Criar vídeo

Visão geral

A geração de vídeo é assíncrona. Você envia uma solicitação, recebe uma task_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 o poll_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 quando output_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

string

padrão:"veo3.1"

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ão false

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

string

obrigatório

Descrição em texto do vídeo a ser gerado. Este campo é obrigatório para a maioria dos modelos públicos de vídeo.

string

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.

string

URL pública da imagem inicial para fluxos image-to-video. Para a compatibilidade mais ampla entre modelos, prefira image_url.

string

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.

array

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.

string

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.

array

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.

string

Campo opcional para modelos que distinguem entre referências asset e style.

array

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.

string

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.

array

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.

string

URL pública de áudio para modelos que suportam audio-to-video.

array

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.

string

Identificador de tarefa usado por alguns fluxos de continuação, extensão ou derivados.

integer

Deslocamento inicial específico do modelo para alguns fluxos video-extension.

string

Multiplicador ou quantidade de repetições específica do modelo para alguns fluxos video-extension.

integer

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.

integer

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.

string

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.

string

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.

boolean

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.

boolean

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.

string

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.

string

Alias compatível de aspect_ratio. Se ratio e aspect_ratio forem enviados juntos, devem ser idênticos.

boolean

Alias compatível de output_audio. Se generate_audio, output_audio e outputAudio aparecerem juntos, todos os valores devem corresponder.

integer

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.

integer

Prioridade opcional da tarefa de 0 a 9 para modelos de vídeo compatíveis. Não combine priority com service_tier=flex.

string

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.

string

default é aceito como no-op compatível para modelos Seedance 2.0. flex só é permitido quando o modelo selecionado oferece suporte.

integer

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.

boolean

Seletor opcional de câmera fixa para modelos de vídeo compatíveis. Modelos Seedance 2.0 não aceitam este campo.

integer

Quadros por segundo (1-120). Só tem efeito em modelos que expõem controle de FPS.

string

Elementos que devem ser evitados no vídeo gerado.

integer

Seed aleatória para geração reproduzível. Seedance usa -1 como seed aleatória quando omitida.

number

Intensidade de aderência ao prompt (0-20) nos modelos que expõem esse controle.

number

Intensidade de movimento (0-1) nos modelos que expõem esse controle.

string

URL da imagem do primeiro quadro, ou entrada compatível, para start-end-to-video.

string

URL da imagem do último quadro, ou entrada compatível, para start-end-to-video.

string

Nível de tamanho específico do modelo para modelos de vídeo compatíveis.

boolean

Alternância opcional de marca d’água para modelos que a expõem. Seedance usa false por padrão quando omitido.

string

Seletor de efeito específico do modelo para alguns fluxos especializados de edição ou efeitos.

string

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_type e output_audio.
Os campos públicos canônicos continuam em snake_case: aspect_ratio, output_audio, reference_images e reference_image_type.
Por compatibilidade, TokenLab também aceita ratio, generate_audio, outputAudio, seconds, referenceImages e referenceImageType.
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_url e audio_url, prefira URLs https pú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íveis seconds, 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

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.0",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

Resposta

string

Identificador canônico da tarefa assíncrona. Quando id e task_id estiverem presentes juntos, trate-os como a mesma tarefa.

string

Identificador único da tarefa para polling.

string

URL de polling recomendada para esta tarefa. Use exatamente esse caminho ao consultar o status.

string

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.

string

Status inicial: pending.

integer

Timestamp Unix de criação da tarefa.

string

Modelo utilizado.

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,
    "aspect_ratio": "16:9"
  }'

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000
}

Imagem para vídeo

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3-standard",
        "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,
        "aspect_ratio": "16:9"
    }
)

Elementos do Kling 3.0

Use kling_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.

response = requests.post("https://api.tokenlab.sh/v1/videos/generations",
    headers=headers,
    json={
        "model": "kling-3.0-video",
        "prompt": "Place @hero_bag on a studio turntable with soft product lighting.",
        "operation": "image-to-video",
        "image_url": "https://example.com/studio-start.png",
        "duration": 5,
        "resolution": "720p",
        "kling_elements": [
            {
                "name": "hero_bag",
                "description": "black leather handbag",
                "element_input_urls": [
                    "https://example.com/bag-front.png",
                    "https://example.com/bag-side.png"
                ]
            }
        ]
    }
)

Referência para vídeo

Use operation=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.

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"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

Controle de quadro inicial e final

Use start_image e end_image para controlar o primeiro e o último quadro.

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "prompt": "Smooth transition from day to night",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    }
)

Vídeo para vídeo

Para video-to-video com grok-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.

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.",
        "resolution": "720p"
    }
)

Controle de movimento

Quando um modelo precisa tanto de uma imagem do sujeito quanto de um vídeo de referência de movimento, use operation=motion-control. A TokenLab normaliza a forma pública image_url + video_url para o formato de solicitação esperado pelo modelo.

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 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 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:

curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models/veo3.1" \
  -H "Authorization: Bearer sk-your-api-key"

Leia 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.

Essencial

Texto

Arquivos e lotes

Imagens

Áudio e tempo real

Música

Vídeo e materiais

Worlds

3D

Tarefas assíncronas

Gemini nativo

Gerenciamento

Visão geral

Comportamento de polling

Comportamento de modelos e mídia

Corpo da requisição

Notas de compatibilidade

Boas práticas para entradas de mídia

Parâmetros Seedance

Exemplo Seedance

Resposta

Imagem para vídeo

Elementos do Kling 3.0

Referência para vídeo

Controle de quadro inicial e final

Vídeo para vídeo

Controle de movimento

Descoberta de modelos

​Visão geral

​Comportamento de polling

​Comportamento de modelos e mídia

​Corpo da requisição

​Notas de compatibilidade

​Boas práticas para entradas de mídia

​Parâmetros Seedance

​Exemplo Seedance

​Resposta

​Imagem para vídeo

​Elementos do Kling 3.0

​Referência para vídeo

​Controle de quadro inicial e final

​Vídeo para vídeo

​Controle de movimento

​Descoberta de modelos

Visão geral

Comportamento de polling

Comportamento de modelos e mídia

Corpo da requisição

Notas de compatibilidade

Boas práticas para entradas de mídia

Parâmetros Seedance

Exemplo Seedance

Resposta

Imagem para vídeo

Elementos do Kling 3.0

Referência para vídeo

Controle de quadro inicial e final

Vídeo para vídeo

Controle de movimento

Descoberta de modelos