Vídeo e materiais
Criar Tarefa (Compatível com Volc)
Crie uma tarefa Seedance com a API compatível com Volc.
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"semrole, ou comrole: "first_frame", é tratado como o primeiro quadro.role: "last_frame"deve ser pareado com um primeiro quadro.type: "video_url"requerrole: "reference_video", etype: "audio_url"requerrole: "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, 1draft_task). O Seedance 2.5 aceita até 51 (1 texto, 30 imagens, 10 vídeos, 10 áudios, 1draft_task). image_url.urlaceita uma URL de imagem pública ou uma URI de material, comoasset://asset-YYYYMMDDHHMMSS-xxxxx. Oroledetermina 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_idematerial_asset_ids, retorna400 UnsupportedParameter. Coloque uma URI de material do TokenLab emimage_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âmetro | Seedance 2.0 | Seedance 2.5 |
|---|---|---|
duration | 4–15 / -1 (padrão: 5) | 4–30 / -1 (padrão: -1) |
resolution | 480p, 720p, 1080p (padrão: 720p) | 480p, 720p (padrão: 720p) |
generate_audio | boolean (padrão: false) | boolean (padrão: true) |
priority | Não suportado | integer: 0–9 |
seed | integer: -1–4294967295 (padrão: -1) | Não suportado |
execution_expires_after | 3600–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.
ratioaceita16:9,4:3,1:1,3:4,9:16,21:9ouadaptive(padrão:adaptive).watermarkereturn_last_framesão booleanos (padrão:false).safety_identifieré uma string de até 64 caracteres.service_tieraceita apenasdefault;flexretorna400 UnsupportedParameter.toolsaceita no máximo um item,{"type": "web_search"}.draft: true,framesecamera_fixednão são suportados.camera_fixed: falseé aceito apenas para o Seedance 2.0.callback_urlpode 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 adicionaIdempotency-Replayed: true. - Reutilizar a chave com um corpo diferente retorna
409com o códigoidempotency_conflicte 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 Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.
Local: header
Cabeçalhos
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"
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.
1 <= length <= 255Corpo da requisição
application/json
Resposta
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json