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

# Crear video

> Crea una tarea de generación de video

## Resumen

La generación de video es asíncrona. Envías una solicitud, recibes una `task_id` y un `poll_url`, y luego consultas periódicamente hasta obtener el resultado final.

### Comportamiento de sondeo

Para el comportamiento de polling más fiable, usa exactamente el `poll_url` que devuelve la respuesta de creación.

Si una respuesta de creación devuelve `poll_url`, llama exactamente a esa URL. Cuando apunte a `/v1/tasks/{id}`, trátala como el endpoint fijo canónico de estado.

### Comportamiento de modelos y medios

La salida de audio depende del modelo. En TokenLab, las solicitudes de Veo 3 y Seedance activan el audio por defecto cuando se omite `output_audio`. Cuando un modelo admite control de audio, usa `output_audio` para activarlo o desactivarlo explícitamente. Los alias `outputAudio` y `generate_audio` se aceptan por compatibilidad y deben coincidir con `output_audio` cuando se proporciona más de uno.

Para integraciones en producción, es mejor usar URLs `https` públicas para imágenes, videos y audio. Los modelos compatibles siguen aceptando URLs `data:`, pero los payloads base64 grandes son más difíciles de reintentar, inspeccionar y depurar.

## Cuerpo de la solicitud

<ParamField body="model" type="string" default="veo3.1">
  ID del modelo de video. Usa los IDs de modelo que muestra TokenLab como `veo3.1`, `wan-2.7`, `happyhorse-1.0`, `viduq3`, `pixverse-v6` o `kling-3.0-video`; elige text-to-video, image-to-video, reference-to-video u otras variantes con `operation`. Consulta la [guia de video](/es/guides/video-generation) y [Models API](/es/api-reference/models/list-models).
</ParamField>

<Note>
  **PixVerse**

  * Modelo: `pixverse-c1`, `pixverse-v6`, `pixverse-v5.6`
  * Operaciones: `text-to-video`, `image-to-video`, `start-end-to-video`, `reference-to-video`
  * Selector de audio: `output_audio`, `false` por defecto

  En TokenLab, los modelos PixVerse anteriores no aceptan `operation=video-extension`.

  **HappyHorse**

  * Modelo: `happyhorse-1.0`
  * Operaciones: `text-to-video`, `image-to-video`, `reference-to-video`, `video-to-video`
  * Selector de audio: No enviar `output_audio`
</Note>

<ParamField body="prompt" type="string" required>
  Descripción en texto del video que quieres generar. Este campo es obligatorio para la mayoría de los modelos públicos de video.
</ParamField>

<ParamField body="operation" type="string">
  Operación de video que se va a ejecutar. Los valores admitidos son `text-to-video`, `image-to-video`, `reference-to-video`, `start-end-to-video`, `video-to-video`, `video-extension`, `audio-to-video` y `motion-control`. TokenLab puede inferir la operación a partir de las entradas, pero en producción se recomienda enviarla de forma explícita.
</ParamField>

<ParamField body="image_url" type="string">
  URL pública de la imagen inicial para flujos image-to-video. Para la compatibilidad más amplia entre modelos, conviene preferir `image_url`.
</ParamField>

<ParamField body="image" type="string">
  Imagen inline como URL `data:` (por ejemplo, `data:image/jpeg;base64,...`). Los modelos compatibles la aceptan, pero `image_url` suele ser más robusta en producción.
</ParamField>

<ParamField body="reference_images" type="array">
  Imágenes de referencia para flujos con condicionamiento dedicado. La cantidad admitida depende del modelo. Para `seedance-2.0` y `seedance-2.0-fast`, TokenLab admite actualmente hasta 9 imágenes de referencia, además de hasta 3 videos de referencia y 3 audios de referencia. Para selección de modelo, límites 4K y notas de Mini, consulta la [guía de modelos de video Seedance 2.0](/es/guides/seedance-2-video). Se recomiendan URLs públicas `https`; los modelos compatibles también aceptan URLs `data:`. Para `grok-imagine-video`, reference-to-video acepta hasta 7 referencias de imagen y `duration` está limitada a 10 segundos. `grok-imagine-video-1.5-preview` solo admite image-to-video y no acepta referencias de imagen.
</ParamField>

<ParamField body="material_asset_id" type="string">
  ID de material Seedance de TokenLab devuelto por [Crear material](/es/api-reference/video/create-material-asset) o por la preparación automática de imágenes. Úsalo después de que el material esté `ACTIVE` con modelos Seedance que puedan usar la biblioteca de materiales de TokenLab.
</ParamField>

<ParamField body="material_asset_ids" type="array">
  Varios IDs de material Seedance de TokenLab. Comparten el límite de referencias de imagen de Seedance con `reference_images`; el modelo seleccionado debe poder usar la biblioteca de materiales de TokenLab.
</ParamField>

<Info>
  Cuando el modelo Seedance seleccionado puede usar la biblioteca de materiales de TokenLab, TokenLab prepara los campos de imagen (`image`, `image_url`, `image_urls`, `reference_images`, `start_image`, `end_image`) como materiales reutilizables antes de generar. Si la preparación no termina en 60 segundos, la API devuelve `409 seedance_material_preparing` con `auto_material_asset_ids`; reintenta cuando esos materiales estén `ACTIVE`. Si el modelo seleccionado no puede usar la biblioteca de materiales, las entradas de imagen normales siguen el flujo de imagen habitual y los IDs de material explícitos fallan de forma segura con un error de disponibilidad de material.
</Info>

<ParamField body="reference_image_type" type="string">
  Campo opcional para modelos que distinguen entre referencias `asset` y `style`.
</ParamField>

<ParamField body="kling_elements" type="array">
  Definiciones de referencias de elementos de Kling 3.0. Solo se admiten con `kling-3.0-video` en solicitudes condicionadas por imagen. Define 1-3 elementos; cada elemento incluye `name`, `description` opcional y `element_input_urls` con 2-4 URL de imágenes. Referencia cada elemento en `prompt` como `@name`. No combines `kling_elements` con `output_audio=true`; omite `output_audio` o ponlo en `false` para solicitudes con referencias de elementos.
</ParamField>

<ParamField body="video_url" type="string">
  URL pública del video de origen. Requerida para flujos `video-to-video` basados en URL de video y para `motion-control`; algunos flujos derivados usan `task_id` en su lugar.
</ParamField>

<ParamField body="video_urls" type="array">
  Entradas adicionales de video de referencia para modelos con condicionamiento multimodal. La cantidad admitida depende del modelo. Para `seedance-2.0` y `seedance-2.0-fast`, TokenLab admite actualmente hasta 3 videos de referencia.
</ParamField>

<ParamField body="audio_url" type="string">
  URL pública del audio para modelos que admiten `audio-to-video`.
</ParamField>

<ParamField body="audio_urls" type="array">
  Entradas adicionales de audio de referencia para modelos con condicionamiento multimodal. La cantidad admitida depende del modelo. Para `seedance-2.0` y `seedance-2.0-fast`, TokenLab admite actualmente hasta 3 audios de referencia.
</ParamField>

<ParamField body="task_id" type="string">
  Identificador de tarea usado por algunos flujos de continuación, extensión o derivados.
</ParamField>

<ParamField body="extend_at" type="integer">
  Desplazamiento inicial específico del modelo para algunos flujos `video-extension`.
</ParamField>

<ParamField body="extend_times" type="string">
  Multiplicador o número de repeticiones específico del modelo para algunos flujos `video-extension`.
</ParamField>

<ParamField body="duration" type="integer">
  Duración del video generado en segundos. Para modelos Seedance 1.5/2.0, omitir este campo usa `5`; enviar `-1` permite que el modelo elija dentro de su rango admitido, y la facturación se estima de forma conservadora hasta que finaliza la tarea.
</ParamField>

<ParamField body="seconds" type="integer">
  Alias compatible de `duration`. Si envías `seconds` y `duration`, ambos deben ser idénticos. Para Seedance, `seconds=-1` tiene el mismo significado de duración automática que `duration=-1`.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Relación de aspecto canónica, por ejemplo `adaptive`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4` o `21:9`. Seedance usa `adaptive` por defecto cuando se omite.
</ParamField>

<ParamField body="resolution" type="string">
  Resolución de salida dependiente del modelo. Seedance usa `720p` por defecto; `seedance-2.0` admite `480p`, `720p`, `1080p` y `4k`, mientras que `seedance-2.0-fast` y `seedance-2.0-mini` se limitan a `480p` y `720p`.
</ParamField>

<ParamField body="output_audio" type="boolean">
  Control canónico de salida de audio dependiente del modelo. Veo 3 y Seedance usan `true` por defecto cuando se omite. `kling-3.0-video` acepta este selector en solicitudes sin referencias de elementos y, cuando se omite, genera salida sin audio. No combines `output_audio=true` con `kling_elements`.
</ParamField>

<ParamField body="draft" type="boolean">
  Indicador del flujo Draft de Seedance 1.5 Pro. Usa `draft=true` con modelos Seedance que admiten tareas draft. No lo envíes junto con `draft_task_id`.
</ParamField>

<ParamField body="draft_task_id" type="string">
  ID de tarea draft de Seedance 1.5 Pro para promoción. Envía el ID de una tarea draft anterior para crear el video final; no es un campo genérico de video.
</ParamField>

<ParamField body="ratio" type="string">
  Alias compatible de `aspect_ratio`. Si se envían `ratio` y `aspect_ratio`, deben ser idénticos.
</ParamField>

<ParamField body="generate_audio" type="boolean">
  Alias compatible de `output_audio`. Si aparecen `generate_audio`, `output_audio` y `outputAudio`, todos los valores deben coincidir.
</ParamField>

<ParamField body="execution_expires_after" type="integer">
  Tiempo opcional de expiración de ejecución en segundos para modelos de video compatibles. Seedance usa `172800` segundos por defecto cuando se omite.
</ParamField>

<ParamField body="priority" type="integer">
  Prioridad opcional de la tarea de `0` a `9` para modelos de video compatibles. No combines `priority` con `service_tier=flex`.
</ParamField>

<ParamField body="safety_identifier" type="string">
  Identificador opcional de seguridad del usuario final para modelos de video compatibles. Si se omite en Seedance, TokenLab usa `user` cuando está disponible.
</ParamField>

<ParamField body="service_tier" type="string">
  `default` se acepta como no-op compatible para modelos Seedance 2.0. `flex` solo se permite cuando el modelo seleccionado lo admite.
</ParamField>

<ParamField body="frames" type="integer">
  Recuento opcional de fotogramas para modelos de video compatibles. Los modelos Seedance 2.0 y Seedance 1.5 Pro no admiten este campo.
</ParamField>

<ParamField body="camera_fixed" type="boolean">
  Selector opcional de cámara fija para modelos de video compatibles. Los modelos Seedance 2.0 no admiten este campo.
</ParamField>

<ParamField body="fps" type="integer">
  Fotogramas por segundo (1-120). Solo surte efecto en los modelos que exponen FPS.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Elementos que deben evitarse en el video generado.
</ParamField>

<ParamField body="seed" type="integer">
  Semilla aleatoria para generación reproducible. Seedance usa `-1` como semilla aleatoria cuando se omite.
</ParamField>

<ParamField body="cfg_scale" type="number">
  Intensidad de adherencia al prompt (0-20) en los modelos que exponen este control.
</ParamField>

<ParamField body="motion_strength" type="number">
  Intensidad del movimiento (0-1) en los modelos que exponen este control.
</ParamField>

<ParamField body="start_image" type="string">
  URL de la imagen del primer fotograma, o entrada compatible, para `start-end-to-video`.
</ParamField>

<ParamField body="end_image" type="string">
  URL de la imagen del último fotograma, o entrada compatible, para `start-end-to-video`.
</ParamField>

<ParamField body="size" type="string">
  Nivel de tamaño específico del modelo para modelos de video compatibles.
</ParamField>

<ParamField body="watermark" type="boolean">
  Control opcional de marca de agua para modelos que lo exponen. Seedance usa `false` por defecto cuando se omite.
</ParamField>

<ParamField body="effect_type" type="string">
  Selector de efecto específico del modelo para algunos flujos especializados de edición o efectos.
</ParamField>

<ParamField body="user" type="string">
  Identificador único del usuario final. Para Seedance, TokenLab también usa este valor como `safety_identifier` cuando ese campo se omite.
</ParamField>

## Notas de compatibilidad

* Los campos públicos canónicos están en snake\_case: `reference_images`, `reference_image_type` y `output_audio`.
* Los campos públicos canónicos siguen usando snake\_case: `aspect_ratio`, `output_audio`, `reference_images` y `reference_image_type`.
* Por compatibilidad, TokenLab también acepta `ratio`, `generate_audio`, `outputAudio`, `seconds`, `referenceImages` y `referenceImageType`.
* Si se envían campos canónicos y alias al mismo tiempo, sus valores deben coincidir; los alias en conflicto se rechazan antes de crear la tarea.

## Buenas prácticas para entradas de medios

* Para `image_url`, `reference_images`, `video_url` y `audio_url`, es preferible usar URLs `https` públicas.
* Siempre que sea posible, evita mezclar base64 inline y URLs remotas en la misma solicitud.
* Asegúrate de que las URLs multimedia remotas sigan siendo válidas durante los reintentos y la creación asíncrona de tareas.

## Parámetros de Seedance

Para modelos Seedance 1.5/2.0, el endpoint unificado sigue los nombres de campos de TokenLab y acepta los alias compatibles `seconds`, `ratio` y `generate_audio`. Si se omiten los selectores de Seedance, se usan estos valores por defecto: `duration=5`, `resolution=720p`, `aspect_ratio=adaptive`, `output_audio=true`, `watermark=false`, `return_last_frame=false`, `execution_expires_after=172800`, `priority=0` y `seed=-1`.

`duration=-1` o `seconds=-1` permite que Seedance elija la duración de salida dentro del rango admitido por el modelo. TokenLab estima el coste de forma conservadora antes de que finalice la tarea y luego liquida según el uso de la tarea completada cuando está disponible. `service_tier=default` se acepta como no-op compatible para Seedance 2.0; `service_tier=flex`, `frames` y `camera_fixed` se rechazan cuando el modelo seleccionado no los admite.

### Ejemplo de 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
  }'
```

## Respuesta

<ResponseField name="id" type="string">
  Identificador canónico de la tarea asíncrona. Cuando `id` y `task_id` estén presentes a la vez, considéralos la misma tarea.
</ResponseField>

<ResponseField name="task_id" type="string">
  Identificador único de la tarea para hacer polling.
</ResponseField>

<ResponseField name="poll_url" type="string">
  URL de polling recomendada para esta tarea. Usa exactamente esta ruta al consultar el estado.
</ResponseField>

<ResponseField name="billing_transaction_id" type="string">
  ID de transacción de facturación de TokenLab cuando la liquidación ya terminó. Es el identificador de dashboard/contabilidad y es distinto del `id` / `task_id` asíncrono.
</ResponseField>

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

<ResponseField name="created" type="integer">
  Marca de tiempo Unix de creación de la tarea.
</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>

## Imagen a video

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

Usa `kling_elements` con `kling-3.0-video` cuando necesites referencias de elementos. Proporciona una solicitud condicionada por imagen (`image_url`, `image_urls`, `start_image` o `end_image`) y referencia cada elemento en el prompt con `@name`. No combines `kling_elements` con `output_audio=true`; omite `output_audio` o ponlo en `false` para solicitudes con referencias 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"
                ]
            }
        ]
    }
)
```

## Referencia a video

Usa `operation=reference-to-video` cuando el modelo admita condicionamiento de referencia dedicado. En los detalhes do modelo de TokenLab, las referencias de imagen se envían mediante `reference_images`, mientras que los videos y audios de referencia multimodales se envían mediante `video_urls` y `audio_urls`. Para `seedance-2.0` y `seedance-2.0-fast`, TokenLab admite actualmente hasta 9 imágenes de referencia, además de hasta 3 videos de referencia y 3 audios de referencia. Para selección de modelo, límites 4K y notas de Mini, consulta la [guía de modelos de video Seedance 2.0](/es/guides/seedance-2-video). `duration` solo controla la duración del resultado generado; no fija un límite independiente para la duración del video de referencia de entrada. Para `grok-imagine-video`, reference-to-video acepta hasta 7 referencias de imagen (`reference_images` o `image_urls`) y `duration` está limitada a 10 segundos. No combines referencias de imagen con entradas de primer fotograma `image_url` / `image`. `grok-imagine-video-1.5-preview` solo admite 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"
    }
)
```

## Control de fotograma inicial y final

Usa `start_image` y `end_image` para controlar el primer y el último fotograma.

```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"
    }
)
```

## Video a video

Para video-to-video con `grok-imagine-video`, envía una URL HTTPS pública `.mp4` en `video_url`. TokenLab la traduce al cuerpo REST de xAI `video.url`. Puedes definir `resolution` como `480p` o `720p`; `duration` y `aspect_ratio` no se aceptan en ese flujo de edición.

Cuando un modelo acepta un video existente como entrada principal, usa `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"
    }
)
```

## Control de movimiento

Cuando un modelo necesita tanto una imagen del sujeto como un video de referencia de movimiento, usa `operation=motion-control`. TokenLab normaliza la forma pública `image_url` + `video_url` al formato motion-control de ese 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"
    }
)
```

## Descubrimiento de modelos

El inventario público de video y las operaciones admitidas cambian con el tiempo. Usa la [Models API](/es/api-reference/models/list-models) como referencia actual antes de implementar un flujo específico de un 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"
```

Lee la respuesta de detalle del modelo antes de depender de operaciones o campos específicos del modelo. Operaciones como `audio-to-video` y `video-extension` dependen del modelo; confirma allí la disponibilidad actual en lugar de depender de ejemplos estáticos de esta página.