> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getimg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Model deprecations

> How models are retired, how the API warns you, and how to migrate before a model stops working.

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](https://getimg.ai/app/developer/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.

```http theme={null}
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](https://www.rfc-editor.org/rfc/rfc9745)) |
| `Sunset` | When the model stops accepting generations, as an HTTP date ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)). 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.

```javascript Node.js theme={null}
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"),
  );
}
```

```python Python theme={null}
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.

```json theme={null}
{
  "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`.

```javascript Node.js theme={null}
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}`,
  );
}
```

```python Python theme={null}
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.

```json theme={null}
{
  "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](https://docs.getimg.ai/guides/media-responses.md).

## Migrate to the replacement

1. Read the replacement with `GET /v2/models/{model}`.
2. 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.
3. Compare its `pricing.rates` with the old model's.
4. Switch the `model` value and test a generation before the sunset date.

> [!TIP]
>
> 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.

## Related pages

* [Models](https://docs.getimg.ai/guides/models.md)
* [Errors](https://docs.getimg.ai/guides/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.