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

# Video Generation

> Generate videos with explicit public operations, async polling, and model-specific media inputs.

Video generation is asynchronous. `POST /v1/videos/generations` returns a public task identity and usually a `poll_url`; the final video appears on later status responses.

When the selected Seedance model can use the TokenLab material library, image URLs and supported inline data URLs are prepared as reusable TokenLab materials before generation. If preparation takes longer than 60 seconds, retry after the returned `auto_material_asset_ids` become `ACTIVE`. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.

## OpenAI-Style And Volc-Compatible Video APIs

Use `/v1/videos/generations` for TokenLab's unified video API across models. If you are migrating an existing Seedance 2.0 integration that already uses Volc-style `content[]` or Action requests, use the Seedance compatibility endpoints under `/api/v3`. Both styles use TokenLab Bearer API keys and async polling, but their request and response shapes are different.

## Supported Operations

Use explicit `operation` in production. TokenLab can infer some operations from inputs, but explicit operation values make validation, support, and retries clearer.

| Operation            | Required or typical input                                                       | Use case                                  |
| -------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- |
| `text-to-video`      | `prompt`                                                                        | Generate from text only                   |
| `image-to-video`     | `image_url` or compatible `image`                                               | Animate a starting image                  |
| `reference-to-video` | `reference_images` and optional `video_urls` / `audio_urls` on supported models | Keep identity, style, or asset references |
| `start-end-to-video` | `start_image`, `end_image`                                                      | Control first and last frames             |
| `video-to-video`     | `video_url` or model-specific `task_id`                                         | Transform or upscale an existing clip     |
| `motion-control`     | `image_url` plus `video_url`                                                    | Apply motion reference to a subject       |
| `audio-to-video`     | `audio_url`                                                                     | Audio-conditioned video flows             |
| `video-extension`    | `task_id`, `extend_at`, or model-specific extension fields                      | Continue a generated video                |

## Model Discovery

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

Use the model IDs shown by TokenLab in `model`, then choose feature variants with `operation` and the corresponding media inputs. Examples include `wan-2.7`, `happyhorse-1.0`, `viduq3`, `viduq3-mix`, `pixverse-v6`, `kling-3.0-video`, `veo3.1`, and `seedance-2.0`; do not use operation-specific suffixes as TokenLab model names.

Read the selected model detail before relying on specialized fields such as `reference_images`, `kling_elements`, `output_audio`, `duration`, `resolution`, or `aspect_ratio`.

## Create Request

```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": "A calm cinematic shot of a cat walking through a sunlit garden",
    "duration": 4,
    "aspect_ratio": "16:9"
  }'
```

For production media input, prefer public `https` URLs over inline `data:` URLs. If you use temporary URLs, keep them valid until TokenLab finishes creating the task.

## Inputs And Model-Specific Fields

* Veo 3 family requests default to audio-on when `output_audio` is omitted. Set it explicitly when the model supports the toggle and your UX depends on sound.
* `kling_elements` is for `kling-3.0-video` image-conditioned requests. Reference each element in `prompt` as `@name`; do not combine it with `output_audio=true`.
* For the Seedance 2.0 family, read the [Seedance 2.0 video models guide](/guides/seedance-2-video) before using 4K output, Fast/Mini resolution caps, or multimodal reference inputs.
* For `grok-imagine-video`, video-to-video uses a public `.mp4` `video_url`; model-specific limits such as `duration` and `resolution` must come from the model details.

## PixVerse and HappyHorse

| Model                        | Operations                                                                    | Inputs                                                                      | Resolution              | Duration                                                                                 | Audio selector                  |
| ---------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------- | ------------------------------- |
| `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 | Any integer from 1 to 15 seconds                                                         | `output_audio`, default `false` |
| `pixverse-v5.6`              | `text-to-video`, `image-to-video`, `start-end-to-video`, `reference-to-video` | Same fields as C1 and V6                                                    | 360p, 540p, 720p, 1080p | 5, 8, or 10 seconds; 1080p supports 5 or 8 seconds                                       | `output_audio`, default `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 to 15 seconds for generation operations; video-to-video output is capped at 15 seconds | Do not send `output_audio`      |

On TokenLab, the PixVerse models above do not accept `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
  }'
```

## Polling Results

Use the returned `poll_url` first. If you need a fixed endpoint, use `GET /v1/tasks/{id}` with the same `id` / `task_id` from the create response.

Completed video tasks may return `video_url`, `video`, or `videos` depending on the model and output count. Treat `billing_transaction_id` as a billing identifier, not as a task identifier.

## Common Pitfalls

* Do not hard-code old video status paths; prefer `poll_url`.
* Do not combine first-frame fields with dedicated reference-image flows unless the model details allows it.
* Do not assume `duration` describes input reference video length; it usually controls generated output length.
* Do not retry create requests after a timeout without checking whether a task was already created.

## API Reference

| Topic             | Reference                                                 |
| ----------------- | --------------------------------------------------------- |
| Create Video      | [Create Video](/api-reference/video/create-video)         |
| Get Video Status  | [Get Video Status](/api-reference/video/get-video-status) |
| Get Task Status   | [Get Task Status](/api-reference/tasks/get-task-status)   |
| Cancel Task       | [Cancel Task](/api-reference/tasks/cancel-task)           |
| Billing & Pricing | [Billing & Pricing](/guides/billing)                      |