Migration to gemini-3.7-flash from the predecessor models named in Google’s current guide is a model-specific request-contract migration, not only a model-name change.
Google instructs applicable migrations from Gemini 3.5 Flash, Gemini 3 Flash Preview, Gemini 3.1 Pro or Gemini 3.6 Flash to remove deprecated sampling controls, replace thinking_budget with thinking_level, remove candidate_count, remove prohibited prefilled model turns and standardize multi-turn conversation on previous_interaction_id. Requirements still vary by model and API surface. Google’s Gemini 3.7 Flash migration guide
As of August 27, 2026, the SDK releases reviewed here are Python google-genai==2.20.0 and JavaScript @google/genai@2.19.0. Recheck the Python package, Python releases, JavaScript package and JavaScript releases before using those values later.
Track the underlying request-contract change in Kingy’s Gemini sampling and turn-validation Radar record. For broader model context, see the Gemini 3.7 Flash review and the Model Economics and Migrations hub.
Scope
This guide’s principal contract is limited to migration to gemini-3.7-flash from source models named in Google’s migration page. The statement that candidate_count is unsupported is documented as a Gemini 3.x baseline, but sampling, thinking and turn rules must not be generalized to another model without its own current primary source. Gemini 3.7 migration checklist
This guide explicitly excludes multi-turn and function-calling flows whose correctness depends on thought-signature preservation. This is an intentional editorial scope boundary: do not apply its history, function-result or streaming instructions to those flows; use Google’s current Thinking guide for thought-signature handling. Operational thought-signature instructions are intentionally outside this article’s supported scope.
| Area | Migration contract |
|---|---|
| Target | gemini-3.7-flash |
| Sampling | Remove temperature, top_p and top_k for the documented migration |
| Thinking | Replace thinking_budget with supported thinking_level; gemini-3.7-flash supports low, medium and high |
| Candidate count | Remove candidate_count |
| Stateful history | Use previous_interaction_id; repeat all required interaction-scoped controls |
| Prefills | Remove synthetic or terminal model prefills, not authentic prior outputs required for history |
| Function results | Preserve the matching function-call ID and name |
| Storage | Interactions store resources by default unless store=false |
Safe migration sequence
1. Remove deprecated sampling controls
For the bound migration, remove temperature, top_p and top_k rather than copying old values forward:
generation_config = {}Do not remove these fields globally from configuration shared with other models until every consumer is identified. Google’s migration checklist
2. Replace thinking_budget
gemini-3.7-flash supports low, medium and high; Google lists medium as its default. Select a level only after evaluating task success, latency and output-token use for the application. Gemini 3.7 thinking levels
generation_config = {
"thinking_level": "medium",
}3. Remove candidate_count
Search for both candidate_count and candidateCount. Google identifies the setting as unsupported for Gemini 3.x. If the application depends on alternative candidates, redesign that behavior explicitly. This guide does not quote an exact error message because Kingy did not independently reproduce one. Google’s migration checklist
4. Remove prohibited prefills without deleting authentic history
Remove synthetic model-authored turns inserted to force a style, format or response prefix. Do not delete authentic model outputs that already occurred. Stateless requests still need the complete, correctly ordered history required by the API; stateful Interactions can carry authentic inputs and outputs through previous_interaction_id. Interactions state management
5. Repeat interaction-scoped controls
Google documents that previous_interaction_id preserves conversation inputs and outputs only. Tools, system_instruction and generation_config apply only to the current interaction and must be supplied again when they should continue. Interactions state management
Safety boundary before running this example: Use only a dedicated non-production project and non-production credentials with synthetic input. Interactions default to store=true, and the stateful continuation shown below depends on the first Interaction being stored. Before execution, select the shortest approved project-storage window, record every created Interaction ID, and define deletion plus cleanup verification after the test. Do not run the example with production credentials, customer data or external tool side effects. Interactions storage and retention
from google import genai
client = genai.Client()
shared_controls = {
"system_instruction": "Answer only from the synthetic deployment fixture.",
"generation_config": {"thinking_level": "medium"},
}
first = client.interactions.create(
model="gemini-3.7-flash",
input="Remember that the synthetic deployment colour is blue.",
**shared_controls,
)
second = client.interactions.create(
model="gemini-3.7-flash",
previous_interaction_id=first.id,
input="What is the synthetic deployment colour?",
**shared_controls,
)This example declares no tools. When tools apply, repeat the exact approved declarations on every applicable interaction. Google currently says custom safety settings are not supported by the Interactions API; an application that depends on them must not silently drop them during migration. Interactions limitations
6. Authorize interaction state by tenant and session
Treat an interaction ID as an opaque reference to stored conversation content. Store its mapping to the authenticated tenant, user, application session, API project and state version on the server. Accept a logical application-session identifier from the client rather than an arbitrary provider interaction ID. Authorize every continuation, retrieval and deletion; fail closed for missing, expired, deleted, cross-tenant or wrong-project mappings.
Keep full interaction IDs out of public URLs, analytics, screenshots and unredacted logs. This ownership contract is an application security control inferred from Google’s documented stored-resource model, not a claim about Google’s internal authorization. How Interactions resources work
7. Make storage and retention an explicit decision
Interactions use store=true by default. As reverified on August 27, 2026, Google documents retention of 55 days for paid-tier interactions and one day for free-tier interactions. Paid projects can configure project-storage deletion windows of 7, 14, 28 or 55 days. store=false prevents later continuation with previous_interaction_id and is incompatible with background execution. Interactions storage and retention
Deletion through the API or AI Studio concerns stored Interaction resources and project storage; Interaction objects are also processed under the applicable terms. Do not present deletion as guaranteed erasure from every processing context. Recheck the current documentation and applicable terms before implementation. Interactions storage and retention
Use store=false for synthetic migration tests that do not require continuation. If continuation itself is being evaluated, use a dedicated non-production project, synthetic content, the shortest approved storage window, an interaction inventory and a cleanup check.
8. Bind function results to calls
For GenerateContent, Google requires FunctionResponse objects in the documented migration to contain the corresponding call ID and function name. The Interactions API uses typed function-call and function-result steps following the same binding principle. Gemini 3.7 migration checklist, Interactions migration guide
During migration testing, use mocked or dry-run tool results only. Validate call ID, function name, result count, duplicate results, unknown calls and multimodal payload placement before submission. Never let a migration test execute an external side effect.
9. Parse typed steps and current streaming events
Use output_text only for simple text output. Applications with tool, multimodal or interleaved output should inspect the current typed steps structure. Earlier Interactions integrations may also need to replace legacy event names with the documented interaction and step lifecycle, including interaction.created, interaction.completed, step.start, step.delta and step.stop. Accumulate streamed function-argument deltas before parsing them. Interactions breaking-changes guide
This guide does not include a version-specific streaming implementation because Kingy has not independently executed one. Use the exact documentation for the SDK version pinned by the application.
Validation and rollback
Use synthetic inputs, non-production credentials, mocked tools, strict request and spend ceilings, and metadata-only telemetry. Verify sampling removal, supported thinking levels, prefill rejection, authentic history replay, interaction-scoped controls, negative cross-tenant authorization, deleted or expired IDs, storage behavior, function-result matching, typed-step parsing and streaming assembly.
Retain the prior model and API path while supported, the previous SDK lockfile, request builder, state mode and response parser. Bind each existing session to its API surface, model, tenant and state version. Switching back to GenerateContent or stateless operation does not translate or delete an Interaction resource. Drain compatible sessions, restart them with explicit state loss or perform a separately reviewed translation using authorized authentic history. Apply the approved project-storage and deletion decision to resources already created.
If the previous model or surface has been shut down, recovery is fix-forward on a supported path rather than rollback.
Testing limitation
Kingy source-reviewed these instructions but did not independently execute the examples, reproduce the candidate_count error, validate a version-specific streaming implementation or test SDK behavior. Treat all code as illustrative and verify it against the pinned SDK in a safe non-production environment.
Operational thought-signature instructions are intentionally omitted as an editorial scope decision; Google documents current stateful and stateless handling in its Thinking guide. As stated in Scope, this article does not cover flows that depend on thought-signature preservation. Consult Google’s current Thinking guide before designing any such flow.