Use polling e webhooks para geração de vídeo

Use polling como base para geração de vídeo porque todo job assíncrono retorna um ID de tarefa que você pode consultar. Adicione webhooks apenas quando o endpoint de vídeo selecionado oferecer suporte a URLs de callback e mantenha o polling como fonte da verdade para callbacks perdidos ou entregues de forma específica pelo provedor.

Criar uma tarefa de vídeo

A solicitação a seguir cria uma tarefa de vídeo mínima e armazena o ID retornado. Adicione campos de duração, resolução ou callback apenas quando a página do modelo selecionado documentar esses campos.

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"

A resposta inclui um ID de tarefa e um status:

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

Consultar status

A solicitação a seguir verifica o status da tarefa de vídeo:

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

A resposta muda conforme a tarefa avança. Respostas concluídas podem incluir video_url quando o adaptador do modelo tiver uma URL de resultado; caso contrário, use campos de resultado específicos do modelo ou a rota de conteúdo /v1/videos/{id}/content quando esse modelo oferecer suporte a downloads por proxy.

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

Receber um webhook

O CometAPI não define um payload de callback universal para todos os modelos de vídeo. Trate os callbacks como eventos pass-through específicos do provedor, armazene o corpo bruto e reconcilie o estado final com polling. O handler Express a seguir aceita um callback de vídeo e armazena o evento:

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);

Um payload de callback normalmente inclui identidade da tarefa e campos de status, mas a estrutura exata depende do modelo ou provedor selecionado:

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

Erros comuns

Error	Fix
Callback perdido	Faça polling pelo ID da tarefa até que seu app tenha armazenado um estado terminal.
Callback duplicado	Torne o tratamento de callbacks idempotente por ID de tarefa.
Callback rejeitado	Retorne uma resposta `2xx` rapidamente e depois processe o job em segundo plano.
Incompatibilidade de payload específico do provedor	Armazene o payload bruto do callback e normalize-o no seu app.
`video_url` ausente	Trate `video_url` como opcional e use polling junto com campos de resultado específicos do modelo ou `/v1/videos/{id}/content` quando disponível.

Comece aqui

Guias rápidos da API de modelos

Guias principais da API

Bibliotecas

Erros

Preços e faturamento

Suporte

Use polling e webhooks para geração de vídeo

Criar uma tarefa de vídeo

Consultar status

Receber um webhook

Erros comuns

Links relacionados

​Criar uma tarefa de vídeo

​Consultar status

​Receber um webhook

​Erros comuns

​Links relacionados

Criar uma tarefa de vídeo

Consultar status

Receber um webhook

Erros comuns

Links relacionados