Джобы и результаты

Картинки и видео создаются асинхронно: POST .../generations сразу возвращает джобу, а результат появляется в ней позже.

Статусы

queued → in_progress → completed
                      ↘ failed

Статус	Значение
queued	Принята, ждёт обработки
in_progress	Генерируется у провайдера
completed	Готово — ссылка в data[0].url
failed	Не получилось — причина в error.code, резерв кредитов возвращён

Опрос

GET /v1/jobs/{id}

curl https://api.souz.ai/v1/jobs/job_a1b2c3 \
  -H "Authorization: Bearer sk-souz-..."

Ответ — всегда полный объект джобы:

{
  "id": "job_a1b2c3",
  "object": "image",
  "model": "souz/nano-banana-pro",
  "status": "completed",
  "price": 20,
  "created_at": 1781250000,
  "data": [{ "url": "https://api.souz.ai/v1/files/res_....png?exp=...&sig=..." }]
}

При failed вместо data приходит error:

{ "status": "failed", "error": { "code": "content_blocked", "message": "content_blocked", "type": "content_blocked" } }

Рекомендуемая частота опроса: картинки — раз в 2–5 сек, видео — раз в 5–10 сек. Чтобы не опрашивать вовсе — используй вебхуки.

Файлы результатов

data[0].url — подписанная ссылка (?exp=...&sig=...): её можно открывать в браузере и отдавать куда угодно без API-ключа, пока не истекла подпись. Если подпись истекла — просто запроси джобу ещё раз, получишь свежую ссылку.

Хранение — около 24 часов. Потом файл удаляется, и ссылка вернёт:

HTTP 410 Gone
{ "error": { "code": "file_expired", "message": "file has expired: generated files are kept for ~24 hours — download results right after completion, or generate again" } }

Поэтому правило простое: скачивай результат сразу после completed и храни у себя.

Идемпотентность

Передай заголовок Idempotency-Key: <твой-уникальный-id> при создании джобы — повторный запрос с тем же ключом вернёт ту же джобу, а не создаст (и не оплатит) новую. Полезно при ретраях по таймауту.

curl https://api.souz.ai/v1/images/generations \
  -H "Authorization: Bearer sk-souz-..." \
  -H "Idempotency-Key: order-42-avatar" \
  -H "Content-Type: application/json" \
  -d '{ "model": "souz/nano-banana", "prompt": "..." }'

Дедлайн

Если генерация зависла у провайдера — джоба автоматически помечается failed и кредиты возвращаются. Потолки с запасом: картинки — 15 минут, видео — 90 минут (реальные генерации укладываются в разы быстрее; долгие, но живые генерации не обрубаются). Бесконечного queued не бывает.