Model deprecations

Models are retired when a provider shuts them down or a newer model replaces them. Every retirement follows the same steps, so you can detect it in code and migrate before anything breaks.

Lifecycle

A model moves through three statuses.

Status	Generations	`GET /v2/models`	`GET /v2/models/{model}`
`active`	Work	Listed	Returned
`deprecated`	Work, with deprecation headers	Listed, with `deprecation`	Returned, with deprecation headers
`retired`	Fail with `400` and `invalid_parameter`	Not listed	Returned, with `status: retired`

A deprecated model keeps working until its sunset date. You get at least 30 days between deprecation and retirement, unless the provider shuts the model down sooner. In that case you get as much notice as the provider gives us. A generation you submit before the sunset date finishes normally, including a video that is still pending at that moment.

How you are notified

Response headers. Every response for a deprecated model carries the headers below.
The models endpoints. status and deprecation show the current state and dates.
The dashboard. The Models page marks deprecated models and shows the sunset date.
This page. The tables below list current and past retirements.

Response headers

Responses from POST /v2/images/generations, POST /v2/videos/generations, and GET /v2/models/{model} carry these headers when the requested model is deprecated.

Deprecation: @1793491200
Sunset: Mon, 01 Feb 2027 00:00:00 GMT
Link: <https://docs.getimg.ai/guides/model-deprecations>; rel="deprecation", </v2/models/seedream-5-pro>; rel="successor-version"

Header	Description
`Deprecation`	When the model was deprecated, as a Unix timestamp prefixed with `@` (RFC 9745)
`Sunset`	When the model stops accepting generations, as an HTTP date (RFC 8594). Omitted when no date is set yet.
`Link`	This page (`rel="deprecation"`) and the replacement model (`rel="successor-version"`), when one is set

The headers are also sent on error responses for a deprecated model, so a failed request still tells you the model is going away. Log a warning when you see Deprecation. That gives you a signal in your own monitoring.

const response = await fetch("https://api.getimg.ai/v2/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GETIMG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ model: "seedream-5-lite", prompt: "A lighthouse at dawn" }),
});

if (response.headers.has("deprecation")) {
  console.warn(
    `Model is deprecated, sunset: ${response.headers.get("sunset") ?? "not set"}`,
    response.headers.get("link"),
  );
}

import os
import requests

response = requests.post(
    "https://api.getimg.ai/v2/images/generations",
    headers={"Authorization": f"Bearer {os.environ['GETIMG_API_KEY']}"},
    json={"model": "seedream-5-lite", "prompt": "A lighthouse at dawn"},
)

if "Deprecation" in response.headers:
    print(
        "Model is deprecated, sunset:",
        response.headers.get("Sunset", "not set"),
        response.headers.get("Link"),
    )

Model fields

GET /v2/models and GET /v2/models/{model} return status and deprecation on every model.

{
  "id": "example-image-model",
  "status": "deprecated",
  "deprecation": {
    "deprecated_at": "2026-11-02T00:00:00.000Z",
    "sunset_at": "2027-02-01T00:00:00.000Z",
    "replacement_model": "seedream-5-pro"
  }
}

Field	Type	Description
`status`	string	`active`, `deprecated`, or `retired`
`deprecation`	object or null	`null` for an active model
`deprecation.deprecated_at`	string	When the model was deprecated
`deprecation.sunset_at`	string or null	When the model stops accepting generations. `null` when no date is set yet.
`deprecation.replacement_model`	string or null	ID of the recommended replacement

To check the models your integration uses, list them and filter on status.

import GetimgAI from "getimg-ai";

const client = new GetimgAI();

const models = await client.models.list();
const deprecated = models.filter((model) => model.status === "deprecated");

for (const model of deprecated) {
  console.log(
    `${model.id} retires on ${model.deprecation.sunset_at}, use ${model.deprecation.replacement_model}`,
  );
}

from getimg import GetimgAI

client = GetimgAI()

models = client.models.list()

for model in models:
    if model.status == "deprecated":
        print(
            f"{model.id} retires on {model.deprecation.sunset_at}, "
            f"use {model.deprecation.replacement_model}"
        )

After retirement

A generation with a retired model returns 400. The message names the retirement date and the replacement.

{
  "error": {
    "message": "Model 'example-image-model' was retired on 2027-02-01. Use 'seedream-5-pro' instead.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "invalid_parameter",
    "doc_url": "https://docs.getimg.ai/guides/model-deprecations"
  }
}

The model disappears from GET /v2/models. GET /v2/models/{model} still returns it with status: retired, so you can read deprecation.replacement_model. Media you already generated with the model is not affected. Download URLs keep working until their usual deletes_at time. See Media responses.

Migrate to the replacement

Read the replacement with GET /v2/models/{model}.
Check the parameters you send against its supported_aspect_ratios, supported_resolutions, supported_durations, supports_sound, and supported_references. A replacement can accept different values.
Compare its pricing.rates with the old model’s.
Switch the model value and test a generation before the sunset date.

Keep model IDs in configuration rather than in code. Then a migration is a config change.

Current deprecations

Model	Deprecated	Sunset	Replacement
`seedance-v1-5-pro`	September 15, 2026	November 11, 2026	`wan-3-0`

Retired models

No models have been retired yet.

Getting started

Generation

Concepts

Lifecycle

How you are notified

Response headers

Model fields

After retirement

Migrate to the replacement

Current deprecations

Retired models

​Lifecycle

​How you are notified

​Response headers

​Model fields

​After retirement

​Migrate to the replacement

​Current deprecations

​Retired models

​Related pages

Lifecycle

How you are notified

Response headers

Model fields

After retirement

Migrate to the replacement

Current deprecations

Retired models

Related pages