Gemini Model Version Suffixes: -latest, -001 and Stable Names

gemini-2.0-flash and gemini-2.0-flash-001 are not the same request. One names a specific set of weights that will never change; the other names whichever set of weights Google currently considers the stable release. The difference is invisible until the day it is not.

Anatomy of a model string

Google’s model documentation describes the naming pattern as model, generation, variation and version:

gemini - 2.0 - flash - 001
   |       |      |      |
   |       |      |      +--  version:     a stable snapshot
   |       |      +---------  variation:   flash, pro, flash-lite
   |       +----------------  generation:  1.5, 2.0, 2.5
   +------------------------  model family

The version segment is the one that carries meaning about stability, and it takes several shapes. Everything else is a description of which model you want; the suffix is a statement about how much it is allowed to change.

The four forms and what each promises

• Pinned stable — gemini-2.0-flash-001. A specific snapshot. The weights behind this string do not change. Google may retire it, with notice, but it will not quietly become something else. This is the only form that offers reproducibility.
• Latest stable alias — gemini-2.0-flash, with no version suffix. Points at the most recent stable snapshot in that variation, and is repointed when a new one ships. Your requests move to new weights without any change on your side.
• The -latest suffix — gemini-1.5-pro-latest. The 1.5-era spelling of the same idea: always the newest version, explicitly labelled as such. Later generations largely dropped it in favour of the bare name.
• Preview and experimental — gemini-2.5-flash-preview-05-20, gemini-2.0-flash-exp. Not for production. Preview builds carry a date and are replaced; experimental builds can change or disappear with little notice, and are explicitly documented as unsuitable for production traffic. The date in a preview name is not a knowledge cutoff—it is a build date, and confusing the two is common enough to be worth stating.

Pinned against alias, side by side

The two requests differ by four characters and by the guarantee they carry:

Pinned — reproducible, retires on a published date
POST .../v1beta/models/gemini-2.0-flash-001:generateContent

Alias — always current, changes underneath you
POST .../v1beta/models/gemini-2.0-flash:generateContent

What actually happens on the day the alias moves is worth being concrete about, because “the model changed” sounds abstract and the observable effects are not:

• Tokenisation of the same prompt can differ, so your input token counts and therefore your bill shift slightly with no change to your traffic.
• Formatting habits change. A new snapshot may prefer markdown headings where the old one used plain paragraphs, or emit a leading acknowledgement it previously omitted. Any downstream parsing built on the old habits breaks.
• Prompt-specific tuning stops applying. Few-shot examples and phrasings that were selected against one snapshot are not guaranteed to be optimal for the next.
• Your evaluation results describe a model you are no longer calling. This is the one that matters. A quality bar established on Monday is not evidence about Wednesday’s weights.

None of that is Google behaving badly. It is the documented behaviour of an alias, chosen by whoever wrote the model string.

modelVersion tells you what served it

Every response carries a modelVersion field naming what actually ran. This is the fact that turns an alias from an invisible risk into a visible one:

{
  "candidates": [ ... ],
  "usageMetadata": { ... },
  "modelVersion": "gemini-2.0-flash-001"
}

Log it on every request, alongside your request id. Two things become possible at once: you can answer “did the model change on the day the complaints started?” from your own data rather than from a changelog, and you can detect an alias having moved within minutes instead of at the next investigation. It is one string per log line and it is the highest-value field in the response for operational purposes.

The models endpoint lists what is currently available, which is the other half of the same discipline:

GET https://generativelanguage.googleapis.com/v1beta/models
x-goog-api-key: $GEMINI_API_KEY

The response enumerates every model your key can call, each with its input and output limits and supported methods. Diffing that listing on a schedule tells you a new snapshot exists before an alias moves you onto it.

What a pinned string does not pin

Pinning fixes the weights. It is worth being precise about what it does not fix, because a team that believes a pinned version guarantees identical behaviour will eventually be wrong in a way that costs a day of investigation.

• Sampling is still stochastic. The same pinned model with the same prompt returns different text on two calls unless you have pinned the sampling too. Temperature, top-p and top-k are request parameters, not model properties, and the Gemini API has no seed guarantee that makes a non-zero temperature reproducible. If you want repeatability, you need a pinned version and a temperature of zero, and even then the guarantee is near-determinism rather than a promise.
• Safety filters are not part of the weights. Classifiers, blocklists and policy filters are platform components that are updated independently. A pinned model can begin blocking a prompt it previously answered, and nothing about the model string changed.
• Serving infrastructure changes. Latency, throughput and quota behaviour are properties of how the model is served, not of the checkpoint. A pinned version can get faster, slower, or newly rate-limited.
• Defaults can move. Anything you do not set explicitly is filled in by the API, and an API default is not part of the model version. Set the parameters you care about rather than relying on what they happen to be.

The honest summary is that pinning removes one large source of variation and leaves several smaller ones. That is still worth doing — a weight change is the variation most likely to be large and least likely to be announced in a way you notice — but it makes the evaluation set in the next section a requirement rather than a nicety. Pinning without measurement gives you a stable input to a system whose output you are still not watching.

Which form to use where

1. Production: pin. Use the versioned stable string. Put it in configuration, not in code, so upgrading is a deploy of a value rather than a code change.
2. Keep an evaluation set that runs against both. The pinned version you are serving and the alias you would move to. The comparison is the entire justification for pinning: without it you have delayed a change you cannot evaluate.
3. Development and prototyping: alias is fine. Riding the latest stable is what you want when nothing depends on the output being the same tomorrow.
4. Never pin to preview or experimental. A dated preview string looks pinned and is not—it is a build with a short life, and it will be withdrawn rather than supported.
5. Track retirement dates for anything pinned. A pinned version is a commitment in both directions: it will not change, and it will eventually stop existing. See the model lifecycle and retirement schedule.

The knowledge cutoff is a property of the weights, so it is also attached to the version rather than to the family name—another reason a pinned string is the one that describes a known quantity. That is covered in the knowledge cutoff page.