Vídeo e materiais

Criar Vídeo

Iniciar uma tarefa de geração de vídeo

POST
/v1/videos/generations

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-Key para 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-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.

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

modelstringpadrão: veo3.1

ID 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ã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
promptstring

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.

operationstring

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.

image_urlstring

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.

imagestring

Imagem inline como data URL (por exemplo, data:image/jpeg;base64,...). Apenas alguns modelos aceitam; image_url funciona em mais modelos.

image_urlsarray

URLs de imagem para modelos que listam este campo. Consulte reference_images para os limites de contagem.

reference_imagesarray

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-fast e seedance-2.0-mini: até 9 referências de imagem no total, incluindo assets de material. Mais do que isso retorna 400 too_many_seedance_reference_images.
  • seedance-2.5: até 30 entradas de imagem no total combinando image_urls e reference_images.
  • grok-imagine-video: até 7, e a duration é limitada a 10 segundos. grok-imagine-video-1.5 e grok-imagine-video-1.5-preview nã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.

start_imagestring

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.

end_imagestring

Imagem do último quadro para start-end-to-video. Aceita as mesmas entradas que start_image.

material_asset_idstring

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.

material_asset_idsarray

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.

video_urlstring

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.

video_urlsarray

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.

audio_urlstring

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.

audio_urlsarray

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

task_idstring

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.

extend_atinteger

Segundo do vídeo de origem onde uma video-extension começa. Obrigatório para grok-imagine-video.

extend_timesstring

Segundos a adicionar em uma video-extension, em modelos que listam este campo. O grok-imagine-video aceita 6 ou 10.

durationinteger

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.

secondsinteger

Alias de compatibilidade para duration. Se ambos forem enviados, eles devem ser idênticos.

aspect_ratiostring

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.

resolutionstring

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.

output_audioboolean

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.

output_formatstring

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.

return_last_frameboolean

Também retorna o último quadro gerado como last_frame_url. Apenas modelos Seedance.

watermarkboolean

Alternador de marca d'água para modelos que listam este campo (modelos Seedance).

negative_promptstring

O que evitar no vídeo gerado, até 5.000 caracteres, para modelos que listam este campo.

seedinteger

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.

fpsinteger

Quadros por segundo (1-120), para modelos que listam este campo.

framesinteger

Contagem de quadros, para modelos que listam este campo. Modelos Seedance não o aceitam.

execution_expires_afterinteger

Segundos que a tarefa pode aguardar na fila antes de expirar (3600 a 259200), para modelos Seedance.

priorityinteger

Prioridade da tarefa de 0 a 9, para modelos Seedance. Não combine com service_tier=flex.

service_tierstring

default é aceito como uma operação sem efeito (no-op) de compatibilidade nos modelos Seedance 2.0 e 2.5. flex é rejeitado nesses modelos.

safety_identifierstring

Identificador de segurança do usuário final (até 128 caracteres), para modelos Seedance. Se omitido, o TokenLab usa user quando fornecido.

toolsarray

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"}.

userstring

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_audio e reference_images.
  • Para compatibilidade, o TokenLab também aceita ratio, generate_audio, outputAudio, seconds e referenceImages.
  • Se um campo principal e seu alias forem enviados juntos, seus valores devem coincidir. Uma divergência retorna 400 com conflicting_audio_selector, conflicting_duration ou conflicting_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.0seedance-2.5
Resoluçãoseedance-2.0: 480p, 720p, 1080p, 4k. seedance-2.0-fast e seedance-2.0-mini: 480p, 720p480p, 720p
Duração-1, 4 a 15 segundos-1, 4 a 30 segundos
Proporção de tela1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptiveO 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ídamp4mp4 ou mov
seedAceitoNão aceito
Entradas de referência9 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
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.

idstring

ID da tarefa. Idêntico a task_id.

task_idstring

ID da tarefa para consultar (polling) com GET /v1/tasks/{id}.

poll_urlstring

URL de status para esta tarefa, /v1/tasks/{id}. Chame-a com sua chave de API.

statusstring

Status da tarefa: pending, processing, completed, failed. Uma nova tarefa normalmente é pending.

createdinteger

Timestamp Unix de quando a tarefa foi criada.

modelstring

Modelo utilizado.

billing_transaction_idstring

ID da transação de faturamento quando a liquidação já foi concluída. É separado do ID da tarefa.

video_urlstring

URL do vídeo, presente apenas quando a resposta de criação já traz o resultado. Normalmente, você a lê na resposta de status.

errorstring | object

Mensagem de erro ou objeto de erro estruturado quando a tarefa falha.

Erros

Status e códigoSignificado
400 invalid_requestUm 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_longA requisição não corresponde ao que o modelo aceita para a operação. O erro geralmente lista os valores aceitos.
400 invalid_parameterUma entrada não se adequa à operação, por exemplo, uma imagem enviada com text-to-video.
400 conflicting_audio_selector, conflicting_duration, conflicting_aspect_ratioUm alias e seu campo principal divergem.
400 unpriceable_selectionA 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_modelMuitas referências de imagem para um modelo Seedance 2.0 ou um material enviado para outro modelo.
402Saldo insuficiente.
403 task_not_ownedO task_id pertence a outro workspace.
409 seedance_material_preparing, seedance_material_route_unavailableUm material ainda não está ACTIVE, ou o modelo selecionado não pode usar os materiais fornecidos.
429Limite 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

Response
{
  "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
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Cabeçalhos

X-TokenLab-Delivery-Policy?string

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"
Idempotency-Key?string

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.

Comprimento1 <= length <= 255

Corpo da requisição

application/json

Resposta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json