Асинхронные задачи

Создание, состояния, результаты и цикл списания средств.

Эта страница описывает асинхронные задачи генерации медиа. При создании средства резервируются, при успехе списываются по фактическому использованию, а для failed и expired полностью освобождаются. Исторические записи canceled обрабатываются так же, но новую принятую задачу отменить нельзя.

API

GET /api/v1/models?includeSchema=1&includeExamples=1
# choose an item where enabled && available

curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: render-001" \
  -d '{
    "model": "MODEL_ID_FROM_CATALOG",
    "input": { "prompt": "a folded paper lantern, hard side light" }
  }'

История задач текущего ключа

GET /api/v1/jobs возвращает только задачи API-ключа, которым авторизован запрос. Выбрать другой ключ нельзя, даже в том же аккаунте. Ответ содержит только метаданные, без input и output. Результат выбранного taskId получите через GET /api/v1/jobs/recordInfo.

from и to — даты UTC, задающие интервал [from, to). По умолчанию он составляет 7 дней, максимум — 92. Доступны фильтры state и точная ссылка model; limit по умолчанию равен 20, максимум — 100. Если hasMore равен true, передайте nextCursor как следующий cursor, сохранив from, to и остальные фильтры. Задачи сортируются по createdAt по убыванию, а при одинаковом времени — по id по убыванию: так задачи с одним временем создания однозначно разделяются по страницам. Каждая страница читает текущее состояние; состояния и результаты фильтрации не являются зафиксированным снимком.

Четыре разных срока

deadlineAt — фактический предельный срок задачи, возвращаемый сервером. Параметр timeoutMs в SDK ограничивает только ожидание на стороне клиента и не отменяет принятую задачу. expiresAt указывает срок действия URL результата, обычно 20 минут; созданные медиафайлы хранятся 14 дней. Истечение срока URL не означает сбой задачи или удаление файла.

Создание задачи

Передайте model, input и при необходимости callBackUrl в POST /api/v1/jobs/createTask. Создавайте один Idempotency-Key на логический запрос и повторно используйте его при сетевых повторах.

Проверка состояния

Для новых задач queued и running не являются конечными; succeeded, failed и expired — конечные. Историческое canceled сохраняется только для чтения и совместимости; это не доступное действие. Успешный HTTP-ответ или code: 200 означает лишь успешный запрос данных. Результат генерации определяется по data.state.

Если output.assets[].pending равно true, подождите и запросите задачу снова. unavailable требует новой генерации.

Webhook и опрос

В продакшене webhook должен быть основным каналом. Опрос с экспоненциальной задержкой и jitter используется для восстановления. recordInfo и webhook имеют один envelope {code,msg,data,request_id}, поэтому можно использовать общий парсер.

Полные определения полей приведены в контракте OpenAPI 3.1.