Gemini 2.5 Pro and Flash Retirement: API Migration Guide Before 1 December 2026

Last updated: 9 November 2026

What changes on 1 December 2026

Key dates:

• 2 November 2026: Google published the deprecation in the Gemini API release notes.
• 1 December 2026: rerouting begins.
• 31 December 2026: end of the current Gemini 3.8 Flash price.
• 1 January 2027: Gemini 3.8 Flash prices double.

New projects cannot start on the deprecated models; API access is limited to existing users who have used them recently.

Price changes

Gemini 2.5 Pro charged more above 200,000 tokens ($2.50 input, $15.00 output). Gemini 3.8 Flash has no long-context surcharge, so long-context workloads may get cheaper.

Thinking tokens count as output, so real costs depend on the thinking level you choose. See Gemini API pricing.

Breaking changes to fix

1. Thinking settings

thinking_level replaces thinking_budget. Gemini 3.8 Flash accepts low, medium and high, and returns an error for minimal. Gemini 3.5 Flash-Lite defaults to minimal.

# Before (Gemini 2.5)
config = {"thinking_config": {"thinking_budget": 1024}}

# After (Gemini 3.8 Flash)
config = {"thinking_config": {"thinking_level": "low"}}

2. Sampling parameters

temperature, top_p and top_k are deprecated and ignored, and Google says they will return HTTP 400 errors in future generations. candidate_count is not supported in Gemini 3 and later. Remove them from your requests.

3. Prefilled model turns

A request that ends with a non-empty model turn, a technique some developers use to force an output format, now returns HTTP 400. Use system_instruction or structured outputs instead.

4. Function calling

• Thought signatures must be preserved between turns.
• Multimodal assets go inside the function response payload.
• Malformed_Function_Call errors can occur if the model emits text before a tool call. Handle this in your code.

Step-by-step migration checklist

1. Inventory usage. Search your code and configuration for gemini-2.5-pro and gemini-2.5-flash, including in no-code tools and plugins.
2. Choose targets. Usually Gemini 3.8 Flash for 2.5 Pro workloads and Gemini 3.5 Flash-Lite for 2.5 Flash, or a different model if quality needs it.
3. Update model strings in a test branch.
4. Replace thinking settings with thinking_level.
5. Remove sampling parameters and candidate_count.
6. Remove prefilled model turns. Use system instructions or structured outputs.
7. Update function-calling code for thought signatures, payload format and malformed call handling.
8. Run an evaluation set of real prompts and compare quality.
9. Measure cost per request, including thinking tokens, at December and January prices.
10. Deploy before 1 December and monitor errors and costs.

Choosing the right thinking level

Start low and raise the level only where quality suffers. Higher levels cost more because thinking tokens are billed as output.

Cost example

A support workload of 20,000 requests a day, previously on Gemini 2.5 Pro, was estimated in one analysis to cost about $9,300 a month, falling to about $4,500 in December on Gemini 3.8 Flash and rising to about $9,000 from January. Those figures assume the same output tokens, which will not hold exactly because thinking behaviour differs. Run your own numbers. See how to estimate AI API costs.

Vertex AI users

This notice covers the Gemini Developer API. Vertex AI has its own model lifecycle documentation. If you use Gemini through Vertex AI, check Google Cloud’s model versions page for your dates rather than assuming the same schedule.

No-code tools and plugins

Many WordPress plugins, automation tools and chatbots let you pick a Gemini model by name. If they are set to gemini-2.5-pro or gemini-2.5-flash, they will be rerouted too. Check settings in tools such as n8n, Zapier, Make and AI plugins, and update to a supported model. See AI WordPress plugins and Zapier vs Make vs n8n.

Other model retirements to plan for

• OpenAI retired o1 and o1-pro from its API on 23 October 2026, and GPT-4o, GPT-4o mini, GPT-4.1 and GPT-4.1 mini leave the API on 14 January 2027. See GPT-4o API retirement.
• Gemini 2.5 Pro was also deprecated in GitHub Copilot earlier in 2026.

A model inventory and a regular review of provider deprecation pages saves emergency migrations.

A full before-and-after request example

Here is a simplified example of a request that would need changes. It uses the Google Gen AI SDK for Python; adapt it to your language and SDK version.

# Before: Gemini 2.5 Pro with old settings
from google import genai
client = genai.Client()

resp = client.models.generate_content(
    model="gemini-2.5-pro",
    contents=[
        {"role": "user", "parts": [{"text": "Classify this ticket: ..."}]},
        {"role": "model", "parts": [{"text": "{\"category\": \""}]},  # prefilled turn
    ],
    config={
        "temperature": 0.2,
        "top_p": 0.9,
        "thinking_config": {"thinking_budget": 512},
    },
)

# After: Gemini 3.8 Flash
resp = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Classify this ticket: ...",
    config={
        "system_instruction": "Reply only with JSON: {\"category\": string}",
        "response_mime_type": "application/json",
        "thinking_config": {"thinking_level": "low"},
    },
)

The changes: a new model string, the prefilled model turn replaced with a system instruction and structured output, sampling parameters removed, and thinking_budget replaced with thinking_level. Check the current SDK documentation for exact parameter names in your version.

Testing plan before you switch

1. Build an evaluation set of 50 to 200 real requests with known good answers.
2. Run old and new models side by side and compare outputs automatically where possible, for example by checking JSON validity and categories.
3. Have a person review a sample of free-text answers for tone and accuracy.
4. Measure latency at realistic concurrency.
5. Measure cost per request, including thinking tokens, at both December and January prices.
6. Test error handling for malformed function calls and HTTP 400 responses.
7. Roll out gradually, for example 10% of traffic first, then 50%, then 100%.

Monitoring after migration

• Error rates by status code, especially new HTTP 400 errors.
• Token usage by type: input, output and thinking.
• Quality signals such as user ratings, escalation rates or validation failures.
• Cost per day with an alert threshold, especially around 1 January 2027 when prices change.

Cutting costs on the new models

• Use the lowest thinking level that meets your quality bar.
• Cache repeated context where the API supports it. See prompt caching explained.
• Batch non-urgent work for lower prices. See batch API savings.
• Route simple tasks to Flash-Lite and keep Flash for harder ones. See model routing explained.
• Trim prompts by removing repeated instructions and unnecessary examples. See how to reduce token usage.

Migration checklist for non-developers

If you use Gemini through a plugin, chatbot builder or automation tool rather than code:

1. List every tool where you entered a Gemini API key.
2. Open each tool’s settings and check the selected model.
3. If it says Gemini 2.5 Pro or 2.5 Flash, switch to a current model offered by the tool.
4. Run a few typical requests and check the answers.
5. Ask the tool’s support team whether they handle the parameter changes automatically.
6. Check your Google AI Studio billing page in December and January for unexpected changes.

Frequently asked questions