Устаревшие модели

Провайдеры периодически снимают модели с обслуживания. У каждой такой модели есть дата снятия, после которой оригинальная модель больше не отвечает.

Чтобы это не ломало работающие интеграции, для части моделей мы заранее назначаем модель-аналог. После даты снятия запросы автоматически выполняются на ней — менять код не нужно.

Как узнать о снятии заранее

Все списки моделей — /v1/models для LLM, /v1/media/models и /api/v2/media/models для медиа — отдают состояние депрекации на каждой модели:

Поля депрекации

Параметр	Тип	Описание
`deprecated`	`boolean`	Дата снятия уже наступила — запросы выполняются на аналоге либо возвращают 410. Пока false, модель работает как обычно.
`deprecated_at`	`string \| null`	Дата и время снятия в формате ISO 8601. Может быть в будущем — это анонс, у вас есть время перейти на другую модель. null — модель не помечена как устаревшая.
`deprecation_redirect_to`	`string \| null`	id модели-аналога, на которой будут выполняться запросы после даты снятия. null — аналога нет, после даты запросы вернут 410.

Пример модели с запланированным снятием:

{
  "id": "claude-4.5-haiku",
  "object": "model",
  "title": "Claude Haiku-4.5",
  "deprecated": false,
  "deprecated_at": "2026-08-27T08:22:18.305Z",
  "deprecation_redirect_to": "claude-4.6-sonnet"
}

Что происходит после даты снятия

Если у модели назначен аналог, запрос выполняется на нём и возвращает обычный 200. О подмене сообщают заголовки ответа:

Заголовки ответа

Параметр	Тип	Описание
`Deprecation`	`string`	Всегда true. Признак того, что запрошенная модель снята с обслуживания.
`Sunset`	`string`	Дата снятия запрошенной модели в формате HTTP-date.
`Warning`	`string`	Код 299 и текст с пояснением: какая модель была запрошена, какая выполнила запрос и по какой считаются деньги.
`x-model-requested`	`string`	id модели, которую вы запросили.
`x-model-served`	`string`	id модели, на которой запрос выполнен фактически.

HTTP/1.1 200 OK
Deprecation: true
Sunset: Mon, 27 Jul 2026 08:04:44 GMT
Warning: 299 - "Model 'claude-3.7-sonnet' was deprecated by the provider and the
  request was served by 'claude-3.5-haiku'. Billing follows the requested model
  'claude-3.7-sonnet'. Update your integration to call 'claude-3.5-haiku' directly."
x-model-requested: claude-3.7-sonnet
x-model-served: claude-3.5-haiku

В теле ответа появляется warnings — массив предупреждений. Подмена приходит одним элементом с кодом DEPRECATED_MODEL:

{
  "warnings": [
    {
      "code": "DEPRECATED_MODEL",
      "message": "Model 'claude-3.7-sonnet' was deprecated by the provider and the request was served by 'claude-3.5-haiku'. Billing follows the requested model 'claude-3.7-sonnet'. Update your integration to call 'claude-3.5-haiku' directly."
    }
  ]
}

Текст совпадает с заголовком Warning, а ветвиться в коде стоит по code — формулировку мы можем поменять. Массив, а не одно поле: со временем ответ может нести несколько предупреждений сразу.

Поле model в теле содержит запрошенную модель — ту, которую вы прислали, а не ту, что выполнила запрос. Так проверки вида «модель в ответе совпадает с моделью в запросе» продолжают работать. Кто выполнил запрос, говорит заголовок x-model-served.

При потоковой передаче warnings приходит только в первом кадре, чтобы не дублировать длинную строку в каждом чанке. model подменяется во всех кадрах.

Транскрипция в OpenAI-совместимом формате. Тело ответа там не наше — его отдаёт провайдер как есть, и оно может быть вообще не JSON (text, srt). warnings вписать некуда, поэтому о подмене говорят только заголовки: они на этом эндпоинте есть.

Повторное чтение задачи (GET /media/tasks/:id, GET /v1/lab/result). Здесь нет ни warnings, ни заголовков подмены: о ней сообщают в момент запроса, а не всю жизнь задачи. По ответу на чтение отличить подменённую задачу от обычной нельзя — model в обоих случаях называет запрошенную модель. Если подмену нужно учитывать в вашей логике, зафиксируйте её при создании: там есть и warnings, и x-model-served.

Если у модели аналога нет, запрос завершается статусом 410 Gone. Формат ответа зависит от API.

Для /v1/chat/completions, /v1/embeddings и OpenAI-совместимого режима транскрибации:

{
  "error": {
    "message": "Model 'gpt-4' is deprecated. See compatible alternatives.",
    "type": "model_deprecated",
    "code": "model_deprecated",
    "param": "model"
  }
}

Для /v1/messages:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Model 'claude-3.7-sonnet' is deprecated. See compatible alternatives."
  }
}

Для /v1/media/create и асинхронного режима /v1/audio/transcriptions — код 15:

{
  "code": 15,
  "message": "Model is deprecated by the provider and is no longer available.",
  "original_id": "flux-old"
}

Какую модель взять взамен, смотрите в списке моделей.

Где это работает

Метод	Переадресация на аналог	Ошибка 410 без аналога
`POST /v1/chat/completions`	да	да
`POST /v1/embeddings`	да	да
`POST /v1/messages`	да	да
`POST /v1/media/create`	да	да
`POST /v1/audio/transcriptions`	да	да
`POST /v1/media/generate`	нет	нет
`POST /api/v2/media/tasks`	да	да
`POST /api/v2/media/price`	да	да

В актуальном Creative Lab API о подмене сообщают и заголовки ответа, и массив warnings в теле — но только в ответе на создание задачи. Ни в GET /api/v2/media/tasks/:id, ни в webhook их нет: подмена относится к запросу, а не ко всей жизни задачи.

Поле model в объекте задачи — это запрошенная модель, одинаково при создании, при чтении и в webhook. Объект всегда называет то, что вы прислали; какая модель его выполнила, видно по заголовку x-model-served в ответе на создание.

Расчёт цены (POST /media/price) подменяет модель так же, как создание задачи, — иначе названная цена разошлась бы со списанием. Ошибка без аналога — 410 с code: 21 и original_id в теле.