Guias de mídia
Geração de Vídeo
Crie vídeos a partir de texto, imagens, áudio ou clipes existentes
A geração de vídeo é assíncrona. O POST /v1/videos/generations retorna um ID de tarefa e, geralmente, uma poll_url. Consulte GET /v1/tasks/{id} com esse ID até que o vídeo finalizado esteja pronto.
Envie URLs HTTP(S) públicas ou URLs de dados suportadas nos campos de imagem aceitos pelo modelo selecionado. Essas entradas seguem o caminho de mídia normal e não criam automaticamente IDs de material reutilizáveis.
Quando um material explícito ainda está sendo preparado, o POST /v1/videos/generations retorna 409 seedance_material_preparing com inactive_asset_ids. Consulte esses ativos até que estejam ACTIVE, então tente novamente com os mesmos IDs de material. Se um ativo estiver FAILED, inspecione a error_message e corrija ou reimporte-o antes de tentar novamente.
Escolha uma API
Use /v1/videos/generations para uma nova integração de vídeo. Clientes existentes do Seedance 2.0 que já enviam content[] do Volcengine ou solicitações de Ação podem manter esse formato através da /api/v3. Ambas as APIs usam uma chave Bearer do TokenLab, mas seus campos e valores de status são diferentes.
Escolha o que criar
Defina a operation explicitamente para que a API possa validar os campos corretos para a tarefa.
| Operação | Entrada necessária ou típica | Caso de uso |
|---|---|---|
text-to-video | prompt | Gerar apenas a partir de texto |
image-to-video | image_url ou image compatível | Animar uma imagem inicial |
reference-to-video | reference_images e, opcionalmente, video_urls / audio_urls em modelos suportados | Manter identidade, estilo ou referências de ativos |
start-end-to-video | start_image, end_image | Controlar o primeiro e o último quadro |
video-to-video | video_url ou task_id específico do modelo | Transformar ou fazer upscale de um clipe existente |
motion-control | image_url mais video_url | Aplicar referência de movimento a um objeto |
audio-to-video | audio_url | Fluxos de vídeo condicionados por áudio |
video-extension | task_id, extend_at ou campos de extensão específicos do modelo | Continuar um vídeo gerado |
Escolha um modelo
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
-H "Authorization: Bearer sk-your-api-key"Use um ID de modelo retornado pelo TokenLab, então escolha o tipo de geração com operation e as entradas de mídia correspondentes. Não use um nome de operação como ID de modelo.
Leia os detalhes do modelo selecionado antes de depender de campos especializados como reference_images, kling_elements, output_audio, duration, resolution ou aspect_ratio.
Criar um vídeo
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "veo3.1",
"operation": "text-to-video",
"prompt": "A calm cinematic shot of a cat walking through a sunlit garden",
"resolution": "720p",
"duration": 4,
"aspect_ratio": "16:9"
}'Use URLs https para mídias que podem ser buscadas na internet. URLs temporárias devem permanecer válidas até que o TokenLab crie a tarefa.
Campos específicos do modelo
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.
- Para a família Seedance 2.0, leia o guia de modelos de vídeo Seedance 2.0 antes de usar saída 4K, limites de resolução Fast/Mini ou entradas de referência multimodal.
- Para
grok-imagine-videovideo-to-video, envieprompte umavideo_urlHTTPS pública em.mp4. Uma URL de resultado.mp4do TokenLab de uma tarefa anterior funciona. Esta operação não usa seletores deduration,resolutionouaspect_ratio.
PixVerse e HappyHorse
| Modelo | Operações | Entradas | Resolução | Duração | Seletor de áudio |
|---|---|---|---|---|---|
pixverse-c1, pixverse-v6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | prompt; image_url; start_image + end_image; reference_images | 360p, 540p, 720p, 1080p | Qualquer número inteiro de 1 a 15 segundos | output_audio, padrão false |
pixverse-v5.6 | text-to-video, image-to-video, start-end-to-video, reference-to-video | Mesmos campos que C1 e V6 | 360p, 540p, 720p, 1080p | 5, 8 ou 10 segundos; 1080p suporta 5 ou 8 segundos | output_audio, padrão false |
happyhorse-1.0 | text-to-video, image-to-video, reference-to-video, video-to-video | prompt; image_url; reference_images; video_url + reference_images | 720p, 1080p | 3 a 15 segundos para operações de geração; a saída de video-to-video é limitada a 15 segundos | Não envie output_audio |
No TokenLab, os modelos PixVerse acima não aceitam operation=video-extension.
curl https://api.tokenlab.sh/v1/videos/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "pixverse-v6",
"operation": "image-to-video",
"prompt": "A slow camera move through a neon-lit street",
"image_url": "https://example.com/start.jpg",
"resolution": "1080p",
"duration": 5,
"output_audio": true
}'Obter o vídeo finalizado
Chame GET /v1/tasks/{id} com o id ou task_id da resposta de criação até que a tarefa esteja completed ou failed.
Tarefas de vídeo concluídas podem retornar video_url, video ou videos dependendo do modelo e da contagem de saídas. Trate billing_transaction_id como um identificador de faturamento, não como um identificador de tarefa.
As URLs de resultado de vídeo são URLs de resultado de mídia do TokenLab que terminam com o tipo de arquivo, como .mp4, e permanecem válidas por 30 dias. media_retention.items relata o status de salvamento de cada item e expires_at; a resposta pode omitir media_retention quando o status de salvamento não é conhecido a tempo, e a URL ainda funciona. Tarefas falhas e em progresso retornam campos de URL de vídeo vazios. Snapshots de tarefas assíncronas têm um ciclo de vida separado. Veja Retenção de dados.
Armadilhas comuns
- Não use caminhos de status por modalidade, como
/v1/videos/generations/{id}, em códigos novos; consulteGET /v1/tasks/{id}. - Não combine campos de primeiro quadro com fluxos de imagem de referência dedicados, a menos que os detalhes do modelo permitam.
- Não presuma que
durationdescreve a duração do vídeo de referência de entrada; geralmente, ele controla a duração da saída gerada. - Envie uma
Idempotency-KeycomPOST /v1/videos/generations. Após um tempo limite, envie a mesma solicitação com a mesma chave para obter a tarefa original. Sem uma chave, verifique se uma tarefa já foi criada antes de tentar novamente.
Referência da API
| Tópico | Referência |
|---|---|
| Criar Vídeo | Criar Vídeo |
| Obter Status do Vídeo | Obter Status do Vídeo |
| Obter Status da Tarefa | Obter Status da Tarefa |
| Cancelar Tarefa | Cancelar Tarefa |
| Faturamento e Preços | Faturamento e Preços |
O Hailuo H3-Max gera vídeos de 5 a 15 segundos em 480p ou 768p a partir de texto, um primeiro quadro ou primeiro e último quadros. Seu fluxo de trabalho focado em velocidade é útil para transformar rapidamente uma ideia de cena em um clipe curto.
{
"model": "hailuo-h3-max",
"operation": "text-to-video",
"prompt": "A slow camera move through a quiet garden",
"resolution": "768p",
"duration": 5,
"aspect_ratio": "16:9"
}