Генерации

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

Базовый адрес — https://api.iskragen.ru. Общие правила — в обзоре справочника.

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

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

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

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

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>).

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

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

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

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

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

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 — файл результата не удалось получить из хранилища.

GET /v1/generations/

Параметры

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

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

Коды ошибок

POST /v1/generations/

Параметры

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

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

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

Коды ошибок

GET /v1/generations/models

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

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

Коды ошибок

GET /v1/generations/{id}

Параметры

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

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

Коды ошибок

GET /v1/generations/{id}/download

Параметры

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

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

Коды ошибок

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

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

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

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

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

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