DEV Community

Ahab
Ahab

Posted on • Originally published at indieseek.co

Imagen 4 API Shutdown: A Gemini 3.1 Flash Image Migration Checklist

#ai #gemini #api #devtools

Imagen 4 API shutdown: migrate to Gemini 3.1 Flash Image without a blind model-ID swap

Quick answer

Google lists three Imagen 4 Gemini API models for shutdown on August 17, 2026: imagen-4.0-generate-001, imagen-4.0-ultra-generate-001, and imagen-4.0-fast-generate-001. The current deprecations table recommends gemini-3.1-flash-image as their replacement.

Do not ship a model-string-only change. Imagen 4 examples use the dedicated generateImages / :predict contract, while Google's current Gemini 3.1 Flash Image guide uses the Interactions API, response_format, and interaction.output_image. Pricing also changes from fixed per-image tiers to token-based image output. Inventory every old ID, add a separate adapter, replay a fixed image fixture, compare cost per accepted image, canary one traffic lane, and keep the old path disabled but reversible until the shutdown behavior is proven.

Who this is for

This guide is for independent developers and small teams that call Imagen 4 through the Gemini Developer API for product shots, social cards, thumbnails, illustrations, or text-heavy graphics. It is especially relevant when the model name is hidden in a queue worker, environment variable, prompt preset, or fallback chain.

The deadline concerns three Imagen 4 API model IDs, not the existence of Google's entire image-generation product family. If you are also migrating a text or agent model, keep that evaluation separate; the Gemini agent migration checklist uses different quality and economics gates.

What changes at the boundary

Boundary Imagen 4 integration Gemini 3.1 Flash Image integration Migration gate
Model IDs Fast, Standard, and Ultra imagen-4.0-*-001 IDs gemini-3.1-flash-image No old ID remains in code, config, jobs, or saved presets
Request route Dedicated image generation / models/...:predict Current guide uses v1beta/interactions Adapter contract test passes
Output Generated-images collection Convenience property interaction.output_image; complex output may require iterating steps Parser rejects missing or partial image data
Controls Imagen-specific image count, aspect ratio, and size fields response_format controls image-only output, MIME type, aspect ratio, and image size Every production ratio and size is explicit
Economics $0.02 Fast, $0.04 Standard, $0.06 Ultra per image Standard output equivalents: $0.045 at 0.5K, $0.067 at 1K, $0.101 at 2K, $0.151 at 4K, plus applicable input and text/thinking tokens Budget uses accepted-image cost

There is a documentation inconsistency worth recording. On August 17, the deprecations table recommends gemini-3.1-flash-image, while the older Imagen 4 pricing warning still says to migrate to Gemini 2.5 Flash Image. The current image-generation guide centers Gemini 3.1 Flash Image and labels Gemini 2.5 Flash Image a legacy model. Use the deprecations table plus the current guide, verify model availability in your own project, and record the exact model ID; do not let stale page copy choose production behavior.

A seven-step migration

1. Find the real blast radius

Search source, deployment config, queue payloads, fixtures, dashboards, and saved customer presets for all three IDs—not only the Standard model:

rg -n 'imagen-4\.0-(generate|ultra-generate|fast-generate)-001' .
Enter fullscreen mode Exit fullscreen mode

For each match, record owner, traffic share, requested image count, aspect ratio, resolution, latency objective, retry policy, and downstream parser. Historical job payloads can reintroduce an old ID after the main service is patched.

2. Add a new adapter instead of rewriting a string

Keep the old and new request builders separate. Google's current JavaScript example is structurally closer to this:

const interaction = await ai.interactions.create({
  model: "gemini-3.1-flash-image",
  input: prompt,
  response_format: {
    type: "image",
    mime_type: "image/png",
    aspect_ratio: "16:9",
    image_size: "1K"
  }
});

if (!interaction.output_image?.data) throw new Error("missing image output");
Enter fullscreen mode Exit fullscreen mode

Make output-only behavior explicit: the model otherwise defaults to returning both text and image. If your workflow consumes interleaved content, iterate the response steps rather than relying only on the convenience property, which returns the last generated image block.

3. Freeze a paired fixture

Use at least twelve non-sensitive prompts covering your real workload: product object, person, small text, long text, logo-like composition, photorealism, illustration, difficult hands, brand colors, 1:1, 9:16, and 16:9. Store the prompt hash, requested size, seed if supported by the path, latency, HTTP result, output dimensions, moderation result, and human acceptance reason.

Do not accept “looks good” as a gate. Score instruction adherence, text accuracy, subject consistency, composition, artifacts, and downstream crop safety. Generated images still include SynthID; keep your product disclosure accurate and do not misrepresent the result as non-generated media.

4. Recalculate accepted-image economics

The replacement price depends on resolution, input tokens, optional text/thinking output, retries, and rejection rate. Use:

accepted_image_cost =
  (image_output_cost + input_cost + text_or_thinking_cost + retry_cost)
  / accepted_images
Enter fullscreen mode Exit fullscreen mode

A 1K output is listed at an equivalent $0.067 before input and other output tokens. That is not a direct continuation of the old $0.02 / $0.04 / $0.06 tiers. Batch pricing can lower image-output cost, but Google's Batch API trades that for turnaround of up to 24 hours; it is not an interactive fallback.

5. Run failure and shape canaries

Require all of these before traffic moves:

  • one valid prompt returns decodable image bytes with the requested MIME type, ratio, and size;
  • a policy-rejected prompt is classified without an infinite retry;
  • an empty or text-only response fails closed;
  • a timeout retries at most once with the same idempotency/job identity;
  • a multi-image request does not silently change product semantics—the guide warns that the model may not follow an exact requested image count;
  • the old model ID is probed separately and its observed response is recorded, without assuming Google's undocumented cutoff time zone.

6. Canary one reversible lane

Route 1% or one internal tenant through the new adapter. Compare p50/p95 latency, accepted-image rate, retry rate, moderation rate, output bytes, and accepted-image cost with the frozen Imagen 4 baseline. Increase one step at a time only when quality and budget gates pass. Never silently fall back from a rejected or malformed new response to an old model after the deadline; that hides the outage and can double spend.

7. Remove only after terminal proof

When 100% traffic uses the new path, disable old model selection, drain queued jobs containing old IDs, and run the inventory again. Keep the old adapter code for one short rollback window if your release policy permits, but make it unreachable by configuration. Final proof is zero old-ID calls plus successful new jobs—not merely a deployed code diff.

Decision tree 

Does any live or queued job contain an Imagen 4 ID?
  yes -> freeze the job, migrate its request contract, replay the fixture
  no  -> run the repository/config/preset inventory again

Does Gemini 3.1 Flash Image pass quality and accepted-cost gates?
  yes -> canary one lane, then ramp with explicit checkpoints
  no  -> keep traffic stopped or choose another currently supported model

Does the parser see missing, text-only, or interleaved output?
  yes -> fail closed and inspect response steps; do not upload partial output
  no  -> record dimensions, cost, latency, model ID, and acceptance result
Enter fullscreen mode Exit fullscreen mode

Common mistakes

  • Calling the three retired IDs “preview endpoints”; they are the Imagen 4 -001 model IDs, while earlier preview IDs had a different shutdown date.
  • Replacing only model= while leaving the old request route and parser intact.
  • Following the stale replacement sentence on one pricing block without reconciling the current deprecations table and image guide.
  • Comparing list price per request instead of cost per accepted image.
  • Letting default text-plus-image output reach a pipeline that expects image-only bytes.
  • Assuming a requested image count is guaranteed.
  • Deleting the old path before queued jobs and saved presets are drained.

Copyable migration record 

date / project / SDK version / owner:
old IDs found / code-config-queue-preset locations:
new model ID / API route / adapter version:
fixture count / ratios / sizes / acceptance rubric:
quality pass rate / p50-p95 latency / retry rate:
image output cost / total cost / accepted-image cost:
missing-output / policy / timeout / count canaries:
old-ID probe result / observed timestamp and zone:
canary share / ramp checkpoints / rollback trigger:
queued old jobs drained / final inventory result:
decision: blocked | canary | ramp | complete
Enter fullscreen mode Exit fullscreen mode

FAQ

Is Imagen 4 Preview shutting down on August 17?

The August 17 deadline in Google's current table applies to the three Imagen 4 -001 IDs: Standard, Ultra, and Fast. The earlier *-preview-06-06 IDs list February 17, 2026 as their shutdown date. Use the exact ID in your logs and documentation.

Can I just change the model name?

No. The current migration crosses a request/response boundary as well as a model boundary. Add and test a new adapter, explicit output format, parser, error policy, and cost model.

Which replacement should I use?

Google's current deprecations table names gemini-3.1-flash-image. The current image guide also presents it as the general-purpose workhorse. Other supported image models may fit lower-cost or premium workloads, but evaluate them as deliberate alternatives rather than undocumented drop-in replacements.

Sources

Originally published on IndieSeek.

Top comments (0)