> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar vídeo

> Cria uma tarefa de geração de 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

<ParamField body="model" type="string" default="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](/pt/guides/video-generation) e a [Models API](/pt/api-reference/models/list-models).
</ParamField>

<Note>
  **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`
</Note>

<ParamField body="prompt" type="string" required>
  Descrição em texto do vídeo a ser gerado. Este campo é obrigatório para a maioria dos modelos públicos de vídeo.
</ParamField>

<ParamField body="operation" type="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.
</ParamField>

<ParamField body="image_url" type="string">
  URL pública da imagem inicial para fluxos image-to-video. Para a compatibilidade mais ampla entre modelos, prefira `image_url`.
</ParamField>

<ParamField body="image" type="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.
</ParamField>

<ParamField body="reference_images" type="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](/pt/guides/seedance-2-video). 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.
</ParamField>

<ParamField body="material_asset_id" type="string">
  ID de material Seedance do TokenLab retornado por [Criar material](/pt/api-reference/video/create-material-asset) 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.
</ParamField>

<ParamField body="material_asset_ids" type="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.
</ParamField>

<Info>
  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.
</Info>

<ParamField body="reference_image_type" type="string">
  Campo opcional para modelos que distinguem entre referências `asset` e `style`.
</ParamField>

<ParamField body="kling_elements" type="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.
</ParamField>

<ParamField body="video_url" type="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.
</ParamField>

<ParamField body="video_urls" type="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.
</ParamField>

<ParamField body="audio_url" type="string">
  URL pública de áudio para modelos que suportam `audio-to-video`.
</ParamField>

<ParamField body="audio_urls" type="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.
</ParamField>

<ParamField body="task_id" type="string">
  Identificador de tarefa usado por alguns fluxos de continuação, extensão ou derivados.
</ParamField>

<ParamField body="extend_at" type="integer">
  Deslocamento inicial específico do modelo para alguns fluxos `video-extension`.
</ParamField>

<ParamField body="extend_times" type="string">
  Multiplicador ou quantidade de repetições específica do modelo para alguns fluxos `video-extension`.
</ParamField>

<ParamField body="duration" type="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.
</ParamField>

<ParamField body="seconds" type="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`.
</ParamField>

<ParamField body="aspect_ratio" type="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.
</ParamField>

<ParamField body="resolution" type="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`.
</ParamField>

<ParamField body="output_audio" type="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`.
</ParamField>

<ParamField body="draft" type="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`.
</ParamField>

<ParamField body="draft_task_id" type="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.
</ParamField>

<ParamField body="ratio" type="string">
  Alias compatível de `aspect_ratio`. Se `ratio` e `aspect_ratio` forem enviados juntos, devem ser idênticos.
</ParamField>

<ParamField body="generate_audio" type="boolean">
  Alias compatível de `output_audio`. Se `generate_audio`, `output_audio` e `outputAudio` aparecerem juntos, todos os valores devem corresponder.
</ParamField>

<ParamField body="execution_expires_after" type="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.
</ParamField>

<ParamField body="priority" type="integer">
  Prioridade opcional da tarefa de `0` a `9` para modelos de vídeo compatíveis. Não combine `priority` com `service_tier=flex`.
</ParamField>

<ParamField body="safety_identifier" type="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.
</ParamField>

<ParamField body="service_tier" type="string">
  `default` é aceito como no-op compatível para modelos Seedance 2.0. `flex` só é permitido quando o modelo selecionado oferece suporte.
</ParamField>

<ParamField body="frames" type="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.
</ParamField>

<ParamField body="camera_fixed" type="boolean">
  Seletor opcional de câmera fixa para modelos de vídeo compatíveis. Modelos Seedance 2.0 não aceitam este campo.
</ParamField>

<ParamField body="fps" type="integer">
  Quadros por segundo (1-120). Só tem efeito em modelos que expõem controle de FPS.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Elementos que devem ser evitados no vídeo gerado.
</ParamField>

<ParamField body="seed" type="integer">
  Seed aleatória para geração reproduzível. Seedance usa `-1` como seed aleatória quando omitida.
</ParamField>

<ParamField body="cfg_scale" type="number">
  Intensidade de aderência ao prompt (0-20) nos modelos que expõem esse controle.
</ParamField>

<ParamField body="motion_strength" type="number">
  Intensidade de movimento (0-1) nos modelos que expõem esse controle.
</ParamField>

<ParamField body="start_image" type="string">
  URL da imagem do primeiro quadro, ou entrada compatível, para `start-end-to-video`.
</ParamField>

<ParamField body="end_image" type="string">
  URL da imagem do último quadro, ou entrada compatível, para `start-end-to-video`.
</ParamField>

<ParamField body="size" type="string">
  Nível de tamanho específico do modelo para modelos de vídeo compatíveis.
</ParamField>

<ParamField body="watermark" type="boolean">
  Alternância opcional de marca d’água para modelos que a expõem. Seedance usa `false` por padrão quando omitido.
</ParamField>

<ParamField body="effect_type" type="string">
  Seletor de efeito específico do modelo para alguns fluxos especializados de edição ou efeitos.
</ParamField>

<ParamField body="user" type="string">
  Identificador único do usuário final. Para Seedance, TokenLab também usa esse valor como `safety_identifier` quando esse campo é omitido.
</ParamField>

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

```bash cURL theme={null}
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

<ResponseField name="id" type="string">
  Identificador canônico da tarefa assíncrona. Quando `id` e `task_id` estiverem presentes juntos, trate-os como a mesma tarefa.
</ResponseField>

<ResponseField name="task_id" type="string">
  Identificador único da tarefa para polling.
</ResponseField>

<ResponseField name="poll_url" type="string">
  URL de polling recomendada para esta tarefa. Use exatamente esse caminho ao consultar o status.
</ResponseField>

<ResponseField name="billing_transaction_id" type="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.
</ResponseField>

<ResponseField name="status" type="string">
  Status inicial: `pending`.
</ResponseField>

<ResponseField name="created" type="integer">
  Timestamp Unix de criação da tarefa.
</ResponseField>

<ResponseField name="model" type="string">
  Modelo utilizado.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "pending",
    "model": "veo3.1",
    "created": 1706000000
  }
  ```
</ResponseExample>

## Imagem para vídeo

```python theme={null}
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"
    }
)
```

## Kling 3.0 Elements

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.

```python theme={null}
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](/pt/guides/seedance-2-video). `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.

```python theme={null}
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.

```python theme={null}
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`.

```python theme={null}
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.

```python theme={null}
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](/pt/api-reference/models/list-models) como referência atual antes de integrar um fluxo específico de modelo:

```bash theme={null}
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.