Criar Tarefa (Compatível com Volc)

Visão GeralCopy Anchor Link

Clientes Seedance existentes no estilo Volc podem usar o TokenLab alterando o endereço da API e a chave.

Veja também Modelos de Vídeo Seedance 2.0 e Geração de Vídeo.

Autenticação e EndpointsCopy Anchor Link

• Use Authorization: Bearer <TOKENLAB_API_KEY>.
• A assinatura Volc AK/SK não é aceita. As solicitações devem incluir uma chave TokenLab Bearer.
• Use o caminho oficial da tarefa: POST /api/v3/contents/generations/tasks.

Regras de ConteúdoCopy Anchor Link

• type: "text" é o texto do prompt.
• type: "image_url" sem role, ou com role: "first_frame", é tratado como o primeiro quadro.
• role: "last_frame" deve ser pareado com um primeiro quadro.
• role: "reference_image", reference_video e reference_audio são usados como referências.
• image_url.url aceita uma URL de imagem pública ou um URI de material como asset://asset-YYYYMMDDHHMMSS-xxxxx. O role determina se esse material é um primeiro quadro, último quadro ou imagem de referência.
• Não misture entradas de primeiro/último quadro com mídia de referência em uma única solicitação.
• Os campos de nível superior material_asset_id e material_asset_ids são rejeitados. Coloque o URI de material TokenLab em image_url.url. priority é aceito somente para Seedance 2.5.

Notas sobre ParâmetrosCopy Anchor Link

duration é um número inteiro de segundos; -1 seleciona a duração automática. Os padrões e limites dependem do modelo:

No Seedance 2.5, solicitações de primeiro quadro, primeiro/último quadro, extensão de vídeo e vídeo para vídeo exigem ratio: "adaptive". Vídeo para vídeo também exige duration: -1. output_format aceita mp4 ou mov somente para Seedance 2.5.

• ratio aceita 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 ou adaptive.
• watermark, return_last_frame, seed, execution_expires_after e safety_identifier são aceitos quando válidos para o modelo selecionado.
• callback_url pode apontar para um endpoint HTTP(S) público.

Entrega de CallbackCopy Anchor Link

Quando callback_url está presente, o TokenLab envia um POST HTTP quando o status da tarefa muda. Os status de callback são queued, running, succeeded, failed e expired. O corpo JSON corresponde à resposta de get-task.

Uma resposta 2xx confirma o recebimento. Para succeeded e failed, uma entrega que não seja bem-sucedida em cinco segundos é tentada novamente até três vezes. O callback possui apenas o cabeçalho de conteúdo JSON padrão e nenhum cabeçalho de entrega específico do TokenLab. Redirecionamentos não são seguidos, e destinos de rede privados ou reservados são rejeitados.

Salve o ID da tarefa. Se um callback não for entregue, você ainda pode recuperar o resultado com o endpoint get-task.

Preparação de ImagemCopy Anchor Link

URLs públicas de imagens HTTP(S) e URLs data compatíveis são usadas como fornecidas, sem serem salvas automaticamente como materiais reutilizáveis. Referências explícitas asset://asset-... usam materiais TokenLab existentes. A propriedade e a disponibilidade são verificadas antes da geração. Se um material ainda estiver em preparação, aguarde até ficar pronto e tente novamente. Em caso de falha, consulte error.code e error.message.

Para materiais existentes, use o ID público asset-YYYYMMDDHHMMSS-xxxxx em vez de um ID de ativo original retornado por outro sistema. O TokenLab verifica a propriedade do material antes da geração.

Resposta de CriaçãoCopy Anchor Link

{
  "id": "cgt-20260102030405-a1b2c"
}

A resposta de criação contém apenas o ID da tarefa. Salve-o para que você possa recuperar o status e os resultados a qualquer momento.

Prevenir Tarefas DuplicadasCopy Anchor Link

Envie um Idempotency-Key exclusivo com as solicitações de criação. Se a conexão for encerrada antes que a resposta chegue, tente novamente com a mesma chave de API, chave de idempotência e corpo da solicitação:

• Se a tarefa original foi criada, o TokenLab retorna o mesmo ID cgt-... e adiciona Idempotency-Replayed: true.
• Se a solicitação original ainda estiver sendo registrada, TokenLab retorna 409 IdempotencyRequestInProgress. Tente novamente mais tarde com a mesma chave e o mesmo corpo.
• Reutilizar a chave com um corpo diferente retorna 409 IdempotencyConflict e nunca cria uma segunda tarefa.

A idempotência se aplica ao caminho de criação REST v3 oficial. Ela não altera a forma da resposta JSON e não é inferida a partir de X-Request-ID ou de corpos de solicitação idênticos sem uma chave.

ExemploCopy Anchor Link

Criação RESTCopy 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": "doubao-seedance-2.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

Para materiais existentes, coloque cada URI no item content[] oficial e declare sua função:

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

Próximo PassoCopy Anchor Link

Use o ID cgt-... retornado com Obter Tarefa (Compatível com Volc) até que a tarefa atinja um status terminal.

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedance-2-0-260128",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'

{  "id": "string"}