Media API использует те же API-ключи, лимиты, PII-маскирование и учёт стоимости, что и текстовый шлюз. Для запуска нужна область gateway:write, а модель должна поддерживать соответствующий API surface — images или videos.

Как найти подходящую модель

Публичный каталог можно фильтровать по API surface. Поля supported_parameters, media_capabilities и media_pricing показывают поддерживаемые параметры и схему цены.

curl -s "https://api.kodikrouter.ru/v1/catalog/models?api_surfaces=images&limit=100" \
  | jq '.items[] | {id, supported_parameters, media_capabilities, media_pricing}'

Изображения: POST /v1/images/generations

Генерация изображения синхронная: соединение остаётся открытым, пока провайдер не вернёт результат. Ответ содержит base64 в data[].b64_json и блок usage. Сохраните base64 на клиенте как обычный файл.

curl --fail-with-body -sS \
  -X POST https://api.kodikrouter.ru/v1/images/generations \
  -H "Authorization: Bearer $KODIK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-moscow-001" \
  -o image.json \
  -d '{
    "model": "qwen/qwen-image-3-pro",
    "prompt": "A cinematic view of Moscow at blue hour, photorealistic",
    "size": "1024x1024",
    "n": 1,
    "response_format": "b64_json"
  }'

jq -r '.data[0].b64_json' image.json | base64 --decode > generated.png

Параметры изображения

Пример ответа изображения

{
  "created": 0,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA...",
      "media_type": "image/png"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 7291,
    "total_tokens": 7305,
    "cost": 0.045
  }
}

Видео: POST /v1/videos

Видео создаётся асинхронно. Первый запрос возвращает 202 Accepted, локальный id задачи и polling_url. Опрашивайте этот URL до status: completed, затем скачайте бинарный файл через content_url.

curl --fail-with-body -sS \
  -X POST https://api.kodikrouter.ru/v1/videos \
  -H "Authorization: Bearer $KODIK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-mountains-001" \
  -o video-job.json \
  -d '{
    "model": "bytedance/seedance-2.5",
    "prompt": "A slow aerial reveal of a mountain village at sunrise",
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

JOB_ID=$(jq -r '.id' video-job.json)

while true; do
  STATUS=$(curl --fail-with-body -sS \
    -H "Authorization: Bearer $KODIK_API_KEY" \
    "https://api.kodikrouter.ru/v1/videos/$JOB_ID" \
    | tee video-status.json | jq -r '.status')

  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && { cat video-status.json; exit 1; }
  sleep 5
done

curl --fail-with-body -sS \
  -H "Authorization: Bearer $KODIK_API_KEY" \
  "https://api.kodikrouter.ru/v1/videos/$JOB_ID/content" \
  -o generated.mp4

Жизненный цикл video job

Параметры видео

Примеры ответов video job

{
  "id": "4599303b-52de-4ad4-9a13-2ff59df823ca",
  "polling_url": "/v1/videos/4599303b-52de-4ad4-9a13-2ff59df823ca",
  "status": "pending"
}

Где сохраняются файлы

• Изображения: возвращаются inline как base64. KodikRouter не создаёт файл на сервере; декодируйте и сохраните его в своём приложении.
• Видео: KodikRouter хранит metadata задачи и usage, но не копию видео. GET /content проксирует бинарный файл провайдера, поэтому клиент должен сохранить его самостоятельно.

Idempotency, тарификация и usage

Всегда отправляйте уникальный Idempotency-Key для логической генерации. Повтор с тем же ключом, организацией и API-ключом возвращает сохранённый ответ и не создаёт вторую платную задачу. Не переиспользуйте один idempotency key для другого prompt.

• Изображение списывается после успешного синхронного ответа провайдера.
• Видео списывается один раз при переходе задачи в completed, даже если статус опрашивается повторно.
• Стоимость и request ID доступны в Dashboard и через usage API при наличии scope gateway:read.
• Заголовки X-KodikRouter-Request-Id и X-KodikRouter-Provider помогают найти запрос в логах.

Основные ошибки