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

Генерация асинхронна: отправка задачи и получение результата — два отдельных вызова.

Простыми словами:

1. Вы отправляете задачу и сразу получаете taskId. Пока ничего не готово; стоимость задачи резервируется на вашем балансе — это резерв.
2. Позже вы спрашиваете, завершена ли задача с этим taskId. Это опрос; одного запроса каждые несколько секунд достаточно. Либо вы передаёте веб-адрес, и мы отправляем туда результат после завершения — это обратный вызов, или вебхук.
3. Когда state равен succeeded, ссылка на файл находится в data.output.assets[0].url. Откройте или скачайте его примерно в течение 20 минут; если ссылка истекла, запросите свежую. С успешной задачи списывается не больше резерва; неудачные и просроченные задачи обычно освобождают его, за исключением некоторых оплачиваемых отказов по содержимому, прямо указанных на странице модели. Окончательное начисление смотрите в settled и cost.

Почему не один вызов? Изображения создаются за секунды, а видео обычно требует минут. Синхронный эндпоинт держал бы ваш процесс на открытом соединении; любой сбой оставил бы вас без результата и безопасного способа повторить запрос, поскольку вы не знали бы, выполняется ли предыдущая попытка. Разделение делает ID задачи надёжной точкой отсчёта: восстановите соединение и продолжайте запрашивать тот же ID.

1. Создайте задачу

POST /api/v1/jobs/createTask

Заголовки

Тело

callBackUrl должен быть публичным HTTPS-адресом, доступным нашим серверам через интернет. Отклоняются обычные URL http://, явно заданные порты, отличные от 443 и 80, URL с именем пользователя или паролем, частные IP или адреса обратной петли, а также имена хостов, которые не разрешаются: тело обратного вызова содержит промпт и подписанные ссылки на результаты. Поэтому http://localhost не подходит для локальной разработки: используйте опрос или туннель, выдающий вашему компьютеру публичный HTTPS-адрес. Некорректное значение возвращает HTTP 400 с бизнес-полями code: 400, msg: "Invalid callback URL" и request_id. Ошибка не повторяет ваш URL, имя хоста, IP-адрес или сведения DNS. При подключении мы повторно проверяем адрес назначения; см. Вебхуки.

Ответ

HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
Retry-After: 2

Транспортный статус — 202 Accepted. Тело использует стандартную обёртку, поэтому успешный бизнес-code остаётся 200. Location указывает адрес опроса, а Retry-After: 2 — рекомендуемое ожидание в секундах до первого запроса.

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.008",
    "deadlineAt": "2026-08-28T09:42:04Z"
  },
  "request_id": "req_01k3m8x9q2z4v7n5p6r8s0t1w2"
}

Ошибки создания

С этими ошибками обычно сталкиваются при первой интеграции. Если createTask возвращает ошибку, ничего не резервируется и не списывается.

Полный список: Ошибки.

Перед началом: выберите модель и допустимые входные данные

Примерам ниже нужны настоящий ID модели и допустимый для неё input. Каталог даёт и то и другое: includeExamples=1 добавляет входные данные, уже прошедшие схему каждой модели. Нужен jq, небольшой инструмент командной строки для JSON; замените image на video или audio для других типов моделей.

curl -s "https://api.spicyapi.ai/api/v1/models?modality=image&includeExamples=1" \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  | jq -c '.data.items[] | select(.enabled and .available) | {model, input: .examples[0].input}'

Каждая выведенная строка — готовое тело запроса с полями model и input. Выберите одну. Если в строке указано "input": null, у модели нет сохранённого примера: прочитайте её inputSchema через GET /api/v1/models/{model} и составьте входные данные самостоятельно. См. Каталог и схемы моделей.

Примеры

MODEL_ID_FROM_CATALOG ниже — только заглушка: замените всё тело запроса строкой, выбранной из актуального каталога. Не отправляйте заглушку буквально.

# Paste one line printed by the command above between the single quotes.
TASK='{"model":"MODEL_ID_FROM_CATALOG","input":{"prompt":"a folded paper lantern, hard side light"}}'
# One new key per new task. After a network error, rerun only the curl command
# so the same key is sent again and no second task is created.
IDEMPOTENCY_KEY="$(uuidgen)"

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: $IDEMPOTENCY_KEY" \
  --data "$TASK"

Вы должны получить показанное выше тело ответа 202 с code: 200 и taskId. Сохраните taskId: по нему вы получите результат. Для обратного вызова добавьте в JSON "callBackUrl":"https://…" со своим HTTPS-адресом.

const res = await fetch('https://api.spicyapi.ai/api/v1/jobs/createTask', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SPICY_API_KEY}`,
    'Content-Type': 'application/json',
    // One key per logical request; reuse it across retries
    'Idempotency-Key': 'order-8814-render-1',
  },
  body: JSON.stringify({
    model: 'MODEL_ID_FROM_CATALOG',
    input: { prompt: 'a folded paper lantern, hard side light' },
    // Your own public HTTPS endpoint; delete this line to poll instead
    callBackUrl: 'https://your-app.example.com/hooks/spicy',
  }),
});

const body = await res.json();
if (res.status !== 202 || body.code !== 200) throw new Error(`${res.status} ${body.code} ${body.msg}`);
console.log(body.data.taskId, body.data.deadlineAt);

import os, requests

res = requests.post(
    "https://api.spicyapi.ai/api/v1/jobs/createTask",
    headers={
        "Authorization": f"Bearer {os.environ['SPICY_API_KEY']}",
        "Content-Type": "application/json",
        # One key per logical request; reuse it across retries
        "Idempotency-Key": "order-8814-render-1",
    },
    json={
        "model": "MODEL_ID_FROM_CATALOG",
        "input": {"prompt": "a folded paper lantern, hard side light"},
        # Your own public HTTPS endpoint; delete this line to poll instead
        "callBackUrl": "https://your-app.example.com/hooks/spicy",
    },
)

body = res.json()
if res.status_code != 202 or body["code"] != 200:
    raise RuntimeError(f'{res.status_code} {body["code"]} {body["msg"]}')
print(body["data"]["taskId"], body["data"]["deadlineAt"])

2. Состояния

Принятая задача необратима: ни для queued, ни для running нет действия отмены. API по-прежнему читает исторические записи canceled, но новые действия пользователя или оператора не создают это состояние.

Проверяйте конечное состояние условием state не входит в {queued, running}, а не перечислением конечных значений. Это корректно обрабатывает исторические записи canceled и не позволяет будущему конечному состоянию вызвать бесконечный опрос.

2.5 Пропустите цикл опроса с wait

Добавьте ?wait=<seconds> к createTask: мы удержим соединение до конечного состояния задачи, так что первому вызову вообще не понадобится цикл опроса.

curl -X POST "https://api.spicyapi.ai/api/v1/jobs/createTask?wait=30" \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID_FROM_CATALOG","input":{"prompt":"a lighthouse at dusk"}}'

Максимум — 60 секунд. Большие значения ограничиваются до максимума, а не отклоняются; всё, что не является положительным целым числом, игнорируется, а не вызывает отказ. Опечатка в параметре оптимизации не должна ломать генерацию, которая иначе была бы успешной.

Предел связан со 100-секундным тайм-аутом пограничного сервера перед API. После него соединение разрывает CDN, а не мы, и вы получили бы 524 без ID задачи и возможности продолжить получение результата, хотя задача уже существует, а средства зарезервированы. 60 секунд оставляют время на сам запрос.

Для рабочих интеграций вебхуки остаются предпочтительнее: соединение вообще не удерживается, а вы узнаете о завершении задач, которые выполняются дольше любого выбранного времени ожидания.

3. Запросите задачу

GET /api/v1/jobs/recordInfo?taskId=job_…

Единственный обязательный параметр запроса — taskId. Прочитать задачу можно только тем API-ключом, который её создал. Другой ключ, даже из того же аккаунта или новый после ротации, возвращает 404, как для несуществующей задачи. Так различия ошибок нельзя использовать для перебора чужих ID. То же правило относится к download-url и retry. Перед ротацией ключа завершите получение результатов задач, созданных старым ключом.

curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3" \
  -H "Authorization: Bearer $SPICY_API_KEY"

Запрос состояния бесплатен. Замените ID примера своим taskId.

Поля ответа

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

• Собственное время ожидания вы выбираете сами. Прекращение ожидания не отменяет удалённую задачу: сохраните taskId и позже запросите ту же задачу для продолжения.
• deadlineAt — срок выполнения на сервере. Идемпотентный повтор его не продлевает; явная повторная попытка создаёт новую задачу со своим сроком. Проверяйте конечное состояние и settled, а не делайте вывод о возврате средств по локальному таймеру.
• output.assets[].expiresAt — истечение временной ссылки на результат, обычно через 20 минут. Повторный запрос обновляет ссылку без создания новой задачи.
• Созданные медиа хранятся не дольше примерно 14 дней после завершения, а загруженные на платформу входные файлы — не дольше суток. Это пределы платформы: можно задать более короткие сроки в разделе Хранение и уничтожение данных или уничтожить содержимое одной задачи по запросу. Обновление ссылки не продлевает хранение самого медиафайла.

В JavaScript SDK client.run({ model, input }, { idempotencyKey, onAccepted, timeoutMs }) отправляет задачу один раз и опрашивает с растущим интервалом от 2 до максимум 10 секунд. Его timeoutMs — только локальное время ожидания, поэтому сохраняйте ID из onAccepted. См. SDK. Для фоновых задач предпочитайте вебхуки. Проверив полный обратный вызов с результатом, используйте результат напрямую без дополнительного запроса задачи.

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "MODEL_ID_FROM_CATALOG",
    "state": "succeeded",
    "input": { "prompt": "a folded paper lantern, hard side light" },
    "output": {
      "assets": [
        {
          "key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/9f3c1d0a7b4e2f68c5a1d3e9b0472fa1.png",
          "url": "https://example.r2.cloudflarestorage.com/results/result.png?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
          "expiresAt": "2026-08-28T09:32:11Z",
          "mime": "image/png",
          "width": 1024,
          "height": 1024,
          "bytes": 1483920
        }
      ]
    },
    "cost": "0.008",
    "settled": true,
    "createdAt": "2026-08-28T09:12:04Z",
    "deadlineAt": "2026-08-28T09:42:04Z",
    "completedAt": "2026-08-28T09:12:11Z",
    "contentState": "present"
  },
  "request_id": "req_01k3m8xa1b2c3d4e5f6g7h8j9k0m"
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "MODEL_ID_FROM_CATALOG",
    "state": "failed",
    "errorCode": "upstream_failed",
    "errorMessage": "Generation failed; the charge has been refunded",
    "cost": "0",
    "settled": true,
    "createdAt": "2026-08-28T09:12:04Z",
    "deadlineAt": "2026-08-28T09:42:04Z",
    "completedAt": "2026-08-28T09:12:39Z",
    "contentState": "present"
  },
  "request_id": "req_01k3m8xb2c3d4e5f6g7h8j9k0m1n"
}

Структура output

У output две независимые части. Созданные файлы — изображения, видео, аудио — поступают в output.assets[]. Текстовые результаты находятся в output.text в виде обычной строки.

Большинство моделей заполняют только одну часть, но модель может заполнить обе. Это свойство эндпоинта, а не его modality: эндпоинт speech-to-text находится в категории audio каталога, поскольку читает аудио, а возвращает текст.

const { text, assets = [] } = task.output ?? {};
if (text) console.log(text);
for (const asset of assets) console.log(asset.url);

Далее в этом разделе описаны assets[].

Отсутствующие данные не включаются в ответ, вместо значений null или 0. Разбирайте поля как необязательные.

Нужно обработать два флага:

• pending: true: файл ещё копируется в наше хранилище, и key и url пока пусты. Запросите снова через несколько секунд; вызов download-url без key сейчас возвращает 409.
• unavailable: true: срок файла истёк либо он окончательно недоступен после неудачной передачи. Этот файл уже не вернётся; ожидание не поможет, нужна новая генерация. Если не удалось сохранить ни один файл успешной задачи, плата за неё не взимается.

Результаты разложения на слои содержат дополнительное поле layer. Первый файл — базовое изображение, то есть исходник с удалёнными выделенными элементами и zIndex 0; остальные — прозрачные PNG-слои. Сложите их в порядке возрастания zIndex, чтобы восстановить изображение. boundingBox имеет вид [x1, y1, x2, y2] в пикселях базового изображения: масштабируйте слой до этого прямоугольника, и он встанет на своё место. Модели, не сообщающие позиции, не включают поле; их слои всё равно пригодны как отдельные вырезанные элементы. name — собственное название от модели, которое присутствует только при его выдаче. В расчёт оплаты входит каждое возвращённое изображение, включая базовое.

4. Обратные вызовы в первую очередь, опрос как запасной вариант

Опрос — ваш код многократно запрашивает recordInfo до завершения задачи. Обратный вызов — мы один раз отправляем завершённую задачу на ваш сервер. Оба способа дают те же данные.

Используйте обратные вызовы в рабочей среде. Трёхминутная видеозадача при опросе раз в секунду даёт 180 запросов почти без новой информации. Действующий предохранитель открытого API в 1000 запросов за 10 секунд не ограничивает обычную платную генерацию, но частый опрос создаёт лишний трафик, а бесконтрольный цикл исчерпывает собственную квоту чтения, пока recordInfo не начнёт отвечать 429.

Опрос разумен в двух случаях: локальная разработка и сервисы без публичного входящего подключения.

Увеличивайте интервал опроса

Рабочий подход:

• Начните с 2–3 секунд. Меньший интервал бесполезен: даже самые быстрые модели изображений требуют нескольких секунд.
• Умножайте на 1,5, ограничивая интервал 10–15 секундами.
• Останавливайтесь по собственному сроку задачи, а не через фиксированное количество минут. Некоторые видеомодели могут работать до часа, поэтому фиксированный тайм-аут 10 минут прекращает ожидание ещё нормально выполняющихся задач. Используйте deadlineAt из ответа createTask, добавив несколько минут на фиксацию исхода сервером.

// created is the data object returned by createTask.
async function waitForTask(created) {
  // Stop a few minutes after the server's own deadline.
  const giveUpAt = Date.parse(created.deadlineAt) + 5 * 60 * 1000;
  let wait = 2000;

  while (Date.now() < giveUpAt) {
    await new Promise((r) => setTimeout(r, wait));
    wait = Math.min(wait * 1.5, 15000);

    const res = await fetch(
      `https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=${encodeURIComponent(created.taskId)}`,
      { headers: { Authorization: `Bearer ${process.env.SPICY_API_KEY}` } },
    );
    const body = await res.json();

    // Being rate-limited is not a task failure — honour Retry-After
    if (body.code === 429) {
      wait = Number(res.headers.get('retry-after') ?? 1) * 1000;
      continue;
    }
    if (body.code !== 200) throw new Error(`${body.code} ${body.msg}`);

    // Terminal means "not one of the two in-flight states"
    const { state } = body.data;
    if (state !== 'queued' && state !== 'running') return body.data;
  }
  // Not a failure: query this taskId again later instead of resubmitting.
  throw new Error(`stopped waiting for ${created.taskId}`);
}

// created = body.data from the createTask example above
const task = await waitForTask(created);
if (task.state === 'succeeded') console.log(task.output.assets[0].url);
else console.log(task.state, task.errorCode);

import os, time, requests
from datetime import datetime

BASE = "https://api.spicyapi.ai/api/v1"
AUTH = {"Authorization": f"Bearer {os.environ['SPICY_API_KEY']}"}


def wait_for_task(created: dict) -> dict:
    """created is the data object returned by createTask."""
    # Stop a few minutes after the server's own deadline.
    deadline = datetime.fromisoformat(created["deadlineAt"].replace("Z", "+00:00"))
    give_up_at = deadline.timestamp() + 5 * 60
    wait = 2.0

    while time.time() < give_up_at:
        time.sleep(wait)
        wait = min(wait * 1.5, 15.0)

        res = requests.get(f"{BASE}/jobs/recordInfo", headers=AUTH, params={"taskId": created["taskId"]})
        body = res.json()

        # Being rate-limited is not a task failure — honour Retry-After
        if body["code"] == 429:
            wait = float(res.headers.get("retry-after", 1))
            continue
        if body["code"] != 200:
            raise RuntimeError(f'{body["code"]} {body["msg"]}')

        # Terminal means "not one of the two in-flight states"
        if body["data"]["state"] not in ("queued", "running"):
            return body["data"]

    # Not a failure: query this taskId again later instead of resubmitting.
    raise TimeoutError(f'stopped waiting for {created["taskId"]}')


# created = body["data"] from the createTask example above
task = wait_for_task(created)
if task["state"] == "succeeded":
    print(task["output"]["assets"][0]["url"])
else:
    print(task["state"], task.get("errorCode"))

5. Проверьте баланс

GET /api/v1/chat/credit возвращает available: средства для новых задач, held: резерв выполняющихся задач, и total. При использовании одобренного кредита available может быть отрицательным, а бонусные средства в funding.grants могут оплачивать только некоторые модели. Подробнее: Проверка баланса.

curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

История задач и восстановление

GET /api/v1/jobs перечисляет видимые задачи, созданные текущим API-ключом. Используйте его для поиска работы после перезапуска приложения или пропущенного обратного вызова. Задачи других ключей и скрытые записи исключены. Ответы содержат ID задачи, модель, состояние, стоимость, состояние расчёта, время и, если он был записан, requestId вызова создания задачи; для текстового вызова это то же значение, что заголовок X-Request-Id. Промпты, входные данные, результаты и ссылки на медиа в список не входят. Получите выбранную задачу через recordInfo, чтобы забрать результат.

Фильтруйте по state, точному model из каталога или псевдониму, а также датам UTC from / to: формат YYYY-MM-DD, начало включено, конец исключён. По умолчанию диапазон составляет семь дней до завтра по UTC; максимальный диапазон — 92 дня. Значение limit по умолчанию 20 и не может превышать 100.

Не передавайте ненужные фильтры: пустое значение, например model=, повторяющийся или неизвестный параметр возвращает 400. Запрос дольше пяти секунд возвращает 503; повторите с меньшим диапазоном дат.

curl --fail-with-body \
  'https://api.spicyapi.ai/api/v1/jobs?from=2026-09-01&to=2026-09-07&state=failed&limit=20' \
  -H "Authorization: Bearer $SPICY_API_KEY"

Читайте data.items. Если data.hasMore равно true, передайте data.nextCursor как cursor следующего запроса, сохраняя все фильтры и явно заданные даты. Сортировка — по убыванию createdAt, затем ID задачи. Страницы отражают текущие состояния задач, а не замороженный снимок. Не создавайте курсоры самостоятельно. Получение истории никогда не создаёт и не повторяет задачу.

Та же функция доступна через client.listTasks(...), spicyapi tasks list и инструмент MCP только для чтения spicyapi_tasks_list. Храните USD cost как десятичную строку; если settled равно false, это всё ещё оценка зарезервированной суммы, а не окончательное начисление.

Если ответ создания потерян, сначала повторите неизменённый запрос с исходным Idempotency-Key. Пустая страница истории не даёт оснований снова создавать ту же платную работу с новым ключом.