Vídeo e materiais

Criar Tarefa (Compatível com Volc)

Crie uma tarefa Seedance com a API compatível com Volc.

POST
/api/v3/contents/generations/tasks

Visão Geral

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

Os exemplos utilizam o Seedance 2.0. Este endpoint também suporta o Seedance 2.5 com as diferenças específicas de modelo abaixo. Os exemplos de URI de material reutilizável do TokenLab nesta página aplicam-se ao Seedance 2.0.

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

Autenticação e Endpoints

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

Regras de Conteúdo

  • 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.
  • type: "video_url" requer role: "reference_video", e type: "audio_url" requer role: "reference_audio". role: "reference_image" marca uma imagem de referência.
  • Limites de itens: O Seedance 2.0 aceita até 16 itens de content (1 texto, 9 imagens, 3 vídeos, 3 áudios, 1 draft_task). O Seedance 2.5 aceita até 51 (1 texto, 30 imagens, 10 vídeos, 10 áudios, 1 draft_task).
  • image_url.url aceita uma URL de imagem pública ou uma 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.
  • O corpo REST aceita apenas os campos nesta página. Qualquer outro campo de nível superior, incluindo material_asset_id e material_asset_ids, retorna 400 UnsupportedParameter. Coloque uma URI de material do TokenLab em image_url.url.

Notas sobre Parâmetros

model aceita um ID de modelo do TokenLab, como seedance-2.0 ou seedance-2.5. Clientes existentes podem continuar enviando o ID de modelo da Volcengine que já utilizam para esses modelos. A resposta do get-task retorna o valor de model que você enviou. Um valor não reconhecido retorna 400 InvalidParameter.

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

ParâmetroSeedance 2.0Seedance 2.5
duration4–15 / -1 (padrão: 5)4–30 / -1 (padrão: -1)
resolution480p, 720p, 1080p (padrão: 720p)480p, 720p (padrão: 720p)
generate_audioboolean (padrão: false)boolean (padrão: true)
priorityNão suportadointeger: 0–9
seedinteger: -1–4294967295 (padrão: -1)Não suportado
execution_expires_after3600–259200 segundos (padrão: 172800)3600–259200 segundos (padrão: 172800)

Para o Seedance 2.5, solicitações de primeiro quadro, primeiro/último quadro, extensão de vídeo e vídeo-para-vídeo requerem ratio: "adaptive"; vídeo-para-vídeo também requer duration: -1. output_format aceita mp4 ou mov apenas para o Seedance 2.5.

  • ratio aceita 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 ou adaptive (padrão: adaptive).
  • watermark e return_last_frame são booleanos (padrão: false). safety_identifier é uma string de até 64 caracteres.
  • service_tier aceita apenas default; flex retorna 400 UnsupportedParameter.
  • tools aceita no máximo um item, {"type": "web_search"}.
  • draft: true, frames e camera_fixed não são suportados. camera_fixed: false é aceito apenas para o Seedance 2.0.
  • callback_url pode apontar para um endpoint HTTP(S) público de até 2.048 caracteres.

Entrega de Callback

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 do get-task.

Uma resposta 2xx confirma a entrega. Para succeeded e failed, uma entrega que não for 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 Imagem

URLs de imagem HTTP(S) públicas e URLs de dados suportadas são usadas conforme fornecidas; elas não são salvas automaticamente como materiais reutilizáveis. Referências explícitas asset://asset-... usam materiais existentes do TokenLab. O TokenLab verifica a propriedade e a prontidão antes da geração. Se um material referenciado ainda estiver sendo preparado, aguarde até que esteja pronto e tente novamente; inspecione error.code e error.message quando a criação falhar.

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ção

{
  "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 Duplicadas

Envie um Idempotency-Key único (1–255 caracteres, sem quebras de linha) 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.
  • Reutilizar a chave com um corpo diferente retorna 409 com o código idempotency_conflict e nunca cria uma segunda tarefa.
  • Uma chave com mais de 255 caracteres ou que contenha quebras de linha retorna 400 InvalidParameter.

A chave não altera o formato da resposta JSON. O TokenLab não infere duplicatas a partir de X-Request-ID ou de corpos de solicitação idênticos sem uma chave.

Exemplo

Criação REST

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.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"}
  }
]

Erros

Erros REST usam {"error": {"code", "message", "param", "type"}}. Problemas na solicitação retornam 400 com InvalidParameter ou UnsupportedParameter, e uma chave Bearer ausente retorna 401 AuthenticationError. Erros da geração de vídeo, como saldo insuficiente (402) ou limite de taxa (429), mantêm seu status HTTP.

As mesmas operações também estão disponíveis como as Ações CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks e DeleteContentsGenerationsTasks em POST /api/v3?Version=2024-01-01. Novas integrações devem usar os caminhos REST acima.

Próximo Passo

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": "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  }'
{  "id": "string"}

Autorização

BearerAuth
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Cabeçalhos

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.

Valores permitidos

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Chave gerada pelo cliente para criação de tarefa REST idempotente, de 1 a 255 caracteres sem quebras de linha. Sob a mesma credencial de API do TokenLab, reutilizar a mesma chave com o mesmo corpo JSON retorna o ID da tarefa cgt original; reutilizá-la com um corpo diferente retorna 409 com o código idempotency_conflict. Uma chave muito longa ou que contenha quebras de linha retorna 400. Mantenha a credencial, a chave e o corpo da requisição inalterados ao tentar novamente após um timeout ou desconexão.

Comprimento1 <= length <= 255

Corpo da requisição

application/json

Resposta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json