Guias de mídia
Migrar Seedance do Volcengine
Mantenha seu formato de requisição do Volcengine e mude o Seedance para o TokenLab
Se sua aplicação já utiliza a API Seedance do Volcengine, você pode manter seus caminhos REST, o corpo content[], campos de resposta, callbacks e as Actions de material em PascalCase. Altere o host da API e substitua a assinatura AK/SK por uma chave de API do TokenLab.
O que muda
| Mudança | Cliente Volcengine existente | TokenLab |
|---|---|---|
| URL Base | Seu endpoint do Volcengine | https://api.tokenlab.sh/ |
| Autenticação | Assinatura de requisição AK/SK | Authorization: Bearer <TOKENLAB_API_KEY> |
| Transporte de tarefa | Caminhos REST oficiais /api/v3/contents/generations/tasks | Preservado |
| Actions de material/validação | Parâmetros de consulta Action e Version | Preservado |
| Corpo da tarefa | content[] no estilo Volcengine | Preservado |
| Corpo do material | Campos em PascalCase como GroupId e ProjectName | Preservado |
| Resultado assíncrono | Ciclo de vida de tarefa do Volcengine | ID de tarefa cgt-... do TokenLab com polling e callback opcional |
Requisições assinadas apenas com AK/SK retornam 401 AuthenticationError. Toda requisição do TokenLab deve incluir Authorization: Bearer <TOKENLAB_API_KEY>.
Escolha um endpoint
| Cliente existente | Endpoint do TokenLab |
|---|---|
| Cliente de tarefa REST do Volcengine | /api/v3/contents/generations/tasks e seus caminhos de tarefa |
| Cliente de Action de material ou validação | POST /?Action=...&Version=2024-01-01 ou POST /api/v3?Action=...&Version=2024-01-01 |
Para tarefas de vídeo, mantenha o método REST, o caminho e o corpo JSON existentes. As requisições de material e verificação continuam a usar os parâmetros de consulta Action e Version. O endpoint de Action também aceita as Actions de tarefa CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks e DeleteContentsGenerationsTasks; use os caminhos REST para novos trabalhos.
Caminhos de tarefa oficiais
| Método e caminho | Propósito |
|---|---|
POST /api/v3/contents/generations/tasks | Criar uma tarefa de vídeo |
GET /api/v3/contents/generations/tasks/{id} | Ler uma tarefa |
GET /api/v3/contents/generations/tasks | Listar tarefas |
DELETE /api/v3/contents/generations/tasks/{id} | Cancelar uma tarefa que ainda está na fila. Uma tarefa que já iniciou retorna 409 task_not_cancellable |
Clientes REST podem usar estas referências equivalentes:
- Criar Tarefa (Compatível com Volc)
- Obter Tarefa (Compatível com Volc)
- Listar Tarefas (Compatível com Volc)
- Cancelar Tarefa (Compatível com Volc)
Regras do corpo da requisição
content[]aceita itenstext,image_url,video_url,audio_urledraft_task.- Para
image_url, omitaroleou usefirst_framepara imagem-para-vídeo. Uselast_framejunto com um primeiro quadro, oureference_imagepara referência-para-vídeo. - Um URI de material público como
asset://asset-YYYYMMDDHHMMSS-xxxxxpode ser usado onde o fluxo de trabalho Seedance selecionado aceitar essa função de mídia. - O corpo REST aceita apenas campos oficiais, incluindo
model,content,ratio,duration,resolution,generate_audio,watermark,return_last_frame,seed,execution_expires_afteresafety_identifier. Os padrões dependem do modelo:generate_audioéfalsepara modelosseedance-2.0etrueparaseedance-2.5, edurationé5para modelosseedance-2.0e-1paraseedance-2.5. Este formato REST aceita valores deresolution480p,720pe1080p(480pe720pparaseedance-2.5), mas não4k, que apenas a API unificada/v1/videos/generationsaceita.seedance-2.5rejeitaseed,framesecamera_fixed. callback_urlaceita um endpoint HTTP(S) público. O TokenLab envia o mesmo corpo de tarefa de consulta paraqueued,running,succeeded,failedeexpired; apenassucceededefailedseguem o comportamento oficial: um timeout de cinco segundos e uma nova tentativa quando seu endpoint não reconhece a notificação.
Exemplo REST mínimo
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"
}'Armazene o ID cgt-... retornado. Faça polling até que o status se torne succeeded, failed, cancelled ou expired; não trate a resposta de criação como um vídeo concluído. Se você fornecer callback_url, permita notificações repetidas de succeeded ou failed e mantenha o polling como um caminho de recuperação.
Mantenha os tipos v1 e v3 separados
Não reutilize uma estrutura de resposta /v1/tasks/{id} para este endpoint. A API v1 unificada reporta pending, processing, completed e failed; a API v3 compatível com Volc reporta queued, running, succeeded, failed, cancelled e expired. A resposta oficial da v3 também representa duration como uma string JSON e omite error em tarefas não falhas.
Para uma recuperação segura após um timeout de criação ou desconexão, adicione um Idempotency-Key único à requisição de criação REST. Tentar novamente o mesmo corpo com a mesma chave retorna o ID cgt-... original; a mesma chave com um corpo diferente retorna 409.
Materiais e verificação de pessoa real
O mesmo endpoint de Action também suporta as 10 operações de material e grupo de material. Veja Material Actions (Compatível com Volc) para seus corpos exatos em PascalCase, filtros, paginação, envelope de resposta e URLs de material de 12 horas.
Materiais de pessoa real adicionam duas Actions antes do upload:
A segunda Action retorna o GroupId verificado. Use esse ID com CreateAsset; um cliente não pode criar um grupo LivenessFace diretamente.
Checklist de migração
- Substitua o host da API por
https://api.tokenlab.sh. - Substitua a assinatura AK/SK por uma chave de API Bearer do TokenLab.
- Mantenha o método, caminho e casing do corpo da requisição REST oficiais; mantenha Action e version apenas para operações de material ou validação.
- Mantenha o mesmo
ProjectNameem requisições relacionadas de material e verificação. - Armazene os IDs de tarefa, grupo e ativo do TokenLab retornados por esses endpoints.
- Verifique uma resposta de criação, polling, listagem e erro antes de mover o tráfego de produção.