Gemini 3.1 Pro API: Long Context, Tools and Cost

You have a 300,000-token script bible for a season of an adult romance series and one question: where do the scenes contradict the character sheets? Gemini 3.1 Pro Preview on SpicyAPI can read the whole thing in one call, but its input rate doubles after 200,000 tokens and its output rate rises by 50%. Stream a large request so it does not hit the non-streaming timeout.

Gemini 3.1 Pro Preview (google/gemini-3.1-pro-preview/chat) takes up to 1,000,000 input tokens, accepts text and image_url parts (not PDF, video or audio parts), supports tools and JSON output, and replies with up to 32,768 tokens. Long-context rates start when total input exceeds 200,000 tokens and apply to the whole request.

Limits and rates

Rates depend on total input tokens: compare the standard and long-context billing tiers.

Keep temperature at the default. Google recommends it for Gemini 3 models, and lower values can make the model loop. Use response_format and the system message to shape output instead.

What a call actually costs

Cost = input tokens x input rate + output tokens x output rate, with the tier chosen by total input (cached tokens count toward it). The examples use uncached input and 4,000 total output tokens:

Reasoning tokens are billed as output and share the max_tokens budget. At higher reasoning effort, leave room above the visible answer you need; a 4,000-token budget does not promise 4,000 tokens of visible text.

One extra token above 200,000 nearly doubles the call, so trimming 5,000 tokens of old correspondence from a 203,000-token packet saves about 50%.

Three things multiply that number:

• Every tool round resends the packet. A tool loop of three rounds over a 250,000-token packet bills about $0.90 of input per round, $2.70 in all, before output.
• Cached tokens are cheaper but not controllable here. The cached rate ($0.36 above the threshold) applies to input served from cache. For example, 300,000 cached plus 5,000 new tokens and 4,000 output costs about $0.19, against $1.16 uncached. The Gemini-format cachedContent field is rejected on this route, so budget uncached and check the settled cost after the first run.
• The balance hold uses your full max_tokens. Before a text request runs, the platform holds the input plus the full max_tokens at the model's price: roughly $4.13 for 1,000,000 input tokens and 32,768 output. Read the error code: 40201 means insufficient balance for the hold; 40202 means a spend cap. Lower an excessive output budget for the former, and inspect key/workspace caps for the latter. Public image URLs also make the hold cover the whole input limit; uploaded or inline images use a fixed image allowance instead.

After the first call, read the X-Spicy-Task-Id response header and look the task up: its cost is final once settled is true. Use that, and the streamed usage, to calibrate every later estimate.

Should the whole packet go in?

Send the whole packet when the answer depends on relationships across it: a continuity audit across a season, a "what changed" question over a full spec set, a conflict search between scripts and character sheets. Send a slice when the question touches one scene or one character. A question about Mara's prop in scene 18 needs the character sheet and scenes 12 and 18, not the season.

A chat app's long-memory behavior may differ from this endpoint: the application may retrieve selected passages or summarize old turns, while the API sees only the messages sent with the request.

A large input window does not guarantee that every detail will be retrieved. Finding several scattered facts is harder than locating one, and older drafts can compete with the current version. The price threshold is not an accuracy boundary. For a focused audit:

• Split a season into arcs of up to 150,000 tokens and audit each against the same character sheets.
• Put the question and output rules last, after all the material, as Google recommends for long prompts.
• Label every chunk (SCRIPT_V3 / scene 12) and require answers to cite only supplied labels. Then check each cited label exists in your packet.
• Ask for conflicts and locations, not rewrites. A 32,768-token reply cannot hold a rewritten season anyway.
• Keep superseded drafts out. Two versions of scene 12 in one packet is how an old prop gets cited as current.

The same budgeting logic, with different rates, is worked through in the Claude Sonnet 4.6 cost guide and the Claude Opus long-document guide.

Prepare a text packet

The route accepts text and image_url parts. For continuity checks across a scanned script, OCR gives you searchable text and stable scene labels: correct damaged names and scene numbers before building the packet. A PDF URL pasted into a text message is not read as a document. Export the script, character notes and shot list as text with stable labels:

CHARACTERS_V2
Mara: 32, photographer. Keeps a copper thermos with a blue band.
Jon: 35, composer. Owns the red leather case.

SCRIPT_V3 / scene 12
Mara puts the thermos on the railway bench. Jon carries the case.

SCRIPT_V3 / scene 18
Jon offers Mara the thermos.

Four English characters per token is a rough screening estimate, not a way to price a request at the boundary: code, names and non-English text tokenize differently. Leave substantial headroom below 200,000, include the system prompt and tool definitions in your estimate, and use the returned usage to compare the actual count.

Turn the finding into a scene change

In this packet, scene 12 last locates the thermos with Mara, while scene 18 gives it to Jon without a handoff. A useful answer identifies that gap and offers a choice:

• Show Jon retrieving it before scene 18 if the beat should show attentiveness.
• Have Mara retrieve it herself if the scene should preserve distance between them.

Choose the relationship beat, then ask for one line implementing it. The model's report helps locate the gap; the author still decides what the action means. The audit should not invent an intervening scene and cite it as source material. For a series bible, the same approach catches scenes that assume a reconciliation before the script shows it: ask for the last established relationship state, the first contradictory scene and the missing transition.

Try it in Playground first

1. Open Gemini 3.1 Pro Preview and switch to Playground.
2. Paste CHARACTERSV2 and the two SCRIPTV3 scenes. Ask where the thermos changes hands without a shown transfer.
3. Choose whether Jon or Mara retrieves it, then request one line that establishes that beat.

Send it streamed

Set SPICY_API_KEY and send the same scene packet from your app. Streaming avoids the roughly 100-second non-streaming edge cutoff; implementation details are in the chat guide.

INTENT_KEY=$(uuidgen)
curl --fail-with-body -sN --max-time 600 https://api.spicyapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $INTENT_KEY" \
  -D reply.headers -o reply.sse \
  -d '{
    "model": "google/gemini-3.1-pro-preview/chat",
    "stream": true,
    "stream_options": {"include_usage": true},
    "reasoning_effort": "low",
    "max_tokens": 4000,
    "response_format": {"type": "json_object"},
    "messages": [
      {"role": "system", "content": "Return JSON with conflicts and suggested_fixes arrays. Cite only supplied scene labels. Do not invent missing scenes."},
      {"role": "user", "content": "Fictional adults: Mara, 32, and Jon, 35. SCRIPT_V3 / scene 12: Mara leaves her blue-banded copper thermos on the railway bench. Jon carries his red case. SCRIPT_V3 / scene 18: Jon hands Mara the thermos. Identify any missing prop handoff."}
    ]
  }'

Add a tool only when information is outside the packet

Keep a character lookup outside the prompt when the canonical record changes frequently. Give the model a narrow read-only function, such as get_character, and let the application return that record. Cap the number of turns: four rounds over the same large packet can cost four input reads. For a fixed two-scene audit, putting the facts in the prompt is simpler and cheaper.

Google's native Search and Maps grounding are separate integrations; this chat route uses functions your application executes. The chat recipes show the complete tool loop.

Let an Agent prepare the call

For repeated continuity audits, ask your coding Agent to use the SpicyAPI Skill: “Read google/gemini-3.1-pro-preview/chat, then adapt the example to my input; show the request before running it.” The CLI lookup is spicyapi models get google/gemini-3.1-pro-preview/chat --json; the MCP lookup is spicyapi_model_get with model: "google/gemini-3.1-pro-preview/chat". Chat calls use a compatible client or the chat API; the media task commands do not generate chat replies.

Adult-content projects

Script indexing, continuity audits and production notes are a good fit. Explicit prose is less reliable: SpicyAPI adds no content filter to this route, but the model can decline or soften a request. In our September 2026 tests, written L3-level content completed in full in 1 of 3 requests, and intimate-scene writing in 4 of 9. For the intimate-scene tests, fiction framing within the request completed 3 of 3, a system prompt alone 1 of 3, and direct requests 0 of 3. A fiction request gives this workflow a better starting point than relying on the system message alone, but choose another model when dependable explicit prose is the main deliverable. The Gemini 3.1 Pro review has the detail.

Common failures

Use the model page for the current rates and to try the route in the playground. It is a preview model, so decide which model takes over if it changes before it carries production traffic.