APIGrid
Получить ключ

Задачи и результаты

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

Жизненный цикл задачи

Задача создаётся запросом POST /v1/tasks и проходит такие статусы:

queued
Задача принята и ждёт очереди у модели. Цена уже списана.
processing
Модель генерирует результат.
completed
Готово: ссылки на файлы — в поле output.
failed
Генерация не удалась: причина — в поле error, деньги автоматически возвращены на баланс (price.refunded: true).

completed и failed — конечные статусы, дальше задача не меняется. Не все модели сообщают отдельный этап генерации, поэтому статус может сразу смениться с queued на completed — ориентируйтесь на конечные статусы. Изображения обычно готовы за 10–60 секунд, видео — за 1–10 минут, в зависимости от модели, длительности и разрешения.

Объект задачи

Один и тот же объект возвращают POST /v1/tasks, GET /v1/tasks/{id}, список задач и вебхук.

Задача
{
  "id": "7e70388cf461f88d7149b1077e4ad098",
  "object": "task",
  "model": "kling-3.0",
  "status": "completed",
  "output": {
    "urls": [
      "https://tempfile.aiquickdraw.com/…/video.mp4"
    ],
    "files": [
      {
        "url": "https://tempfile.aiquickdraw.com/…/video.mp4",
        "kind": "video"
      }
    ]
  },
  "error": null,
  "price": {
    "amount": "29.400000",
    "currency": "RUB",
    "refunded": false
  },
  "created_at": "2026-10-15T09:12:04.512Z",
  "started_at": "2026-10-15T09:12:04.880Z",
  "completed_at": "2026-10-15T09:14:47.203Z"
}
Поля
idstring
ID задачи — для опроса статуса и поддержки.
objectstring
Всегда task.
modelstring
ID модели, переданный при создании.
statusstring
queued, processing, completed или failed — см. выше.
outputobject | null
Результат готовой задачи; до завершения — null. Подробнее ниже.
errorobject | null
Для failed: code и message — причина ошибки. Иначе null.
priceobject
amount — списанная сумма (строка, 6 знаков после точки), currency — RUB, refunded — вернули ли деньги.
created_atstring
Время создания, ISO 8601 в UTC.
started_atstring | null
Когда задачу приняла модель. null — задача ещё не отправлена.
completed_atstring | null
Когда задача завершилась (успешно или с ошибкой).

Результат и файлы

У готовой задачи в output.files — список файлов: url и kind (image, video, audio или file). В output.urls — те же ссылки простым списком. У моделей, которые возвращают несколько файлов (например, Suno — два трека), в списке больше одного элемента.

Опрос статуса

Запрашивайте GET /v1/tasks/{id}, пока статус не станет конечным. Разумная пауза между запросами: 3–5 секунд для изображений, 10–15 секунд для видео.

import os
import time
import requests

API = "https://api.apigrid.cloud/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['APIGRID_KEY']}"}


def wait_task(task_id: str, every: float = 10, timeout: float = 900) -> dict:
    """Ждёт завершения задачи и возвращает её. every — пауза между запросами, с."""
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        task = requests.get(f"{API}/tasks/{task_id}", headers=HEADERS, timeout=30).json()
        if task["status"] in ("completed", "failed"):
            return task
        time.sleep(every)
    raise TimeoutError(f"Задача {task_id} не завершилась за {timeout} с")

Повтор без дублей

Если ответ на POST /v1/tasks не дошёл (обрыв сети, таймаут), повторять запрос опасно — можно создать и оплатить две задачи. Чтобы этого не случилось, передайте заголовок Idempotency-Key — любую уникальную строку до 200 символов, например UUID:

curl -X POST https://api.apigrid.cloud/v1/tasks \
  -H "Authorization: Bearer $APIGRID_KEY" \
  -H "Idempotency-Key: order-1842-cover" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "Обложка для заказа №1842"
    }
  }'

Повторный запрос с тем же ключом вернёт уже созданную задачу и ничего не спишет. Ключ действует для вашего аккаунта; для новой задачи используйте новый.

Список задач

GET /v1/tasks возвращает задачи аккаунта, новые сверху. limit — сколько вернуть (1–100, по умолчанию 20), before — вернуть задачи, созданные раньше этого времени (ISO 8601). Чтобы получить следующую страницу, передайте в before значение created_at последней задачи. Пока has_more равно true, есть ещё задачи.

curl https://api.apigrid.cloud/v1/tasks?limit=20 \
  -H "Authorization: Bearer $APIGRID_KEY"
Ответ
{
  "object": "list",
  "data": [
    {
      "id": "7e70388cf461f88d7149b1077e4ad098",
      "object": "task",
      "model": "kling-3.0",
      "status": "completed",
      "…": "…"
    }
  ],
  "has_more": false
}

В списке только задачи на генерацию медиа. Запросы к текстовым моделям видны в кабинете, на странице Задачи.