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çãoEntrada necessária ou típicaCaso de uso
text-to-videopromptGerar apenas a partir de texto
image-to-videoimage_url ou image compatívelAnimar uma imagem inicial
reference-to-videoreference_images e, opcionalmente, video_urls / audio_urls em modelos suportadosManter identidade, estilo ou referências de ativos
start-end-to-videostart_image, end_imageControlar o primeiro e o último quadro
video-to-videovideo_url ou task_id específico do modeloTransformar ou fazer upscale de um clipe existente
motion-controlimage_url mais video_urlAplicar referência de movimento a um objeto
audio-to-videoaudio_urlFluxos de vídeo condicionados por áudio
video-extensiontask_id, extend_at ou campos de extensão específicos do modeloContinuar 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-fast e veo3.1-lite sempre geram áudio. Omita output_audio ou envie true; false é rejeitado.
  • wan-2.6 e wan-2.7 sempre incluem áudio. Omita output_audio ou envie true. wan-3.0 e wan-3.0-prime também sempre incluem áudio e não aceitam nenhum seletor de áudio.
  • hailuo-h3 gera á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-pro e viduq3-turbo geram áudio por padrão; envie output_audio: false (ou audio: false) para uma saída sem som. Os modelos Seedance e PixVerse aceitam output_audio; envie-o explicitamente em vez de depender do padrão. Use-o apenas para operações que o listam.
  • audio_url / audio_urls fornecem á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-video video-to-video, envie prompt e uma video_url HTTPS pública em .mp4. Uma URL de resultado .mp4 do TokenLab de uma tarefa anterior funciona. Esta operação não usa seletores de duration, resolution ou aspect_ratio.

PixVerse e HappyHorse

ModeloOperaçõesEntradasResoluçãoDuraçãoSeletor de áudio
pixverse-c1, pixverse-v6text-to-video, image-to-video, start-end-to-video, reference-to-videoprompt; image_url; start_image + end_image; reference_images360p, 540p, 720p, 1080pQualquer número inteiro de 1 a 15 segundosoutput_audio, padrão false
pixverse-v5.6text-to-video, image-to-video, start-end-to-video, reference-to-videoMesmos campos que C1 e V6360p, 540p, 720p, 1080p5, 8 ou 10 segundos; 1080p suporta 5 ou 8 segundosoutput_audio, padrão false
happyhorse-1.0text-to-video, image-to-video, reference-to-video, video-to-videoprompt; image_url; reference_images; video_url + reference_images720p, 1080p3 a 15 segundos para operações de geração; a saída de video-to-video é limitada a 15 segundosNã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; consulte GET /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 duration descreve a duração do vídeo de referência de entrada; geralmente, ele controla a duração da saída gerada.
  • Envie uma Idempotency-Key com POST /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ópicoReferência
Criar VídeoCriar Vídeo
Obter Status do VídeoObter Status do Vídeo
Obter Status da TarefaObter Status da Tarefa
Cancelar TarefaCancelar Tarefa
Faturamento e PreçosFaturamento 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"
}

Nesta página