Migrar Seedance do Volcengine

Use este guia quando sua aplicação já envia solicitações Seedance no formato Volcengine. Nomes de Action, Version=2024-01-01, content[], corpos PascalCase de materiais e o envelope de resposta Volcengine podem ser mantidos. Apenas endpoint e autenticação precisam mudar.

O que mudaCopy Anchor Link

Solicitações apenas com assinatura AK/SK retornam 401 AuthenticationError. Clientes Action podem usar POST /?Action=...&Version=2024-01-01; POST /api/v3?Action=...&Version=2024-01-01 continua disponível. Clientes REST usam /api/v3/contents/generations/tasks.

Formato da solicitação e ciclo da tarefaCopy Anchor Link

Se sua integração já envia solicitações Seedance no estilo Volc, use o endpoint compatível em vez de remodelar o body para /v1/videos/generations. Envie sua API key TokenLab como Authorization: Bearer ..., use POST /api/v3/contents/generations/tasks para criação REST ou /api/v3?Action=CreateContentsGenerationsTasks&Version=2024-01-01 para solicitações Action. A criação retorna um ID cgt-...; respostas de status usam queued, running, succeeded, failed, cancelled ou expired.

Este endpoint aceita itens content[] como text, image_url, video_url, audio_url e draft_task. callback_url recebe o mesmo objeto de consulta em cada mudança para queued, running, succeeded, failed ou expired; succeeded e failed são repetidos até três vezes após cinco segundos. Mantenha a consulta como recuperação.

Páginas de referênciaCopy Anchor Link

• Criar tarefa (compatível com Volc)
• Obter tarefa (compatível com Volc)
• Listar tarefas (compatível com Volc)
• Cancelar tarefa (compatível com Volc)

Não reutilize a struct de /v1/tasks/{id} no v3. O v1 usa pending, processing, completed e failed; o v3 usa queued, running, succeeded, failed, cancelled e expired. No v3, duration é uma string e error só aparece em falhas.

Para recuperar após uma desconexão, envie um Idempotency-Key único na criação REST. O mesmo body e chave retornam o mesmo ID cgt-...; outro body com a mesma chave retorna 409.

Actions de tarefaCopy Anchor Link

Exemplo REST mínimoCopy Anchor Link

curl 'https://api.tokenlab.sh/api/v3/contents/generations/tasks' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"seedance-2.5",
    "content":[
      {"type":"text","text":"A cinematic product reveal"},
      {"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
    ],
    "ratio":"16:9",
    "duration":5,
    "resolution":"720p"
  }'

Materiais e verificação de pessoasCopy Anchor Link

O mesmo endpoint Action aceita dez operações de materiais e grupos. Consulte Actions de materiais compatíveis com Volcengine para corpos PascalCase, filtros, paginação, envelope e URLs de 12 horas. Para pessoas reais, antes do upload também use Criar sessão de verificação visual e Obter resultado da verificação visual.

Checklist de migraçãoCopy Anchor Link

1. Troque o host da API por https://api.tokenlab.sh.
2. Substitua a assinatura AK/SK por uma chave API Bearer do TokenLab.
3. Mantenha Action, versão e capitalização do corpo.
4. Use o mesmo ProjectName em solicitações relacionadas de materiais e verificação.
5. Armazene os IDs de tarefa, grupo e material retornados pelo TokenLab.
6. Valide criação, polling, listagem e erro antes de mover tráfego de produção.