Задачи и вебхуки

Генерация медиа осуществляется асинхронно. POST /api/v1/generation/create возвращает taskId; получите конечный результат с помощью опроса или вебхука.

Значения статуса

Статус	Финальный	Значение
`not_started`	Нет	В очереди и еще не отправлен.
`processing`	Нет	Выполняется у поставщика или обрабатываются возвращенные материалы.
`finished`	Да	Успех. Читайте `files` и/или `output`.
`failed`	Да	Ошибка. Читайте `errorMessage`; плата возвращена.
`expired`	Да	Сохранённые сведения о задаче больше недоступны.

Опрос

curl https://api.api-stock.com/api/v1/task/status/$TASK_ID \
  -H "Authorization: Bearer $API_STOCK_KEY"

{
  "code": 200,
  "data": {
    "taskId": "019ca881-9503-7270-a560-f00fc2b15785",
    "status": "finished",
    "files": [
      {
        "fileUrl": "https://storage.api-stock.com/result.mp4",
        "fileType": "video"
      }
    ],
    "output": null,
    "createdTime": "2026-08-22T12:00:00.000Z",
    "errorMessage": null
  }
}

Проверяйте статус, а не наличие files: некоторые действия завершаются только со структурированными данными в output. Выполняйте опрос с увеличением интервала, как описано в Ошибки и ограничения.

Вебхуки

Добавьте общедоступный HTTPS URL рядом с model и input:

{
  "model": "veo3.1-fast",
  "input": { "prompt": "A waterfall at sunrise" },
  "webhook": "https://example.com/hooks/api-stock/long-random-secret"
}

API Stock отправляет JSON POST после того, как задача становится finished или failed. Тело соответствует ответу о статусе. Быстро верните 2xx и выполняйте дорогостоящую работу после подтверждения доставки.

Неудачные доставки повторяются с экспоненциальной задержкой, но запустить их повторно вручную нельзя. Сохраняйте редкий опрос как резервный способ сверки статуса.

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