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

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

## Статусы

```text
queued → in_progress → completed
                      ↘ failed
```

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

## Опрос

```text
GET /v1/jobs/{id}
```

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

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

```json
{
  "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`:

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

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

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

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

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

```json
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>` при создании джобы — повторный запрос с тем же ключом вернёт ту же джобу, а не создаст (и не оплатит) новую. Полезно при ретраях по таймауту.

```bash
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` не бывает.