Vídeo e materiais
Criar Vídeo
Iniciar uma tarefa de geração de vídeo
Visão Geral
A geração de vídeo é assíncrona. Uma requisição de criação bem-sucedida retorna um id de tarefa (o mesmo valor de task_id) e uma poll_url. Chame GET /v1/tasks/{id} com esse ID até que o status seja completed ou failed, e então leia video_url. Consulte Obter Status do Vídeo.
- O arquivo de resultado é salvo por 30 dias. Faça o download se precisar dele por mais tempo; consulte Retenção de dados.
- Uma tarefa do Seedance na fila pode ser cancelada com Cancelar Tarefa.
- O custo pode ser reservado quando a tarefa é aceita e liquidado quando a tarefa termina ou falha. Consulte Faturamento e Preços.
- Envie um cabeçalho
Idempotency-Keypara tentar novamente uma requisição de criação com segurança após um timeout.
Cada modelo aceita suas próprias operações e campos. GET /v1/models/{model} (Obter Modelo) lista, para cada operação, os campos, resoluções, durações e proporções de tela aceitos. Um campo ou valor fora dessa lista retorna 400 com os valores aceitos. Defina duration, resolution, aspect_ratio e output_audio você mesmo: quando você omite um, o TokenLab usa o padrão do modelo para a operação e, se nenhum padrão corresponder, a requisição retorna 400 e indica o campo a ser definido.
Entrada de Áudio e Mídia
O comportamento do áudio depende do modelo selecionado e da operação. Um vídeo pode conter som mesmo quando nenhum seletor de áudio é exibido. Omitir um seletor é diferente de enviar false.
veo3.1,veo3.1-fasteveo3.1-litesempre geram áudio. Omitaoutput_audioou envietrue;falseé rejeitado.wan-2.6ewan-2.7sempre incluem áudio. Omitaoutput_audioou envietrue.wan-3.0ewan-3.0-primetambém sempre incluem áudio e não aceitam nenhum seletor de áudio.hailuo-h3gera áudio nativo e não possui um botão de mudo. Não envie um seletor de áudio que não esteja listado nos detalhes do modelo.viduq3-proeviduq3-turbogeram áudio por padrão; envieoutput_audio: false(ouaudio: false) para uma saída sem som. Os modelos Seedance e PixVerse aceitamoutput_audio; envie-o explicitamente em vez de depender do padrão. Use-o apenas para operações que o listam.audio_url/audio_urlsfornecem áudio de entrada ou de referência. Eles não são seletores de saída de áudio. Edição de vídeo, transferência de movimento e transferência de estilo podem manter a trilha sonora de entrada; preservar o áudio de origem não significa silenciá-lo.
Verifique os detalhes do modelo para valores permitidos e preços dependentes de áudio. Onde um modelo os lista, os aliases outputAudio, generate_audio e o booleano audio devem concordar com output_audio quando combinados. Não presuma que todas as versões ou operações em uma família de modelos compartilham os mesmos controles de áudio.
Use URLs https acessíveis publicamente para imagens, vídeos e áudio, e mantenha-as válidas até que a tarefa seja iniciada. Uma URL de mídia pode ter até 8.192 caracteres. Alguns modelos também aceitam URLs de imagem inline data: (até 2.000.000 de caracteres por campo); URLs são mais confiáveis para arquivos grandes. Não misture base64 inline e URLs remotas na mesma requisição.
Corpo da Requisição
veo3.1ID do modelo de vídeo. Liste os modelos de vídeo atuais com Listar modelos (recommended_for=video) e envie o modelo explicitamente.
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
No TokenLab, os modelos PixVerse acima não aceitam 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, com até 10.000 caracteres. A maioria das operações requer uma; os detalhes do modelo informam quais não requerem.
Modo de geração: text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension ou motion-control. Cada modelo suporta apenas alguns deles; os outros retornam 400 unsupported_operation. Se você omiti-lo, o TokenLab o infere a partir das entradas: um task_id com extend_at ou extend_times resulta em video-extension, imagens ou materiais de referência resultam em reference-to-video, end_image resulta em start-end-to-video, uma entrada de vídeo resulta em video-to-video, uma entrada de imagem (image, image_url, image_urls ou start_image) resulta em image-to-video e, caso contrário, text-to-video. Envie-o explicitamente para que um campo incompatível falhe precocemente.
URL publicamente acessível da imagem do primeiro quadro. Os modelos Seedance 2.0 também aceitam asset://asset-YYYYMMDDHHMMSS-xxxxx para usar um material ACTIVE do TokenLab como o primeiro quadro. Prefira uma URL https para o suporte mais amplo entre os modelos.
Imagem inline como data URL (por exemplo, data:image/jpeg;base64,...). Apenas alguns modelos aceitam; image_url funciona em mais modelos.
URLs de imagem para modelos que listam este campo. Consulte reference_images para os limites de contagem.
Imagens de referência para reference-to-video, como URLs https ou data URLs. O limite de contagem depende do modelo:
seedance-2.0,seedance-2.0-fasteseedance-2.0-mini: até 9 referências de imagem no total, incluindo assets de material. Mais do que isso retorna400 too_many_seedance_reference_images.seedance-2.5: até 30 entradas de imagem no total combinandoimage_urlsereference_images.grok-imagine-video: até 7, e adurationé limitada a 10 segundos.grok-imagine-video-1.5egrok-imagine-video-1.5-previewnão aceitam imagens de referência.- Outros modelos: consulte os detalhes do modelo. Uma requisição acima do limite retorna
400 too_many_items.
Os modelos Seedance 2.0 também aceitam asset://asset-YYYYMMDDHHMMSS-xxxxx para um material ACTIVE do TokenLab. Para seleção de modelo, limites de 4K e observações sobre o Mini, consulte o Guia de modelos de vídeo Seedance 2.0. Para grok-imagine-video, não combine imagens de referência com image_url ou image.
Imagem do primeiro quadro. Com end_image, a requisição é start-end-to-video. Sem end_image, é image-to-video, e start_image funciona como image em modelos cujo contrato a lista. Aceita uma URL pública ou uma data URL; modelos Seedance 2.0 também aceitam asset://asset-YYYYMMDDHHMMSS-xxxxx.
Imagem do último quadro para start-end-to-video. Aceita as mesmas entradas que start_image.
ID de asset de material Seedance do TokenLab retornado por Criar Asset de Material. Aceito apenas pelos modelos Seedance 2.0; outros modelos retornam 400 unsupported_seedance_material_asset_model. O asset deve estar ACTIVE e pertencer à sua conta. Este campo é uma entrada de referência genérica; para atribuir significado explícito de primeiro quadro, último quadro ou imagem de referência, utilize asset://<material_asset_id> em start_image, end_image ou reference_images.
Até 9 IDs de asset de material Seedance do TokenLab. Eles contam para o limite de 9 referências de imagem dos modelos Seedance 2.0.
URLs de imagem comuns são passadas como entradas de imagem; elas não criam assets de material reutilizáveis. Crie assets reutilizáveis por meio da API de material e use seus IDs do TokenLab ou URIs asset://asset-YYYYMMDDHHMMSS-xxxxx. Se um material explícito retornar 409 seedance_material_preparing, verifique os inactive_asset_ids retornados e tente novamente após esses materiais se tornarem ACTIVE.
URL publicamente acessível do vídeo de origem para as operações que o utilizam: video-to-video, video-extension e motion-control, em modelos que listam este campo.
Vídeos de origem ou de referência para modelos que listam este campo. O seedance-2.5 aceita até 10 entradas de vídeo no total combinando video_url e video_urls. Consulte os detalhes do modelo para outros modelos.
URL pública de áudio para referência de áudio ou operação orientada a áudio, em modelos que listam este campo. É uma entrada, não um seletor de saída de áudio.
Áudio de referência para modelos que listam este campo. O seedance-2.5 aceita até 10 entradas de áudio no total combinando audio_url e audio_urls e permite uma requisição com referências de áudio sem prompt. Para o seedance-2.5, o áudio de referência mais o vídeo de referência duram, no máximo, 30 segundos combinados.
ID de uma tarefa anterior em seu workspace, para video-extension em modelos que listam este campo. Uma tarefa que não pertence ao seu workspace retorna 403 task_not_owned.
Segundo do vídeo de origem onde uma video-extension começa. Obrigatório para grok-imagine-video.
Segundos a adicionar em uma video-extension, em modelos que listam este campo. O grok-imagine-video aceita 6 ou 10.
Duração de saída em segundos. Os valores permitidos dependem do modelo e da operação; outros valores retornam 400 invalid_duration. Os modelos Seedance também aceitam -1 para permitir que o modelo escolha dentro do seu intervalo; o faturamento é então estimado de forma conservadora até a conclusão da tarefa. Algumas operações não aceitam duração, como motion-control e video-to-video do grok-imagine-video.
Alias de compatibilidade para duration. Se ambos forem enviados, eles devem ser idênticos.
Proporção de tela, por exemplo 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 ou adaptive (Seedance). Os valores permitidos dependem do modelo e da operação; outros valores retornam 400 invalid_aspect_ratio.
Resolução de saída, por exemplo 480p, 720p, 1080p ou 4k. Os valores permitidos dependem do modelo e da operação, e alguns modelos também utilizam 360p, 540p ou 768p. Outros valores retornam 400 invalid_resolution.
Seletor de saída de áudio para operações que o listam. A omissão segue o padrão do modelo; false solicita saída silenciosa somente onde o modelo permite. Consulte as observações de áudio acima e os detalhes do modelo selecionado.
Formato de contêiner, mp4 ou mov, para modelos que listam este campo, como seedance-2.5. Omita para modelos que não o listam.
Também retorna o último quadro gerado como last_frame_url. Apenas modelos Seedance.
Alternador de marca d'água para modelos que listam este campo (modelos Seedance).
O que evitar no vídeo gerado, até 5.000 caracteres, para modelos que listam este campo.
Seed para geração reproduzível, para modelos que listam este campo. Modelos Seedance 2.0 aceitam -1 para uma seed aleatória; seedance-2.5 não aceita este campo.
Quadros por segundo (1-120), para modelos que listam este campo.
Contagem de quadros, para modelos que listam este campo. Modelos Seedance não o aceitam.
Segundos que a tarefa pode aguardar na fila antes de expirar (3600 a 259200), para modelos Seedance.
Prioridade da tarefa de 0 a 9, para modelos Seedance. Não combine com service_tier=flex.
default é aceito como uma operação sem efeito (no-op) de compatibilidade nos modelos Seedance 2.0 e 2.5. flex é rejeitado nesses modelos.
Identificador de segurança do usuário final (até 128 caracteres), para modelos Seedance. Se omitido, o TokenLab usa user quando fornecido.
Ferramentas que o modelo pode usar durante a geração, para os modelos Seedance 2.0 e 2.5. A ferramenta suportada é {"type": "web_search"}.
Um identificador exclusivo para o usuário final. Para modelos Seedance, o TokenLab também o utiliza como safety_identifier quando esse campo é omitido.
Nomes de Campos Compatíveis
- Os campos principais utilizam snake_case:
aspect_ratio,output_audioereference_images. - Para compatibilidade, o TokenLab também aceita
ratio,generate_audio,outputAudio,secondsereferenceImages. - Se um campo principal e seu alias forem enviados juntos, seus valores devem coincidir. Uma divergência retorna
400comconflicting_audio_selector,conflicting_durationouconflicting_aspect_ratio.
Parâmetros do Seedance
Os modelos Seedance (seedance-2.0, seedance-2.0-fast, seedance-2.0-mini e seedance-2.5) aceitam os nomes de campo do TokenLab acima e os aliases seconds, ratio e generate_audio. As versões diferem:
| Modelos Seedance 2.0 | seedance-2.5 | |
|---|---|---|
| Resolução | seedance-2.0: 480p, 720p, 1080p, 4k. seedance-2.0-fast e seedance-2.0-mini: 480p, 720p | 480p, 720p |
| Duração | -1, 4 a 15 segundos | -1, 4 a 30 segundos |
| Proporção de tela | 1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptive | O mesmo para text-to-video e reference-to-video. Image-to-video, start-end, edição de vídeo e extensão requerem adaptive; edição de vídeo também requer duration=-1 |
| Formato de saída | mp4 | mp4 ou mov |
seed | Aceito | Não aceito |
| Entradas de referência | 9 referências de imagem incluindo materiais (materiais são aceitos apenas nestes modelos) | 30 imagens, 10 vídeos e 10 arquivos de áudio no total |
Os detalhes do modelo são a fonte atual para esses valores. Envie duration, resolution, aspect_ratio e output_audio explicitamente em vez de depender de um padrão; o recommended_request do modelo mostra uma requisição típica.
duration=-1 ou seconds=-1 permite que o Seedance escolha a duração de saída dentro do intervalo do modelo. O TokenLab estima o custo de forma conservadora antes do término da tarefa e, em seguida, faz a liquidação a partir do uso da tarefa concluída quando disponível. service_tier=flex e frames são rejeitados nesses modelos.
Exemplo do Seedance
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"prompt": "A sleek product reveal with cinematic camera movement",
"operation": "text-to-video",
"duration": -1,
"aspect_ratio": "adaptive",
"resolution": "720p",
"output_audio": true
}'Resposta
Campos que descrevem resultados, erros, carimbos de data/hora (timestamps) e o modelo são retornados quando disponíveis para a tarefa.
ID da tarefa. Idêntico a task_id.
ID da tarefa para consultar (polling) com GET /v1/tasks/{id}.
URL de status para esta tarefa, /v1/tasks/{id}. Chame-a com sua chave de API.
Status da tarefa: pending, processing, completed, failed. Uma nova tarefa normalmente é pending.
Timestamp Unix de quando a tarefa foi criada.
Modelo utilizado.
ID da transação de faturamento quando a liquidação já foi concluída. É separado do ID da tarefa.
URL do vídeo, presente apenas quando a resposta de criação já traz o resultado. Normalmente, você a lê na resposta de status.
Mensagem de erro ou objeto de erro estruturado quando a tarefa falha.
Erros
| Status e código | Significado |
|---|---|
400 invalid_request | Um campo está malformado, fora do intervalo ou ausente. error.param indica qual é. Uma mensagem como "Set aspect_ratio explicitly" significa que o campo omitido não tem valor padrão para esta requisição. |
400 unsupported_operation, unsupported_parameter, invalid_resolution, invalid_duration, invalid_aspect_ratio, invalid_parameter_value, too_many_items, prompt_too_long | A requisição não corresponde ao que o modelo aceita para a operação. O erro geralmente lista os valores aceitos. |
400 invalid_parameter | Uma entrada não se adequa à operação, por exemplo, uma imagem enviada com text-to-video. |
400 conflicting_audio_selector, conflicting_duration, conflicting_aspect_ratio | Um alias e seu campo principal divergem. |
400 unpriceable_selection | A combinação selecionada não possui preço. Altere resolution, duration, aspect_ratio ou a configuração de áudio. |
400 too_many_seedance_reference_images, unsupported_seedance_material_asset_model | Muitas referências de imagem para um modelo Seedance 2.0 ou um material enviado para outro modelo. |
402 | Saldo insuficiente. |
403 task_not_owned | O task_id pertence a outro workspace. |
409 seedance_material_preparing, seedance_material_route_unavailable | Um material ainda não está ACTIVE, ou o modelo selecionado não pode usar os materiais fornecidos. |
429 | Limite de taxa excedido. Consulte Limites de taxa. |
Requisição
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"prompt": "A cat walking through a garden, cinematic lighting",
"operation": "text-to-video",
"duration": 4,
"resolution": "720p",
"aspect_ratio": "16:9"
}'Resposta
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"model": "veo3.1",
"created": 1706000000
}Imagem para Vídeo
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "hailuo-2.3",
"prompt": "The scene begins from the provided image and adds gentle natural motion.",
"operation": "image-to-video",
"image_url": "https://example.com/image.jpg",
"duration": 6,
"resolution": "768p"
}
)Referência para Vídeo
Use operation=reference-to-video quando o modelo suportar condicionamento por referência dedicado. As referências de imagem vão em reference_images; modelos que aceitam vídeos e áudios de referência usam video_urls e audio_urls. duration define apenas a duração da saída gerada. Ela não limita a duração da entrada de vídeo de referência. Consulte reference_images acima para os limites de contagem por modelo.
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "veo3.1",
"prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
"operation": "reference-to-video",
"reference_images": [
"https://example.com/ref-a.jpg",
"https://example.com/ref-b.jpg"
],
"duration": 8,
"resolution": "720p",
"aspect_ratio": "9:16"
}
)Controle de Keyframes
Use start_image e end_image para controlar o primeiro e o último quadros:
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "viduq2-pro",
"operation": "start-end-to-video",
"start_image": "https://example.com/day.jpg",
"end_image": "https://example.com/night.jpg",
"duration": 5,
"resolution": "720p"
}
)Vídeo para Vídeo
Use operation=video-to-video quando o modelo aceitar um vídeo existente como entrada principal. Para o grok-imagine-video, envie uma URL HTTPS pública de .mp4 em video_url e o prompt de edição, e omita resolution, duration e aspect_ratio.
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "grok-imagine-video",
"operation": "video-to-video",
"video_url": "https://example.com/source.mp4",
"prompt": "Enhance the clip while preserving the original motion."
}
)Extensão de Vídeo
Use operation=video-extension para continuar um resultado anterior. Envie o task_id de uma tarefa do seu workspace e um prompt; os outros campos dependem do modelo. O grok-imagine-video também requer extend_at e aceita extend_times de 6 ou 10. veo3.1 e veo3.1-fast aceitam task_id e prompt. Os modelos Seedance listam video_url, video_urls e task_id para esta operação.
Controle de Movimento
Use operation=motion-control quando o modelo esperar uma imagem do sujeito e um vídeo de referência de movimento. Envie image_url e video_url; resolution é obrigatório.
import requests
response = requests.post(
"https://api.tokenlab.sh/v1/videos/generations",
headers={"Authorization": "Bearer sk-your-api-key"},
json={
"model": "kling-3.0-motion-control",
"operation": "motion-control",
"prompt": "Keep the subject identity stable while following the motion reference.",
"image_url": "https://example.com/subject.png",
"video_url": "https://example.com/motion.mp4",
"resolution": "720p"
}
)Descoberta de Modelos
O catálogo público de vídeos e as operações suportadas mudam com o tempo. Use a API de Modelos para verificar o suporte atual antes de estruturar um fluxo específico para um modelo:
curl "https://api.tokenlab.sh/v1/models?recommended_for=video"
curl "https://api.tokenlab.sh/v1/models/veo3.1"Leia a resposta com os detalhes do modelo antes de depender de operações ou campos específicos de um modelo. Operações como video-extension e motion-control são específicas do modelo; confirme a disponibilidade atual lá em vez de confiar nos exemplos estáticos desta página.
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 opcional que torna uma requisição de criação segura para novas tentativas. Envie um novo valor único, como um UUID, para cada tarefa. Uma nova tentativa com a mesma chave e o mesmo corpo retorna o resultado da requisição de criação original, geralmente a tarefa original, e não cria, despacha ou cobra uma segunda tarefa. Um corpo diferente com uma chave que já foi aceita é rejeitado com 409. Uma chave com mais de 255 caracteres é ignorada e a requisição não terá proteção de idempotência. Veja Tente novamente com segurança usando uma chave de idempotência.
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
application/json