Задачи

POST/v1/tasks

Изображения создаются задачами, других видов задач пока нет. Вы присылаете, что сделать и какой моделью, и получаете один и тот же объект задачи: готовой или ещё идущей. Это не формат OpenAI, поэтому SDK OpenAI и Vercel AI для изображений не подходят, хватает обычного HTTP, как в примерах. Доступные модели и их возможности: GET /v1/tasks/models.

Запрос ждёт результата до wait секунд. Если задача успела, ответ 200 с результатом приходит сразу. Если нет, ответ 202, дальше опрос, см. «Опрос и повтор». Перед запуском резервируем стоимость, списываем по цене модели на момент создания и не больше резерва. Неудавшаяся задача не списывается никогда.

idstring

UUID задачи, 36 символов с дефисами, любой, кроме нулевого; вернётся строчными. Свой id известен до ответа, с ним запрос можно безопасно повторить. Каждой новой задаче нужен новый UUID: id, занятый другим запросом, даёт 409. Без id создадим UUIDv4 и вернём

kindstringобязательно

Вид задачи в форме группа/действие, от него зависят поля input. Сейчас только image/generate, другой даёт 400 с param /kind

modelstringобязательно

Модель, например google/gemini-3-pro-image. Модели по умолчанию нет: от неё зависят результат и цена. На неизвестную модель или модель чата ответ 404 not_found с param /model

inputobjectобязательно

Поля вида задачи, см. ниже. Неизвестное поле или значение, которого модель не умеет, дают 400 с путём к полю в param, до резерва и без списания

optionsobject

Поля отдельных моделей. Сейчас ни одна модель их не объявляет, любое поле внутри даёт 400

metadataobject

До 16 пар «строка → строка»: ключ до 40 символов из a-z0-9_, значение до 500 символов. Возвращается в задаче, по нему можно фильтровать список

waitinteger

Сколько секунд ждать результата: от 0 до 60, по умолчанию 60. Больше 60 или не целое число: 400 с param /wait

promptstringобязательно

Описание изображения или правки, до max_length символов модели

countinteger

Сколько изображений, от 1 до max модели, по умолчанию 1. Цена умножается на count

aspect_ratioresolutionstring

Кадр, например 16:9 и 2K, допустимые сочетания в variants модели. Без обоих полей кадр по умолчанию. Если прислано одно из двух, второе берётся из варианта по умолчанию или из единственного подходящего

sizestring

Кадр пикселями из variants, например 2048x2048. Вместе с aspect_ratio или resolution нельзя: 400

formatqualitystring

Формат файла и качество из values модели, если она их объявляет

seedinteger

От 0 до 4294967295, если модель его принимает. Если модерация отклонила готовое изображение, повтор уходит с новым seed. С каким seed сделано изображение, видно в output[].seed, если модель его сообщает

referencesarray

Ссылки https или data URL (png, jpeg, webp, base64, до 10 МиБ). Сколько можно, задаёт модель; у некоторых моделей от числа референсов зависит цена. Data URL проверяем до резерва: reference_too_large, reference_unsupported. Ссылку https скачивает провайдер; если не смог, задача failed, без списания

idkindmodelstring

Как в запросе

statusstring

queued, in_progress, completed или failed

eventsarray

История по порядку: type и at (время RFC 3339, UTC, до секунды). Первое событие task.queued, его at и есть время создания; последнее task.completed или task.failed. Незнакомые type пропускайте

outputarraycompleted

Список частей. У image: type, url, media_type, expires_at, retained_until, width, height, bytes, expired (только true, см. «Хранение») и, если модель его знает, seed. Частей не больше count: если провайдер отклонил часть изображений модерацией, придут остальные, и платите вы только за них

errorobjectfailed

Объект ошибки, см. «Ошибки задач»

usageobject

Пока задача идёт, reserved: столько зарезервировано, больше этого не спишется. У завершённой cost, окончательная цена. У failed он равен "0"

deadline_atstringпока задача идёт

Время, к которому задача гарантированно завершится

poll_afterintegerпока задача идёт

Через сколько секунд спросить снова

metadataobject

Как в запросе, если присылали

Деньги везде один объект: { "amount": "42.50", "currency": "rub" }. Сумма десятичной строкой, точно как списано, не меньше двух знаков после точки; ноль пишется "0".