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

# Geração de Vídeo

> Gere vídeos com operações públicas explícitas, polling assíncrono e entradas de mídia específicas do modelo.

A geração de vídeo é assíncrona. `POST /v1/videos/generations` retorna uma identidade de tarefa pública e geralmente um `poll_url`; o vídeo final aparece em respostas de status posteriores.

Quando o modelo Seedance selecionado pode usar a biblioteca de materiais do TokenLab, URLs de imagem e data URLs inline compatíveis são preparadas como materiais reutilizáveis do TokenLab antes da geração. Se a preparação levar mais de 60 segundos, tente novamente quando os `auto_material_asset_ids` retornados estiverem `ACTIVE`. Se o modelo selecionado não puder usar a biblioteca de materiais, entradas comuns de imagem continuam pelo caminho normal de imagem.

## Operações compatíveis

Use `operation` explícito em produção. O TokenLab pode inferir algumas operações a partir das entradas, mas valores de operação explícitos tornam a validação, suporte e tentativas mais claros.

| 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 `video_urls` / `audio_urls` opcionais em modelos suportados | Manter identidade, estilo ou referências de ativos |
| `start-end-to-video` | `start_image`, `end_image`                                                       | Controlar os primeiros e últimos quadros           |
| `video-to-video`     | `video_url` ou `task_id` específico do modelo                                    | Transformar ou aumentar um clipe existente         |
| `motion-control`     | `image_url` mais `video_url`                                                     | Aplicar referência de movimento a um sujeito       |
| `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                          |

## Descoberta de Modelos

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \\
  -H "Authorization: Bearer sk-your-api-key"
```

Use os IDs de modelo mostrados pelo TokenLab em `model` e escolha variantes de recurso com `operation` e as entradas de mídia correspondentes. Exemplos: `wan-2.7`, `happyhorse-1.0`, `viduq3`, `viduq3-mix`, `pixverse-v6`, `kling-3.0-video`, `veo3.1` e `seedance-2.0`; não use sufixos específicos de operação como nomes de modelo do TokenLab.

Leia os detalhes do modelo selecionado antes de confiar em campos especializados, como `reference_images`, `kling_elements`, `output_audio`, `duration`, `resolution` ou `aspect_ratio`.

## Criar Solicitação

```bash theme={null}
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": "Uma cena cinematográfica calma de um gato andando por um jardim ensolarado",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'
```

Para entrada de mídia em produção, prefira URLs públicas `https` em vez de URLs `data:` inline. Se você usar URLs temporárias, mantenha-as válidas até o TokenLab terminar de criar a tarefa.

## Entradas E Campos Específicos do Modelo

* Solicitações da família Veo 3 padrão para áudio ativado quando `output_audio` é omitido. Defina-o explicitamente quando o modelo suportar a alternância e sua experiência do usuário depender de som.
* `kling_elements` é para solicitações condicionadas por imagem de `kling-3.0-video`. Referencie cada elemento em `prompt` como `@name`; não combine com `output_audio=true`.
* Para a família Seedance 2.0, leia o [guia de modelos de vídeo Seedance 2.0](/pt/guides/seedance-2-video) antes de usar saída 4K, limites Fast/Mini ou entradas de referência multimodais.
* Para `grok-imagine-video`, vídeo-para-vídeo usa um `video_url` público `.mp4`; limites específicos do modelo, como `duration` e `resolution`, devem vir do detalhe do modelo.

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

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

## Resultados de Polling

Use o `poll_url` retornado primeiro. Se precisar de um endpoint fixo, use `GET /v1/tasks/{id}` com o mesmo `id` / `task_id` da resposta de criação.

Tarefas de vídeo concluídas podem retornar `video_url`, `video` ou `videos`, dependendo do modelo e da contagem de saída. Trate `billing_transaction_id` como um identificador de cobrança, não como um identificador de tarefa.

## Armadilhas Comuns

* Não codifique caminhos de status de vídeo antigos; prefira `poll_url`.
* Não combine campos de primeiro quadro com fluxos dedicados de imagem de referência, a menos que o detalhe do modelo permita.
* Não assuma que `duration` descreve o comprimento do vídeo de referência de entrada; geralmente controla o comprimento da saída gerada.
* Não tente recriar solicitações após um timeout sem verificar se uma tarefa já foi criada.

## Referência da API

| Tópico                 | Referência                                                        |
| ---------------------- | ----------------------------------------------------------------- |
| Criar Vídeo            | [Criar Vídeo](/pt/api-reference/video/create-video)               |
| Obter Status do Vídeo  | [Obter Status do Vídeo](/pt/api-reference/video/get-video-status) |
| Obter Status da Tarefa | [Obter Status da Tarefa](/pt/api-reference/tasks/get-task-status) |
| Cancelar Tarefa        | [Cancelar Tarefa](/pt/api-reference/tasks/cancel-task)            |
| Cobrança & Preços      | [Cobrança & Preços](/pt/guides/billing)                           |

## APIs de vídeo estilo OpenAI e compatíveis com Volc

Use `/v1/videos/generations` para a API unificada de vídeo da TokenLab entre modelos. Se você estiver migrando uma integração Seedance 2.0 que já usa `content[]` ou solicitações Action no estilo Volc, use os endpoints de compatibilidade Seedance em `/api/v3`. Ambos os estilos usam TokenLab Bearer API keys e polling assíncrono, mas seus formatos de solicitação e resposta são diferentes.