Использование polling и webhooks для генерации видео

Используйте polling как базовый механизм для генерации видео, потому что каждая асинхронная задача возвращает ID задачи, который можно запрашивать. Добавляйте webhooks только тогда, когда выбранный video endpoint поддерживает callback URL, и сохраняйте polling как источник истины для пропущенной доставки callback или callback, зависящих от конкретного провайдера.

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

Следующий запрос создает минимальную видео-задачу и сохраняет возвращенный ID. Добавляйте поля duration, resolution или callback только тогда, когда страница выбранной модели документирует эти поля.

curl https://api.cometapi.com/v1/videos \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -F "model=doubao-seedance-2-0" \
  -F "prompt=A cinematic shot of a paper airplane crossing a desk"

Ответ включает ID задачи и статус:

{
  "id": "task_example",
  "task_id": "task_example",
  "object": "video",
  "model": "doubao-seedance-2-0",
  "status": "queued",
  "progress": 0,
  "created_at": 1779872000
}

Poll статуса

Следующий запрос проверяет статус видео-задачи:

curl https://api.cometapi.com/v1/videos/task_example \
  -H "Authorization: Bearer $COMETAPI_KEY"

Ответ меняется по мере выполнения задачи. Завершенные ответы могут включать video_url, если адаптер модели предоставляет URL результата; в противном случае используйте поля результата, специфичные для модели, или content route /v1/videos/{id}/content, если эта модель поддерживает проксированные загрузки.

{
  "id": "task_example",
  "object": "video",
  "model": "doubao-seedance-2-0",
  "status": "completed",
  "progress": 100,
  "completed_at": 1779872300,
  "video_url": "<generated-video-url>"
}

Получение webhook

CometAPI не определяет один универсальный callback payload для каждой video model. Рассматривайте callbacks как pass-through events, специфичные для провайдера, сохраняйте raw body и сверяйте финальное состояние с помощью polling. Следующий обработчик Express принимает video callback и сохраняет событие:

import express from "express";

const app = express();
app.use(express.json({ limit: "2mb" }));

app.post("/cometapi/video-webhook", async (request, response) => {
  const event = request.body;

  console.log("Task ID:", event.task_id || event.id);
  console.log("Status:", event.status);

  response.status(200).json({ received: true });
});

app.listen(3000);

Callback payload обычно включает поля идентификатора задачи и статуса, но точная вложенность зависит от выбранной модели или провайдера:

{
  "task_id": "task_example",
  "status": "completed",
  "progress": 100,
  "result": {
    "video_url": "https://example.com/result.mp4"
  }
}

Распространенные ошибки

Error	Fix
Потерянный callback	Выполняйте poll по ID задачи, пока ваше приложение не сохранит терминальное состояние.
Дублирующийся callback	Сделайте обработку callback идемпотентной по ID задачи.
Callback отклонен	Быстро возвращайте ответ `2xx`, а затем обрабатывайте задачу в фоне.
Несоответствие payload, специфичного для провайдера	Сохраняйте raw callback payload и нормализуйте его в своем приложении.
Отсутствует `video_url`	Считайте `video_url` необязательным и используйте polling вместе с полями результата, специфичными для модели, или `/v1/videos/{id}/content`, когда доступно.

Начните здесь

Быстрый старт по API моделей

Основные руководства по API

Библиотеки

Ошибки

Цены и биллинг

Поддержка

Использование polling и webhooks для генерации видео

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

Poll статуса

Получение webhook

Распространенные ошибки

Связанные ссылки

​Создание видео-задачи

​Poll статуса

​Получение webhook

​Распространенные ошибки

​Связанные ссылки

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

Poll статуса

Получение webhook

Распространенные ошибки

Связанные ссылки