Visão geral
A geração de vídeo é assíncrona. Você envia uma solicitação, recebe umatask_id e um poll_url, e então faz polling até obter o resultado final.
Comportamento de polling
Para o comportamento de polling mais confiável, use exatamente opoll_url retornado pela resposta de criação.
Se uma resposta de criação retornar poll_url, chame exatamente essa URL. Quando ela apontar para /v1/tasks/{id}, trate-a como o endpoint fixo canônico de status.
Comportamento de modelos e mídia
A saída de áudio depende do modelo. No TokenLab, solicitações Veo 3 e Seedance ativam áudio por padrão quandooutput_audio é omitido. Quando um modelo oferece controle de áudio, use output_audio para alternar explicitamente. Os aliases outputAudio e generate_audio são aceitos por compatibilidade e devem corresponder a output_audio quando mais de um for enviado.
Em integrações de produção, prefira URLs https públicas para imagens, vídeos e áudio. Modelos compatíveis continuam aceitando URLs data:, mas payloads base64 grandes dificultam retry, observabilidade e depuração.
Corpo da requisição
ID do modelo de video. Use IDs logicos de produto como
veo3.1, wan-2.7, happyhorse-1.0, viduq3, pixverse-v6 ou kling-3.0-video; escolha text-to-video, image-to-video, reference-to-video ou outras variantes com operation. Consulte o guia de video e a Models API.PixVerse
- Modelo:
pixverse-c1,pixverse-v6,pixverse-v5.6 - Operações:
text-to-video,image-to-video,start-end-to-video,reference-to-video - Seletor de áudio:
output_audio, padrãofalse
operation=video-extension.HappyHorse- Modelo:
happyhorse-1.0 - Operações:
text-to-video,image-to-video,reference-to-video,video-to-video - Seletor de áudio: Não envie
output_audio
Descrição em texto do vídeo a ser gerado. Este campo é obrigatório para a maioria dos modelos públicos de vídeo.
Operação de vídeo a ser executada. O detalhes do modelo suporta
text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension, audio-to-video e motion-control. A TokenLab pode inferir a operação a partir das entradas, mas em produção o ideal é informá-la explicitamente.URL pública da imagem inicial para fluxos image-to-video. Para a compatibilidade mais ampla entre modelos, prefira
image_url.Imagem inline como URL
data: (por exemplo, data:image/jpeg;base64,...). Modelos compatíveis aceitam esse formato, mas image_url costuma ser mais robusto em produção.Imagens de referência para fluxos com condicionamento dedicado. A quantidade suportada depende do modelo. Para
seedance-2.0 e seedance-2.0-fast, a TokenLab suporta atualmente até 9 imagens de referência, além de até 3 vídeos de referência e 3 áudios de referência. Para escolha de modelo, limites de 4K e notas sobre Mini, consulte o guia de modelos de vídeo Seedance 2.0. Recomendam-se URLs públicas https; modelos compatíveis também aceitam URLs data:. Para grok-imagine-video, reference-to-video aceita até 7 referências de imagem e duration é limitado a 10 segundos. grok-imagine-video-1.5-preview é apenas image-to-video e não aceita referências de imagem.ID de material Seedance do TokenLab retornado por Criar material ou pela preparação automática de imagem. Use-o após o material ficar
ACTIVE com modelos Seedance que possam usar a biblioteca de materiais do TokenLab.Vários IDs de material Seedance do TokenLab. Eles compartilham o limite de referências de imagem do Seedance com
reference_images; o modelo selecionado precisa poder usar a biblioteca de materiais do TokenLab.Quando o modelo Seedance selecionado pode usar a biblioteca de materiais do TokenLab, o TokenLab prepara os campos de imagem (
image, image_url, image_urls, reference_images, start_image, end_image) como materiais reutilizáveis antes da geração. Se a preparação não terminar em 60 segundos, a API retorna 409 seedance_material_preparing com auto_material_asset_ids; tente novamente quando esses materiais estiverem ACTIVE. Se o modelo selecionado não puder usar a biblioteca de materiais, entradas comuns de imagem continuam pelo caminho normal de imagem e IDs de material explícitos falham com segurança com um erro de disponibilidade de material que pode ser repetido.Campo opcional para modelos que distinguem entre referências
asset e style.Definições de referências de elementos do Kling 3.0. Suportadas apenas por
kling-3.0-video em solicitações condicionadas por imagem. Defina 1-3 elementos; cada elemento tem name, description opcional e element_input_urls com 2-4 URLs de imagem. Referencie o elemento no prompt como @name. Não combine kling_elements com output_audio=true; omita output_audio ou defina como false em solicitações com referências de elementos.URL pública do vídeo de origem. Necessária para fluxos
video-to-video baseados em URL de vídeo e para motion-control; alguns fluxos derivados usam task_id em vez disso.Entradas adicionais de vídeo de referência para modelos com condicionamento multimodal. A quantidade suportada depende do modelo. Para
seedance-2.0 e seedance-2.0-fast, a TokenLab suporta atualmente até 3 vídeos de referência.URL pública de áudio para modelos que suportam
audio-to-video.Entradas adicionais de áudio de referência para modelos com condicionamento multimodal. A quantidade suportada depende do modelo. Para
seedance-2.0 e seedance-2.0-fast, a TokenLab suporta atualmente até 3 áudios de referência.Identificador de tarefa usado por alguns fluxos de continuação, extensão ou derivados.
Deslocamento inicial específico do modelo para alguns fluxos
video-extension.Multiplicador ou quantidade de repetições específica do modelo para alguns fluxos
video-extension.Duração do vídeo de saída gerado, em segundos. Para modelos Seedance 1.5/2.0, omitir este campo usa
5; enviar -1 permite que o modelo escolha dentro da faixa suportada, e a cobrança é estimada de forma conservadora até a tarefa terminar.Alias compatível de
duration. Se seconds e duration forem enviados juntos, os valores devem ser idênticos. Para Seedance, seconds=-1 tem o mesmo significado de duração automática que duration=-1.Proporção canônica, por exemplo
adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 ou 21:9. Seedance usa adaptive por padrão quando omitido.Resolução de saída dependente do modelo. Seedance usa
720p por padrão; seedance-2.0 aceita 480p, 720p, 1080p e 4k, enquanto seedance-2.0-fast e seedance-2.0-mini são limitados a 480p e 720p.Alternância canônica de saída de áudio dependente do modelo. Veo 3 e Seedance usam
true por padrão quando omitido. kling-3.0-video aceita este seletor para solicitações sem referência de elemento e gera saída sem áudio por padrão quando omitido. Não combine output_audio=true com kling_elements.Flag do fluxo Draft do Seedance 1.5 Pro. Use
draft=true com modelos Seedance que oferecem suporte a tarefas draft. Não envie junto com draft_task_id.ID da tarefa draft do Seedance 1.5 Pro para promoção. Envie o ID de uma tarefa draft anterior para criar o vídeo final; este não é um campo genérico de vídeo.
Alias compatível de
aspect_ratio. Se ratio e aspect_ratio forem enviados juntos, devem ser idênticos.Alias compatível de
output_audio. Se generate_audio, output_audio e outputAudio aparecerem juntos, todos os valores devem corresponder.Janela opcional de expiração de execução em segundos para modelos de vídeo compatíveis. Seedance usa
172800 segundos por padrão quando omitido.Prioridade opcional da tarefa de
0 a 9 para modelos de vídeo compatíveis. Não combine priority com service_tier=flex.Identificador opcional de segurança do usuário final para modelos de vídeo compatíveis. Se omitido para Seedance, TokenLab usa
user quando fornecido.default é aceito como no-op compatível para modelos Seedance 2.0. flex só é permitido quando o modelo selecionado oferece suporte.Contagem opcional de frames para modelos de vídeo compatíveis. Modelos Seedance 2.0 e Seedance 1.5 Pro não aceitam este campo.
Seletor opcional de câmera fixa para modelos de vídeo compatíveis. Modelos Seedance 2.0 não aceitam este campo.
Quadros por segundo (1-120). Só tem efeito em modelos que expõem controle de FPS.
Elementos que devem ser evitados no vídeo gerado.
Seed aleatória para geração reproduzível. Seedance usa
-1 como seed aleatória quando omitida.Intensidade de aderência ao prompt (0-20) nos modelos que expõem esse controle.
Intensidade de movimento (0-1) nos modelos que expõem esse controle.
URL da imagem do primeiro quadro, ou entrada compatível, para
start-end-to-video.URL da imagem do último quadro, ou entrada compatível, para
start-end-to-video.Nível de tamanho específico do modelo para modelos de vídeo compatíveis.
Alternância opcional de marca d’água para modelos que a expõem. Seedance usa
false por padrão quando omitido.Seletor de efeito específico do modelo para alguns fluxos especializados de edição ou efeitos.
Identificador único do usuário final. Para Seedance, TokenLab também usa esse valor como
safety_identifier quando esse campo é omitido.Notas de compatibilidade
- Os campos públicos canônicos usam snake_case:
reference_images,reference_image_typeeoutput_audio. - Os campos públicos canônicos continuam em snake_case:
aspect_ratio,output_audio,reference_imagesereference_image_type. - Por compatibilidade, TokenLab também aceita
ratio,generate_audio,outputAudio,seconds,referenceImagesereferenceImageType. - Se campos canônicos e aliases forem enviados juntos, seus valores devem coincidir; aliases conflitantes são rejeitados antes da criação da tarefa.
Boas práticas para entradas de mídia
- Para
image_url,reference_images,video_urleaudio_url, prefira URLshttpspúblicas. - Sempre que possível, evite misturar base64 inline e URLs remotas na mesma requisição.
- Garanta que URLs remotas de mídia permaneçam válidas durante retries e criação assíncrona da tarefa.
Parâmetros Seedance
Para modelos Seedance 1.5/2.0, o endpoint unificado segue os nomes de campo do TokenLab e aceita os aliases compatíveisseconds, ratio e generate_audio. Seletores Seedance omitidos usam estes padrões: duration=5, resolution=720p, aspect_ratio=adaptive, output_audio=true, watermark=false, return_last_frame=false, execution_expires_after=172800, priority=0 e seed=-1.
duration=-1 ou seconds=-1 permite que Seedance escolha a duração de saída dentro da faixa suportada pelo modelo. TokenLab estima o custo de forma conservadora antes da tarefa terminar e depois liquida pelo usage da tarefa concluída quando disponível. service_tier=default é aceito como no-op compatível para Seedance 2.0; service_tier=flex, frames e camera_fixed são rejeitados quando o modelo selecionado não oferece suporte.
Exemplo Seedance
cURL
Resposta
Identificador canônico da tarefa assíncrona. Quando
id e task_id estiverem presentes juntos, trate-os como a mesma tarefa.Identificador único da tarefa para polling.
URL de polling recomendada para esta tarefa. Use exatamente esse caminho ao consultar o status.
ID de transação de faturamento da TokenLab quando a liquidação já foi concluída. Este é o identificador usado no dashboard / conciliação e é separado do
id / task_id assíncrono.Status inicial:
pending.Timestamp Unix de criação da tarefa.
Modelo utilizado.
Imagem para vídeo
Kling 3.0 Elements
Usekling_elements com kling-3.0-video quando precisar de referências de elementos. Forneça uma solicitação condicionada por imagem (image_url, image_urls, start_image ou end_image) e referencie cada elemento no prompt com @name. Não combine kling_elements com output_audio=true; omita output_audio ou defina como false em solicitações com referências de elementos.
Referência para vídeo
Useoperation=reference-to-video quando o modelo suportar condicionamento dedicado por referência. No detalhes do modelo da TokenLab, referências de imagem usam reference_images, enquanto vídeos e áudios de referência multimodais usam video_urls e audio_urls. Para seedance-2.0 e seedance-2.0-fast, a TokenLab suporta atualmente até 9 imagens de referência, além de até 3 vídeos de referência e 3 áudios de referência. Para escolha de modelo, limites de 4K e notas sobre Mini, consulte o guia de modelos de vídeo Seedance 2.0. duration controla apenas a duração do resultado gerado; ele não define um limite separado para a duração do vídeo de referência de entrada. Para grok-imagine-video, reference-to-video aceita até 7 referências de imagem (reference_images ou image_urls) e duration é limitado a 10 segundos. Não combine referências de imagem com entradas de primeiro frame image_url / image. grok-imagine-video-1.5-preview é apenas image-to-video.
Controle de quadro inicial e final
Usestart_image e end_image para controlar o primeiro e o último quadro.
Vídeo para vídeo
Para video-to-video comgrok-imagine-video, envie uma URL HTTPS pública .mp4 em video_url. O TokenLab traduz isso para o corpo REST xAI video.url. Você pode definir resolution como 480p ou 720p; duration e aspect_ratio não são aceitos nesse fluxo de edição.
Quando um modelo aceita um vídeo existente como entrada principal, use operation=video-to-video.
Controle de movimento
Quando um modelo precisa tanto de uma imagem do sujeito quanto de um vídeo de referência de movimento, useoperation=motion-control. A TokenLab normaliza a forma pública image_url + video_url para o formato de solicitação esperado pelo modelo.
Descoberta de modelos
O inventário público de vídeo e as operações compatíveis mudam com o tempo. Use a Models API como referência atual antes de integrar um fluxo específico de modelo:tokenlab.capabilities, tokenlab.supported_operations, GET /v1/models e GET /v1/models/{model} na resposta de detalhe do modelo. Operações como audio-to-video e video-extension são específicas de cada modelo; confirme a disponibilidade atual ali, em vez de depender de exemplos estáticos desta página.