API do Seedance

A API permite enviar tarefas de geração de vídeo do Seedance 2.5 e Seedance 2.0 de forma programática. O Seedance 2.5 é o modelo recomendado e suporta texto para vídeo, imagem para vídeo (com base no primeiro frame ou no primeiro e último frames) e referência multimodal para vídeo. A geração é assíncrona: você cria uma tarefa, recebe um ID de tarefa imediatamente e, em seguida, obtém o vídeo finalizado via consultas periódicas (polling) ao endpoint da tarefa ou recebendo um webhook.

Crie uma chave de API no painel de controle e envie-a como um token Bearer em cada requisição. A chave completa é exibida apenas uma vez, no momento da criação.

Authorization: Bearer sk_live_xxxxxxxx

Primeiro, envie uma tarefa. Assim que ela for aceita, escolha um método para receber o resultado: consulte periodicamente o endpoint da tarefa ou receba o resultado final por meio de um webhook.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

curl https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

Crie uma tarefa de vídeo com POST /v1/videos/generations. O corpo da requisição contém o modelo no nível superior, uma callback_url opcional e um objeto input com o prompt e as configurações de geração.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

O campo generation_type controla quais arquivos de mídia são aceitos e como o modelo os interpreta.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cinematic drone shot over a futuristic coastal city at sunrise",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "the subject turns toward camera, soft studio motion",
      "generation_type": "image-to-video",
      "image_urls": ["https://your.cdn.com/first-frame.jpg"],
      "duration": 5,
      "resolution": "720p"
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "input": {
      "prompt": "use the product from image 1 and the camera motion from the reference video",
      "generation_type": "reference-to-video",
      "image_urls": ["https://your.cdn.com/product.jpg"],
      "video_urls": ["https://your.cdn.com/camera-motion.mp4"],
      "audio_urls": [],
      "duration": 8,
      "resolution": "720p"
    }
  }'

Nomes de parâmetros, valores de enum, caminhos de endpoint e exemplos fazem parte do contrato da API. As descrições abaixo detalham o comportamento de cada campo.

Esta é a resposta de sucesso de POST /v1/videos/generations. Ela indica que a tarefa foi aceita e os créditos foram reservados. Use o taskId retornado para consultar GET /v1/tasks/:id ou para identificar o callback de conclusão ou falha.

{
  "taskId": "3f2aK9mR...",
  "credits": 100
}

Use GET /v1/tasks/:id para obter o status atual da tarefa. Faça a consulta periódica (polling) no máximo uma vez a cada 10 segundos. Para sistemas de produção, prefira webhooks.

curl https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seevio.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

Quando a callback_url é informada, o Seedance chama o seu endpoint ao concluir a tarefa (com sucesso ou falha), enviando um JSON com o resultado final. Se o seu endpoint retornar um status diferente de 2xx ou não responder em até 15 segundos, o envio será tentado novamente até 5 vezes. As tentativas de reenvio mantêm o mesmo id da tarefa, portanto, faça o tratamento de duplicatas com base nesse ID. Retorne uma resposta 200 assim que salvar os dados do callback com segurança.

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "results": ["https://cdn.seevio.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

As chamadas POST /v1/videos/generations e GET /v1/tasks/:id retornam este formato de erro quando a requisição em si falha (por exemplo, parâmetros inválidos, chave de API incorreta, créditos insuficientes, limite de requisições excedido ou tarefa não encontrada). Dependendo da situação, alguns erros incluem campos adicionais como required, available ou retry_after.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this task.",
    "required": 100,
    "available": 12
  }
}

Os limites de requisição são aplicados por chave de API com base em uma janela flutuante. O envio de geração tem um limite padrão de 100 requisições por minuto; as consultas de status possuem limites mais flexíveis. As respostas HTTP 429 incluem o cabeçalho Retry-After.

A API opera no modelo de reserva no envio, cobrança na conclusão e reembolso em caso de falha. As páginas de uso no painel exibem o histórico de créditos da API, os logs de tarefas e estatísticas de consumo por período.