# Генерации

Создание задач генерации и проверка статуса

Базовый адрес — `https://api.iskragen.ru`. Общие правила — в [обзоре справочника](/docs/api-reference).

## GET /v1/generations/

**Список генераций.** Возвращает свои генерации от новых к старым с фильтрами `status`, `modelId` через запятую, `q` длиной 1–200 символов и `from` / `to`; курсорная пагинация принимает `limit` от 1 до 100, по умолчанию 20, а `cursor` равен ISO 8601 `createdAt` последнего элемента, `nextCursor: null` означает конец списка. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает `429 RATE_LIMIT_ERROR` с `retryAfter`, а отсутствие ключа — `401 AUTHENTICATION_ERROR`.

**Авторизация:** заголовок `Authorization: Bearer <ключ>` — API-ключ, выданный в личном кабинете (`isk_live_<prefix>_<secret>`).

### Параметры

| Параметр | Где | Тип | Обязательный | Описание и ограничения |
|---|---|---|---|---|
| `limit` | query | `integer` | нет | ≥ 1; ≤ 100; по умолчанию `20` |
| `cursor` | query | `string` | нет | — |
| `status` | query | `string` | нет | значения: `PENDING`, `PROCESSING`, `SUCCEEDED`, `FAILED` |
| `modelId` | query | `string` | нет | Один или несколько идентификаторов моделей через запятую — `modelSlug` (рекомендуется) или прежний идентификатор; длина ≤ 2000 |
| `q` | query | `string` | нет | длина ≥ 1; длина ≤ 200 |
| `mediaType` | query | `string` | нет | значения: `IMAGE`, `VIDEO`, `AUDIO` |
| `from` | query | `string` | нет | формат date-time |
| `to` | query | `string` | нет | формат date-time |

### Пример вызова

```bash
curl -X GET "https://api.iskragen.ru/v1/generations/" \
  -H "Authorization: Bearer $ISKRAGEN_API_KEY"
```

### Структура ответа `200`

Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — `object`.

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `items` | `object[]` | да | — |
| `items[].chargeStatus` | `string \| null` | да | — |
| `items[].costRub` | `number` | да | — |
| `items[].createdAt` | `string` | да | — |
| `items[].errorCode` | `string \| null` | да | — |
| `items[].errorMessage` | `string \| null` | да | — |
| `items[].finishedAt` | `string \| null` | да | — |
| `items[].id` | `string` | да | — |
| `items[].mediaPriceRub` | `number \| null` | да | — |
| `items[].mediaType` | `string` | да | — |
| `items[].modelId` | `string` | да | Устарело: внутренний идентификатор. Используйте modelSlug. |
| `items[].modelName` | `string` | да | — |
| `items[].modelSlug` | `string` | нет | Всегда присутствует в ответе; публичный идентификатор модели |
| `items[].outputUrls` | `string[]` | да | — |
| `items[].prompt` | `string` | да | — |
| `items[].startedAt` | `string \| null` | да | — |
| `items[].status` | `string` | да | — |
| `nextCursor` | `string \| null` | да | — |

### Коды ошибок

- `401 AUTHENTICATION_ERROR` — ключ отсутствует, невалиден или отозван.
- `429 RATE_LIMIT_ERROR` — превышен лимит запросов либо число одновременных генераций (по умолчанию 5).

## POST /v1/generations/

**Создать генерацию.** Возвращает `202` и задачу с `id`, `status`, `costRub`, а не результат; при резервировании стоимость списывается с баланса в момент создания задачи, до постановки в очередь, при нехватке возвращается `402 INSUFFICIENT_BALANCE` с `required` и `available`, а при провале генерации сумма возвращается на баланс автоматически. Результат получают опросом `GET /v1/generations/{id}` или вебхуком `generation.completed` / `generation.failed`; `Idempotency-Key` длиной 1–64 символа приоритетнее одноимённого поля тела, повтор и одновременные запросы с одним ключом возвращают ту же задачу. `prompt` — до 10 000 символов с точным пределом модели в `promptMaxChars` каталога, допускается не более 5 одновременных задач и до 10 внешних референсов суммарно до 200 МБ; доступ: Требуется API-ключ, действует общий лимит 60 запросов в минуту, превышение возвращает `429 RATE_LIMIT_ERROR` с `retryAfter`, а отсутствие ключа — `401 AUTHENTICATION_ERROR`.

**Авторизация:** заголовок `Authorization: Bearer <ключ>` — API-ключ, выданный в личном кабинете (`isk_live_<prefix>_<secret>`).

### Параметры

| Параметр | Где | Тип | Обязательный | Описание и ограничения |
|---|---|---|---|---|
| `idempotency-key` | header | `string` | нет | длина ≥ 1; длина ≤ 64 |

### Тело запроса (`application/json`)

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `durationSec` | `integer` | нет | ≥ 1; ≤ 600 |
| `height` | `integer` | нет | ≥ 256; ≤ 4096 |
| `idempotencyKey` | `string` | нет | длина ≥ 1; длина ≤ 64 |
| `modelSlug` | `string` | да | длина ≥ 1 |
| `negativePrompt` | `string` | нет | длина ≤ 2000 |
| `params` | `object` | нет | произвольные ключи |
| `prompt` | `string` | да | длина ≥ 1; длина ≤ 10000 |
| `seed` | `integer` | нет | ≥ 0 |
| `width` | `integer` | нет | ≥ 256; ≤ 4096 |

### Пример вызова

```bash
curl -X POST "https://api.iskragen.ru/v1/generations/" \
  -H "Authorization: Bearer $ISKRAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"modelSlug":"<modelSlug>","prompt":"<prompt>"}'
```

### Структура ответа `202`

Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — `object`.

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `costRub` | `number` | да | — |
| `id` | `string` | да | — |
| `status` | `string` | да | — |

### Коды ошибок

- `401 AUTHENTICATION_ERROR` — ключ отсутствует, невалиден или отозван.
- `402 INSUFFICIENT_BALANCE` — баланс ниже стоимости запроса.
- `429 RATE_LIMIT_ERROR` — превышен лимит запросов либо число одновременных генераций (по умолчанию 5).

## GET /v1/generations/models

**Модели из моей истории.** Возвращает без пагинации модели, по которым у аккаунта есть генерации, и их счётчики для фильтра списка. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает `429 RATE_LIMIT_ERROR` с `retryAfter`, а отсутствие ключа — `401 AUTHENTICATION_ERROR`.

**Авторизация:** заголовок `Authorization: Bearer <ключ>` — API-ключ, выданный в личном кабинете (`isk_live_<prefix>_<secret>`).

### Пример вызова

```bash
curl -X GET "https://api.iskragen.ru/v1/generations/models" \
  -H "Authorization: Bearer $ISKRAGEN_API_KEY"
```

### Структура ответа `200`

Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — `object`.

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `models` | `object[]` | да | — |
| `models[].count` | `integer` | да | — |
| `models[].id` | `string` | да | Устарело: внутренний идентификатор. Используйте slug. |
| `models[].name` | `string` | да | — |
| `models[].slug` | `string` | нет | Всегда присутствует в ответе; публичный идентификатор модели |

### Коды ошибок

- `401 AUTHENTICATION_ERROR` — ключ отсутствует, невалиден или отозван.
- `429 RATE_LIMIT_ERROR` — превышен лимит запросов либо число одновременных генераций (по умолчанию 5).

## GET /v1/generations/{id}

**Получить генерацию.** Возвращает генерацию для опроса статуса и параметры для повтора; возможные статусы: `PENDING`, `PROCESSING`, `SUCCEEDED`, `FAILED`, `REFUNDED`, `CANCELLED`, `ENQUEUE_FAILED`, а чужой `id` возвращает `404`. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает `429 RATE_LIMIT_ERROR` с `retryAfter`, а отсутствие ключа — `401 AUTHENTICATION_ERROR`.

**Авторизация:** заголовок `Authorization: Bearer <ключ>` — API-ключ, выданный в личном кабинете (`isk_live_<prefix>_<secret>`).

### Параметры

| Параметр | Где | Тип | Обязательный | Описание и ограничения |
|---|---|---|---|---|
| `id` | path | `string` | да | формат uuid |

### Пример вызова

```bash
curl -X GET "https://api.iskragen.ru/v1/generations/<id>" \
  -H "Authorization: Bearer $ISKRAGEN_API_KEY"
```

### Структура ответа `200`

Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — `object`.

| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
| `chargeStatus` | `string \| null` | да | — |
| `costRub` | `number` | да | — |
| `createdAt` | `string` | да | — |
| `durationSec` | `integer \| null` | да | — |
| `errorCode` | `string \| null` | да | — |
| `errorMessage` | `string \| null` | да | — |
| `finishedAt` | `string \| null` | да | — |
| `height` | `integer \| null` | да | — |
| `id` | `string` | да | — |
| `mediaPriceRub` | `number \| null` | да | — |
| `mediaType` | `string` | да | — |
| `modelId` | `string` | да | Устарело: внутренний идентификатор. Используйте modelSlug. |
| `modelName` | `string` | да | — |
| `modelSlug` | `string` | да | — |
| `negativePrompt` | `string \| null` | да | — |
| `outputUrls` | `string[]` | да | — |
| `params` | `object` | да | произвольные ключи |
| `prompt` | `string` | да | — |
| `seed` | `integer \| null` | да | — |
| `startedAt` | `string \| null` | да | — |
| `status` | `string` | да | — |
| `userId` | `string` | да | — |
| `width` | `integer \| null` | да | — |

### Коды ошибок

- `401 AUTHENTICATION_ERROR` — ключ отсутствует, невалиден или отозван.
- `404` — Ресурс не существует или принадлежит другому пользователю
- `429 RATE_LIMIT_ERROR` — превышен лимит запросов либо число одновременных генераций (по умолчанию 5).

## GET /v1/generations/{id}/download

**Скачать результат.** Отдаёт файл потоком с `Content-Disposition: attachment` и `Cache-Control: private, no-store`, а не ссылку или редирект; `index` от 0–15 выбирает файл при нескольких результатах. Отсутствующий файл возвращает `404`, недоступное хранилище — `502 OUTPUT_FETCH_FAILED`. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает `429 RATE_LIMIT_ERROR` с `retryAfter`, а отсутствие ключа — `401 AUTHENTICATION_ERROR`.

**Авторизация:** заголовок `Authorization: Bearer <ключ>` — API-ключ, выданный в личном кабинете (`isk_live_<prefix>_<secret>`).

### Параметры

| Параметр | Где | Тип | Обязательный | Описание и ограничения |
|---|---|---|---|---|
| `index` | query | `integer` | нет | ≥ 0; ≤ 15; по умолчанию `0` |
| `id` | path | `string` | да | формат uuid |

### Пример вызова

```bash
curl -X GET "https://api.iskragen.ru/v1/generations/<id>/download" \
  -H "Authorization: Bearer $ISKRAGEN_API_KEY"
```

### Структура ответа `200`

Схема не описывает JSON-тело ответа; что приходит в ответе — в описании метода выше.

### Коды ошибок

- `401 AUTHENTICATION_ERROR` — ключ отсутствует, невалиден или отозван.
- `404` — Ресурс не существует или принадлежит другому пользователю
- `429 RATE_LIMIT_ERROR` — превышен лимит запросов либо число одновременных генераций (по умолчанию 5).
- `502 OUTPUT_FETCH_FAILED` — файл результата не удалось получить из хранилища.