DEV Community

Cover image for Gemini 3.7 Flash to 3.8 Flash: API migration guide
Hassann
Hassann

Posted on Originally published at apidog.com

Gemini 3.7 Flash to 3.8 Flash: API migration guide

Migrating from Gemini 3.7 Flash to Gemini 3.8 Flash: A Practical Checklist

Google shipped Gemini 3.8 Flash on September 2, 2026—three weeks after Gemini 3.7 Flash—with the same introductory price and roughly the same speed. The model ID is gemini-3.8-flash, without a preview suffix, and the model card describes it as “based on Gemini 3.7 Flash.” A plain chat prompt usually needs only a one-line model swap. However, configurations that control thinking, sampling, or tool loops require nine migration checks—two of which can produce errors that 3.7 Flash did not.

Try Apidog today

This checklist is based on Google’s What’s new in Gemini 3.8 Flash page and the Gemini 3 developer guide. The examples cover both the Interactions API, which Google now treats as the primary path, and the legacy generateContent endpoint used by much existing 3.7 Flash code. You can paste the requests into Apidog and test them against the live endpoint before changing production.

Google says 3.8 Flash “works harder” by taking smaller reasoning steps, verifying its work, and calling tools iteratively on complex tasks. That improves capability but can also increase token usage, so migration requires a budget review—not just a configuration diff.

What changes—and what doesn’t

Area Gemini 3.7 Flash Gemini 3.8 Flash
Model ID gemini-3.7-flash gemini-3.8-flash
Context / output 1,048,576 / 65,536 Same
Introductory price through Dec. 31, 2026 $0.75 / $3.75 per 1M tokens Same
Price from Jan. 1, 2027 — $1.50 / $7.50 per 1M tokens for both models
Thinking levels low, medium, high Same; minimal returns a validation error; default is medium
Tokens per task Baseline About 30% more output tokens on average, according to Artificial Analysis
Function results call_id + name Both required and enforced
Support status Fully supported; no deprecation date Current

The pricing rows come from Google’s Gemini API pricing page, where the 3.6, 3.7, and 3.8 Flash rows are identical.

Step 0: Decide whether to migrate

Migration is optional. Google says Gemini 3.7 Flash “remains fully supported,” and no sunset date has been published.

Per-token pricing is unchanged, so the main cost difference is usage. Artificial Analysis measured Gemini 3.8 Flash at high thinking with approximately 48,000 output tokens per task—30% more than 3.7 Flash. At identical rates, that moved the estimated cost per task from $0.40 to $0.58. The index score increased from 56 to 59, while tool-use accuracy on τ³-Banking increased 12 points to 45%.

The trade-off is more capability per task in exchange for more tokens per task. If your workload is short, latency-sensitive, or already passes its evaluations on 3.7 Flash, staying on 3.7 may be reasonable. See the Gemini 3.8 Flash vs. 3.7 Flash comparison for a workload decision matrix.

Step 1: Swap the model ID in both API shapes

Interactions API 

{
  "model": "gemini-3.7-flash",
  "input": "..."
}
Enter fullscreen mode Exit fullscreen mode

Change it to:

{
  "model": "gemini-3.8-flash",
  "input": "..."
}
Enter fullscreen mode Exit fullscreen mode

Legacy generateContent 

POST /v1beta/models/gemini-3.7-flash:generateContent
Enter fullscreen mode Exit fullscreen mode

Change it to:

POST /v1beta/models/gemini-3.8-flash:generateContent
Enter fullscreen mode Exit fullscreen mode

Python SDK 

client.interactions.create(
    model="gemini-3.8-flash",
    input=...,
    generation_config={"thinking_level": "medium"},
)

client.models.generate_content(
    model="gemini-3.8-flash",
    contents=...,
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
Enter fullscreen mode Exit fullscreen mode

If you have not used the Interactions API, the Gemini 3.8 Flash API guide covers both request shapes. The older 3.7 Flash walkthrough covered only generateContent.

The nine-item migration checklist

Work through these in order:

  1. Update thinking_level
  2. Remove sampling parameters
  3. Replace thinking_budget
  4. Remove candidate_count
  5. Include call_id and name in function results
  6. Preserve thought signatures
  7. Increase token budgets where needed
  8. Test media resolution by input type
  9. Remove unsupported image-segmentation paths

1. Map thinking_level: "minimal" to "low"

Gemini 3.8 Flash accepts low, medium, and high. Sending minimal returns a validation error. If you omit the setting, the default is medium.

Gemini 3 Pro defaults to high, so do not copy a Pro configuration without checking the intended behavior.

Before:

{
  "generation_config": {
    "thinking_level": "minimal"
  }
}
Enter fullscreen mode Exit fullscreen mode

After, Interactions API:

{
  "generation_config": {
    "thinking_level": "low"
  }
}
Enter fullscreen mode Exit fullscreen mode

After, legacy API:

{
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "low"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Google’s thinking documentation describes low as the latency-oriented setting and medium as the default for complex code and agentic work. For migration purposes, low is the direct replacement for minimal.

2. Remove temperature, topP, and topK

Google recommends leaving temperature at its default of 1.0 for every Gemini 3 model. Lower values may cause looping or degraded performance.

Many 3.7 Flash configurations still contain values such as temperature: 0.2 from earlier model generations. Delete the sampling parameters instead of tuning them for 3.8 Flash.

Before:

{
  "generationConfig": {
    "temperature": 0.2,
    "topP": 0.9,
    "topK": 40
  }
}
Enter fullscreen mode Exit fullscreen mode

After:

{
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "medium"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

For repeatable JSON, use structured outputs rather than low temperature. Structured outputs are supported on 3.8 Flash and return schema-shaped data without changing sampling behavior.

3. Replace thinking_budget with thinking_level

thinking_budget was an integer token cap. thinking_level is a string enum, and there is no direct arithmetic mapping between them.

Choose based on intent:

  • low for latency-sensitive routes
  • medium for default routes
  • high for the hardest multi-step tasks

Before:

{
  "generationConfig": {
    "thinkingConfig": {
      "thinkingBudget": 4096
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

After:

{
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "low"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Thinking tokens are still billed as output tokens and reported in usageMetadata.thoughtsTokenCount. Cost control now comes from the thinking level plus assertions in your regression tests.

4. Remove candidate_count

Gemini 3 and later do not support multiple candidates. Remove the parameter and any code that accesses candidates[1] or later entries.

Before:

{
  "generationConfig": {
    "candidateCount": 2
  }
}
Enter fullscreen mode Exit fullscreen mode

After:

{
  "generationConfig": {}
}
Enter fullscreen mode Exit fullscreen mode

If you previously sampled several candidates and selected the best one, try a higher thinking level instead. The model performs verification within a single response.

5. Include call_id and name in every function result

This is the second breaking change. Every function result sent to Gemini 3.8 Flash must include both the function call ID and function name.

The Gemini 3 developer guide requires all FunctionResponse objects to include these fields.

Interactions API:

{
  "previous_interaction_id": "<id from the function_call step>",
  "input": [
    {
      "type": "function_result",
      "name": "get_weather",
      "call_id": "<id from the function_call step>",
      "result": [
        {
          "type": "text",
          "text": "{\"temp_c\": 24}"
        }
      ]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

The model’s function_call step provides id, name, and arguments. Copy the ID and name into the function result.

In the legacy shape, the functionResponse part uses a field named id, matching the model’s functionCall ID, alongside name and response.

The Gemini 3.8 Flash function-calling guide shows the complete two-turn loop and explains why 3.8 Flash may call tools more times per task.

6. Preserve thought signatures exactly

Gemini 3 models attach thought signatures to response parts. When constructing the next turn, return every response part unchanged, including signatures and non-text parts.

Do not strip or reserialize signatures. Doing so can degrade continuity on the next step.

The Interactions API handles this automatically when you use server-side state:

{
  "previous_interaction_id": "<interaction-id>"
}
Enter fullscreen mode Exit fullscreen mode

If you set store: false, you must manage the history yourself and return the thought blocks and signatures. With legacy generateContent, your application always owns the history, so audit code that rebuilds contents from a trimmed response.

7. Increase token budgets per route

This change does not produce an error, so it is easy to miss. Artificial Analysis measured approximately 30% more output tokens on average at high thinking. Google also notes that the model can use more tokens on long-running and complex tasks, especially at higher effort levels.

Budget by route:

  • Latency-sensitive: Use low. Artificial Analysis measured about 0.8 minutes and $0.24 per task at low versus 2.5 minutes and $0.58 at high.
  • Default routes: Use medium, measured at approximately $0.41 per task on the same index.
  • Agent loops: Expect more tool-call turns. Cap loops by turn count, not only by token count.

Recheck the 65,536-token output ceiling. A 3.7 Flash prompt that returned 40,000 tokens with thinking may approach the limit on 3.8 Flash. The 3.8 Flash pricing breakdown includes per-task estimates for all three thinking levels.

8. Test media_resolution_high separately for PDFs and video

Gemini 3.8 Flash accepts text, image, video, audio, and PDF input. Media resolution changes token consumption, and the cost differs by media type.

Do not carry a global high-resolution setting from 3.7 Flash without measuring it. Test one representative PDF and one representative video at each resolution, then compare:

usageMetadata.promptTokenCount
Enter fullscreen mode Exit fullscreen mode

A setting that is affordable for a PDF page may be expensive for a long video.

9. Remove image-segmentation calls

Image segmentation is not supported on Gemini 3 models. If an older pipeline routed segmentation through another Gemini model, that path is separate from this migration.

Prompts asking Gemini 3.8 Flash for segmentation masks should be expected to fail rather than return usable masks. The model page also lists image generation, audio generation, and the Live API as unsupported.

Build a regression plan in Apidog

A migration with two breaking changes and a token-usage shift needs repeatable comparisons rather than a one-off curl request. Apidog works well here as an API client and test runner: it sends requests, validates responses, and schedules tests. It does not run the model itself.

Configure the environment

Create a Gemini environment with:

  • GEMINI_API_KEY stored as a secret variable
  • MODEL as an environment variable

Use {{MODEL}} in the generateContent URL and in the Interactions API model field. The same saved requests can then run against either model.

Create golden prompts

Save 10–20 prompts representing your production routes, including:

  • A short chat turn
  • A structured-output extraction
  • A two-turn function call with a mocked tool
  • A representative PDF input
  • A representative video input

Make each prompt a request in a test scenario.

Add assertions

Add at least three assertions per request:

  • The status is 200, and the response matches a JSON schema. For structured-output routes, validate the fields consumed downstream.
  • usageMetadata.thoughtsTokenCount remains below a route-specific ceiling, such as 8,000 for a low-thinking route.
  • usageMetadata.totalTokenCount remains below the route budget.

For function calls, also assert that the call_id sent in the function result equals the ID from the previous step’s function_call.

Compare both models

Duplicate the scenario:

  • Set MODEL to gemini-3.7-flash in one copy.
  • Set MODEL to gemini-3.8-flash in the other.
  • Run both scenarios.

Apidog’s test reports show assertion results and response bodies side by side, making token deltas visible per prompt.

Schedule the test

Turn the 3.8 Flash scenario into a scheduled run so token ceilings are checked daily during rollout. Follow the scheduled API tests guide for setup instructions.

You can also download Apidog and import the request fragments above.

Roll back with a configuration flag

Because Gemini 3.7 Flash remains fully supported and has the same price, rollback is inexpensive. Keep model IDs in configuration rather than hard-coding them:

{
  "gemini_model": "gemini-3.8-flash",
  "gemini_fallback_model": "gemini-3.7-flash"
}
Enter fullscreen mode Exit fullscreen mode

Follow three rules:

  1. Keep one request shape for both models. The migrated shape—no minimal, no sampling parameters, thinking_level instead of thinking_budget, no candidate_count, complete function results, and preserved signatures—is valid on 3.7 Flash too.
  2. Roll out by route. Start with low-thinking latency routes, where the token delta is smallest. Move agent loops last, after side-by-side tests pass for several days.
  3. Monitor tokens as well as errors. A 3.8 Flash regression is more likely to appear as a cost or latency increase than as a 4xx response. Feed token-ceiling assertions into alerting.

FAQ

Does Gemini 3.8 Flash cost more than 3.7 Flash?

Not per token. Both cost $0.75 per 1M input tokens and $3.75 per 1M output tokens through December 31, 2026. Both increase to $1.50 and $7.50 on January 1, 2027.

Per task, 3.8 Flash uses more tokens by design. Artificial Analysis measured approximately 30% more output tokens at high thinking.

What happens if I leave thinking_level: "minimal" in place?

The request fails with a validation error on 3.8 Flash. Replace it with low. The thinking-level documentation explains the remaining levels and how to measure them.

Do I have to use the Interactions API?

No. generateContent is described as legacy but remains fully supported, with no published sunset date.

The Interactions API provides server-side conversation state through previous_interaction_id, which removes much of the thought-signature bookkeeping described in item 6.

Is Gemini 3.7 Flash deprecated?

No. Google says it “remains fully supported” and has not published a deprecation date. That makes a configuration-flag rollback practical.

Can I keep the temperature tuned for 3.7 Flash?

Google recommends leaving temperature at 1.0 for all Gemini 3 models. If you override it on 3.7 Flash, use this migration to remove the override and rerun your evaluations. Use structured outputs when you need deterministic response shapes.

Ship in stages

The code migration is small:

  • One model ID change
  • Four configuration deletions or renames
  • Two function-result fields
  • A thought-signature audit

The time-consuming part is proving that token budgets and latency still hold for every route. Save golden prompts, assert response schemas and token ceilings, compare 3.7 and 3.8 Flash side by side until the numbers stabilize, and switch one route at a time.

If a route regresses, the configuration flag can send it back to 3.7 Flash without another code change.

References

Top comments (0)