aisplice

Справочник API

Изображения: асинхронные задачи

Модели этого эндпоинта (12)

gpt-image-2.5-extgpt-image-2seedream-5-0-flashgpt-image-2.5-flare+8
Попробовать в Workbench
POST/v1/images/tasks
GET/v1/images/tasks/{task_id}
GET/v1/images/tasks/{task_id}/content

Асинхронная генерация изображений — маршрут, которым пользуются все модели изображений каталога. Отправка возвращает task_id; опрашивайте эндпоинт статуса, затем получите постоянные URL результатов из /content — или зарегистрируйте вебхук и обойдитесь без опроса.

#Параметры запроса

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

    ID асинхронной модели изображений, например gpt-image-2. Модели только с синхронным режимом этот эндпоинт отклоняют.

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

    Что нарисовать.

  • sizestringнеобязательно

    Предустановленное соотношение сторон, например "16:9", — так размер задаётся у большинства моделей изображений; точные значения указаны в карточке модели. Некоторые старые модели принимают и WIDTHxHEIGHT.

  • resolutionstringнеобязательно

    Уровень разрешения результата, например "1K", "2K" или "4K", если он указан в карточке модели, — тоже влияет на ценовой уровень.

  • qualitystringнеобязательно

    Уровень качества у провайдера (например, standard / hd) — тоже влияет на ценовой уровень.

  • nintegerнеобязательно

    Количество изображений (стоимость умножается на их число).

  • imagesarrayнеобязательно

    Референсные изображения для редактирования или как образец — URL или data URI. Сколько принимает модель, указано в её карточке.

  • maskstringнеобязательно

    Перерисовывает одну область первого референсного изображения — см. «Изменить часть изображения» ниже. Принимают только модели, в карточке которых есть mask; mask_url принимается как то же поле.

  • webhook_urlstringнеобязательно

    HTTPS-URL, который вызывается, когда задача переходит в конечное состояние, — формат обратного вызова описан в руководстве по видео.

  • webhook_secretstringнеобязательно

    Если задан, каждая доставка содержит X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)).

Параметры зависят от модели

Какие поля и значения принимает модель, смотрите в её карточке. gpt-image-2.5-ext принимает size как соотношение сторон плюс resolution; размер в пикселях, например 2560x1088, приводится к ближайшему соотношению и разрешению (21:9, 2K). Управлять background у неё нельзя: "auto" игнорируется, другие значения отклоняются. Он создаёт одно изображение за запрос и не даёт выбрать version: не передавайте его или передайте "flare".

Названия полей могут зависеть от семейства моделей

Данные о статусе задачи повторяют то, что сообщает вышестоящий провайдер; ориентируйтесь на фактические ответы и полагайтесь на task_id, status и эндпоинт /content — они одинаковы у всех провайдеров.

#Изменить часть изображения

Передайте изображение в images и маску в mask: перерисуется только область под маской, остальное останется как есть. В prompt опишите, что должно появиться в этой области. Сейчас маску принимают gpt-image-2.5-flare и gpt-image-2.5-sunburst; в карточке модели она показана как поле mask.

curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Replace the mug with a glass of orange juice; keep everything else",
    "images": ["https://example.com/desk.png"],
    "mask": "https://example.com/desk-mask.png",
    "resolution": "1K"
  }'

Как сделать маску

PNG с альфа-каналом: полностью прозрачные пиксели отмечают область, которую нужно перерисовать, остальное сохраняется. Размер в пикселях должен точно совпадать с первым референсным изображением (а не с результатом), файл — меньше 4 МБ. Одна маска на запрос; если референсов несколько, она применяется к первому. У моделей gpt-image-2.5 не передавайте size, тогда результат сохранит пропорции изображения.
  • 400 invalid_requestmask передан без референсного изображения или модели, которая не принимает маску (gpt-image-2.5-ext отвечает "mask is not supported on Ext").

Полная таблица кодов ошибок →

#Связанные ошибки

  • 404 not_foundНеизвестный путь, неизвестное имя модели или просроченный / чужой task_id.
  • 401Bearer-токен недействителен или отсутствует. На этом пути error.code нет — ориентируйтесь на статус.
  • 402 insufficient_user_quotaБаланса кошелька не хватает на предварительно резервируемую сумму.
  • 429Ограничение частоты для ключа. Тело пустое; дождитесь Retry-After. Если же в ответе 429 есть insufficient_user_quota, это дневной лимит расходов.
  • 503 model_not_foundНеизвестная модель, или сейчас её не обслуживает ни один исправный канал.

Полная таблица кодов ошибок →

#Пример запроса

# 1. submit
curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-ext", "prompt": "A red paper crane on a desk", "size": "16:9", "resolution": "1K"}'

# 2. poll every 3s until a terminal status
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# 3. fetch persistent result URLs
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID/content -H "Authorization: Bearer sk-YOUR_KEY"

#Ответ

response.json
// POST /v1/images/tasks
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/images/tasks/{task_id}
{"task_id": "task_xxx", "status": "in_progress", "progress": "60%"}

// GET /v1/images/tasks/{task_id}/content — after completion
{"created": 1720000000, "data": [{"url": "https://…"}]}

Проблема не решена?

Пришлите нам ID запроса или текст ошибки, и мы разберёмся.

НазадMessages (формат Anthropic)ДалееВидео