Update gemini/genai doc: models are 2 generations behind (2.5 → 3.1)
Author: kc9611Created Mar 14, 2026Updated Mar 21, 2026
Summary
The gemini/genai Python doc (content/gemini/docs/genai/python/DOC.md) recommends Gemini 2.5 models, but Google has since released Gemini 3.1 (as of March 2026). The doc is ~2 generations behind.
What's wrong
Model recommendations are outdated
| What the doc says | What it should be (March 2026) |
|---|---|
gemini-2.5-flash (General) |
gemini-3-flash-preview |
gemini-2.5-pro (Reasoning) |
gemini-3.1-pro-preview (released Feb 19, 2026) |
gemini-2.0-flash (acceptable) |
gemini-3.1-flash-lite (released March 3, 2026) |
gemini-2.5-flash-image-preview (Image editing) |
gemini-3.1-flash-image |
Deprecated models list is incomplete
The doc only lists 1.5 series as deprecated. The following should also be listed:
- All 2.x models (
gemini-2.0-flash,gemini-2.0-pro) - All 2.5 models (
gemini-2.5-flash,gemini-2.5-pro) gemini-3-pro-preview(shut down March 9, 2026 — users told to migrate to 3.1 Pro)
SDK version is outdated
- Doc says:
1.56.0 - Latest on PyPI:
1.67.0(released March 12, 2026)
What's still correct
- The SDK import pattern (
from google import genai) - Client initialization (
client = genai.Client()) - API call patterns (
client.models.generate_content(...)) - Streaming (
generate_content_stream) - Tool/function calling, structured outputs, system instructions
- Image generation with Imagen, video generation with Veo
- The deprecation of
google-generativeai(legacy SDK)
Suggested changes to content/gemini/docs/genai/python/DOC.md
- Update frontmatter
versionsto1.67.0andupdated-onto current date, bumprevision - Replace model recommendations:
- General →
gemini-3-flash-preview - Reasoning →
gemini-3.1-pro-preview - Cost-efficient →
gemini-3.1-flash-lite
- General →
- Update deprecated models list to include all 2.x and 2.5 series
- Update image editing model to
gemini-3.1-flash-image - Update all code examples to use the new model IDs
References
Source: andrewyng/context-hub