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çaCliente Volcengine existenteTokenLab
URL BaseSeu endpoint do Volcenginehttps://api.tokenlab.sh/
AutenticaçãoAssinatura de requisição AK/SKAuthorization: Bearer <TOKENLAB_API_KEY>
Transporte de tarefaCaminhos REST oficiais /api/v3/contents/generations/tasksPreservado
Actions de material/validaçãoParâmetros de consulta Action e VersionPreservado
Corpo da tarefacontent[] no estilo VolcenginePreservado
Corpo do materialCampos em PascalCase como GroupId e ProjectNamePreservado
Resultado assíncronoCiclo de vida de tarefa do VolcengineID 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 existenteEndpoint 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çãoPOST /?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 caminhoPropósito
POST /api/v3/contents/generations/tasksCriar uma tarefa de vídeo
GET /api/v3/contents/generations/tasks/{id}Ler uma tarefa
GET /api/v3/contents/generations/tasksListar 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:

Regras do corpo da requisição

  • content[] aceita itens text, image_url, video_url, audio_url e draft_task.
  • Para image_url, omita role ou use first_frame para imagem-para-vídeo. Use last_frame junto com um primeiro quadro, ou reference_image para referência-para-vídeo.
  • Um URI de material público como asset://asset-YYYYMMDDHHMMSS-xxxxx pode 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_after e safety_identifier. Os padrões dependem do modelo: generate_audio é false para modelos seedance-2.0 e true para seedance-2.5, e duration é 5 para modelos seedance-2.0 e -1 para seedance-2.5. Este formato REST aceita valores de resolution 480p, 720p e 1080p (480p e 720p para seedance-2.5), mas não 4k, que apenas a API unificada /v1/videos/generations aceita. seedance-2.5 rejeita seed, frames e camera_fixed.
  • callback_url aceita um endpoint HTTP(S) público. O TokenLab envia o mesmo corpo de tarefa de consulta para queued, running, succeeded, failed e expired; apenas succeeded e failed seguem 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:

  1. Criar Sessão de Validação Visual
  2. Obter Resultado de Validação Visual

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

  1. Substitua o host da API por https://api.tokenlab.sh.
  2. Substitua a assinatura AK/SK por uma chave de API Bearer do TokenLab.
  3. 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.
  4. Mantenha o mesmo ProjectName em requisições relacionadas de material e verificação.
  5. Armazene os IDs de tarefa, grupo e ativo do TokenLab retornados por esses endpoints.
  6. Verifique uma resposta de criação, polling, listagem e erro antes de mover o tráfego de produção.

Nesta página