How to use the Gemini 3.8 Flash API: Interactions API, thinking levels, and your first call in Apidog

Google released Gemini 3.8 Flash on September 2, 2026, and the API model ID is the plain string gemini-3.8-flash, with no preview suffix. It keeps the 3.7 Flash intro price of $0.75 per million input tokens and $3.75 per million output tokens through December 31, 2026, and Google describes it as a model that “works harder”: it takes more reasoning steps and calls tools more often on complex tasks, which shows up in your token bill.

This guide covers the full path to a working integration: getting a key in AI Studio, sending a first request through the Interactions API (Google’s primary API for Gemini 3.x now), the legacy generateContent equivalent most existing code still uses, where thinking_level goes in each, streaming, and how to read thoughtsTokenCount so thinking cost never surprises you. Every call is plain HTTP with JSON, so you can build and check each one in Apidog before it goes into application code.

For the model overview, benchmarks, and what changed, start with what Gemini 3.8 Flash is. Google’s launch post has the official framing.

Gemini 3.8 Flash API at a glance

Two details stand out before you write code. The default thinking level is medium, not high as on Gemini 3 Pro. And thinking tokens are billed at the output rate on the official pricing page, so the level you pick is a cost decision as much as a quality one. The pricing breakdown works through the per-task numbers.

Step 1: Get an API key in AI Studio

Open Google AI Studio, sign in with a Google account, and create an API key from the key page. The key works on the free tier straight away, with rate limits and the caveat that Google says free-tier data is “used to improve our products”. Link a billing account to move to Tier 1 for production limits.

Export the key instead of pasting it into code:

export GEMINI_API_KEY="AIza..."

The official Python SDK reads GEMINI_API_KEY from the environment, so genai.Client() needs no arguments. Install it with pip install google-genai.

Step 2: Your first call with the Interactions API

Google now treats the Interactions API as the primary way to call Gemini 3.x models. The request is one JSON object: the model, an input, and an optional generation_config where thinking_level lives.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain HTTP caching in 3 sentences.",
    "generation_config": {"thinking_level": "medium"}
  }'

The response is a list of execution steps instead of a single message. Model thoughts and tool calls appear as steps, and the final step is model_output, which holds the text. In Python the SDK flattens this for you:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain HTTP caching in 3 sentences.",
    generation_config={"thinking_level": "medium"},
)

print(interaction.output_text)

Leave temperature, top_p, and top_k out. Google’s guidance for every Gemini 3 model is to keep temperature at its default of 1.0, because lowering it “may cause looping or degraded performance”. If you copied a config from an older model, that is the first line to delete.

Step 3: Multi-turn with previous_interaction_id

The Interactions API keeps conversation state on the server by default. To continue a conversation, send the previous response’s id as previous_interaction_id along with only the new user input. You don’t resend the history.

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    input="Now give one example of a Cache-Control header.",
    previous_interaction_id=interaction.id,
)
print(follow_up.output_text)

If your compliance rules forbid server-side storage, set store: false. The trade-off is that you then manage state yourself, including sending the model’s thought blocks and thought signatures back exactly as you received them on every turn. That is the same rule that trips up tool use, covered in the function calling guide for 3.8 Flash.

Step 4: The legacy generateContent path

Most Gemini code in production still calls generateContent. Google calls it legacy, but it “remains fully supported” with no sunset date, so you don’t have to rewrite anything today. Our Gemini 3.7 Flash API guide covered only this path; the shape is identical for 3.8 Flash, and the thinking setting sits in a different place than it does on Interactions.

In generateContent, the level goes under generationConfig.thinkingConfig.thinkingLevel, in camelCase:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Explain HTTP caching in 3 sentences."}]}],
    "generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
  }'

The Python equivalent uses typed config objects:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain HTTP caching in 3 sentences.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
print(response.text)

If you’re coming from a config that used thinking_budget as an integer, replace it with the string enum. candidate_count is also gone on Gemini 3 and later. The full checklist, with before-and-after JSON for each change, is in the 3.7 to 3.8 Flash migration guide.

Here is the same set of concerns side by side, so you can translate between the two APIs without re-reading both docs:

Step 5: Streaming and reading the thinking cost

For chat interfaces, swap the method name for streamGenerateContent and add ?alt=sse to get server-sent events, one partial candidates chunk per event:

curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"List three HTTP caching headers."}]}]}'

Streaming or not, every generateContent response ends with a usageMetadata object. Read it on every call:

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}

thoughtsTokenCount is the number to watch on 3.8 Flash. Thinking tokens are billed as output tokens at $3.75 per million during the intro period, and Google states the model “might use more tokens to maximize performance, especially at higher effort levels”. Artificial Analysis measured about 48k output tokens per task on its index run at high, 30% more than 3.7 Flash, which pushed cost per task from $0.40 to $0.58 at unchanged per-token prices. Their medium and low runs came in at $0.41 and $0.24 per task. The thinking levels guide turns those numbers into a per-route strategy.

To see what the model reasoned about, add "includeThoughts": true inside thinkingConfig. Thought summaries come back as parts flagged with "thought": true; skip those when you assemble the visible answer.

Errors you will hit in the first hour

thinking_level: "minimal" fails validation. Gemini 3.8 Flash supports only low, medium, and high. Sending minimal returns a 400 INVALID_ARGUMENT with the message “Thinking level MINIMAL is not supported for this model. Please retry with other thinking level.” (verified with a live call on September 3, 2026), and the fix is a one-word change to low. Older 3.x configs and copied snippets are the usual source.

429 means you hit your tier’s limit, not a bug. The rate limits page explains the tiers: the free tier is rate-limited, Tier 1 unlocks when you link a billing account, Tier 2 needs $100 of spend plus three days, and Tier 3 needs $1,000 plus 30 days. Per-model requests-per-minute and tokens-per-minute figures are only displayed on the AI Studio rate-limit page for your account, so check there instead of trusting a number from a blog post. On a 429, back off and retry; on repeated 429s at low volume, upgrade the tier. For offline jobs, the Batch API is the better fix: it runs at 50% off ($0.375 / $1.875 per million tokens during the intro period) and has its own enqueued-token limits of 3M at Tier 1, 400M at Tier 2, and 1B at Tier 3. The Gemini batch mode guide shows the request shape.

Missing call_id on a function result. If you use tools, every function_result (Interactions) must carry both call_id and name on 3.8 Flash, and every legacy functionResponse must carry the matching id plus name. Omitting either fails the turn.

Test both endpoints in Apidog before they ship

Once both requests work from the terminal, move them into a place where the whole team can run them. Download Apidog, create a project, and add the two endpoints above as saved requests. Four habits pay off:

• Keep the key out of the request. Add GEMINI_API_KEY as an environment variable and reference it as {{GEMINI_API_KEY}} in the x-goog-api-key header. The saved request never contains the secret, and switching between a free-tier key and a billed key is one environment change.
• Assert on status and on token usage. Add an assertion that the status is 200, then a JSON path assertion that usageMetadata.thoughtsTokenCount stays under a ceiling you choose per prompt. The ceiling is your cost regression alarm: if a prompt update or a silent model change pushes thinking tokens up, the test fails before the invoice does. The SSE testing guide covers the streaming variant, which Apidog renders as a merged event stream instead of raw chunks.
• Send the same prompt at all three levels. Duplicate the request with low, medium, and high, and compare thoughtsTokenCount and response time side by side. That gives you real numbers for your prompts instead of index averages.
• Schedule it. Turn the requests into a test scenario and run it on a schedule, so a rate-limit change, a validation change like the minimal removal, or a token spike shows up in a report, not in production. How to schedule API tests in Apidog walks through the setup.

Apidog does not run the model or replace the SDK. It gives you a saved, shareable, assertable version of the HTTP calls, which is the part most teams skip until something breaks.

FAQ

Which endpoint should new projects use? The Interactions API. Google calls generateContent legacy, and it is still fully supported, but new features land on Interactions first and server-side state makes multi-turn code shorter. Keep generateContent for existing services until you have a reason to migrate.

Do I need a paid account to call Gemini 3.8 Flash? No. A free AI Studio key works, with rate limits and Google’s data-use terms. The free-usage guide lists what the free tier will and won’t give you, including the fact that the Gemini app requires an AI Pro or Ultra plan for 3.8 Flash.

Is 3.8 Flash slower than 3.7 Flash? Per token, no. Google’s Logan Kilpatrick said it is about the same speed, and Artificial Analysis measured roughly 300 output tokens per second. Per task it takes longer at high (2.5 minutes versus 2.2 in their runs) because it generates more tokens.

Can I keep calling Gemini 3.7 Flash? Yes. Google says 3.7 Flash “remains fully supported” and has published no deprecation date. If the extra token spend on 3.8 Flash doesn’t buy you anything on your workload, staying put is a valid choice.

Does 3.8 Flash support the Live API or image generation? No. It outputs text only. Audio generation, image generation, and the Live API aren’t supported on this model.

Where to go next

You now have two working call paths, a multi-turn pattern, and a token-usage check. From here, wire up tools with the function calling guide, decide your per-route levels with the thinking levels post, and if you’re still deciding whether to move at all, the 3.8 vs 3.7 Flash comparison lays out the trade. Keep the Apidog scenario running so cost drift shows up as a failed test.