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

# Interfaz de generación de vídeo

>  AiHubMix ofrece una API unificada de generación de vídeo, compatible con el formato de la interfaz OpenAI Sora, con soporte backend para modelos de múltiples proveedores

## Inicio rápido

La generación de vídeo es una operación asíncrona; todo el flujo se divide en tres pasos:

```text theme={null}
1. Enviar la tarea → obtener video_id
2. Sondear el estado → esperar a que status cambie a completed
3. Descargar el vídeo → obtener el archivo MP4
```

**Ejemplo mínimo**

```shellscript theme={null}
# Paso uno: enviar la tarea de generación de vídeo
curl -X POST https://aihubmix.com/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A cat playing jazz on a piano, warm lighting, cinematic shot",
    "seconds": "5",
    "size": "1280x720"
  }'

# Ejemplo de respuesta:
# {
#   "id": "eyJtb2RlbCI6IndhbjI...",
#   "object": "video",
#   "status": "in_progress",
#   "model": "wan2.6-t2v",
#   "duration": 5,
#   "width": 1280,
#   "height": 720,
#   ...
# }

# Paso dos: sondear el estado (consultar cada 15 segundos hasta que status sea completed)
curl https://aihubmix.com/v1/videos/{video_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# Paso tres: descargar el vídeo
curl https://aihubmix.com/v1/videos/{video_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output video.mp4
```

## Resumen de las interfaces

| Interfaz         | Método | Ruta                            | Descripción                                   |
| :--------------- | :----- | :------------------------------ | :-------------------------------------------- |
| Crear vídeo      | POST   | `/v1/videos`                    | Enviar la tarea de generación de vídeo        |
| Consultar estado | GET    | `/v1/videos/{video_id}`         | Consultar el estado y el progreso de la tarea |
| Descargar vídeo  | GET    | `/v1/videos/{video_id}/content` | Descargar el vídeo MP4 generado               |
| Eliminar tarea   | DELETE | `/v1/videos/{video_id}`         | Eliminar la tarea de vídeo                    |

Base URL: `https://aihubmix.com`

Método de autenticación: Bearer Token

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
```

## Modelos compatibles

### Texto a vídeo (Text-to-Video)

| Proveedor | Nombre del modelo                                       | Características                                                                         |
| --------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| OpenAI    | `sora-2`                                                | Generación de vídeo estándar, con sincronización de audio e imagen                      |
| OpenAI    | `sora-2-pro`                                            | Versión de alta calidad, con imágenes más refinadas y estables                          |
| Google    | `veo-3.1-generate-preview`                              | Veo 3.1 más reciente, audio nativo, soporta 4K                                          |
| Google    | `veo-3.1-fast-generate-preview`                         | Versión rápida de Veo 3.1, con mayor velocidad de generación                            |
| Google    | `veo-3.0-generate-preview`                              | Veo 3.0, vídeo de alta fidelidad                                                        |
| Google    | `veo-2.0-generate-001`                                  | Veo 2.0, versión estable                                                                |
| Alibaba   | `wan2.6-t2v`                                            | Tongyi Wanxiang más reciente, sincronización de audio e imagen                          |
| Alibaba   | `wan2.5-t2v-preview`                                    | Tongyi Wanxiang 2.5, optimizado para el chino                                           |
| Alibaba   | `wan2.2-t2v-plus`                                       | Tongyi Wanxiang 2.2                                                                     |
| ByteDance | `jimeng-3.0-pro`                                        | Jimeng 3.0 Pro, alta definición 1080P                                                   |
| ByteDance | `jimeng-3.0-1080p`                                      | Jimeng 3.0 1080P                                                                        |
| ByteDance | `doubao-seedance-2-0-260128`                            | Modelo de vídeo multimodal de creación de nivel profesional Seedance 2.0                |
| ByteDance | `doubao-seedance-2-0-fast-260128`                       | Versión rápida de Seedance 2.0                                                          |
| Kuaishou  | `kling-v3`、`kling-v2-6`、`kling-v2-5-turbo`、`kling-v2-1` | Kling texto a vídeo / imagen a vídeo, las versiones nuevas soportan de 3 a 15 segundos  |
| Kuaishou  | `kling-v3-omni`、`kling-video-o1`                        | Kling OmniVideo multimodal, soporta vídeo de referencia, audio nativo y múltiples tomas |

### Imagen a vídeo (Image-to-Video)

| Proveedor | Nombre del modelo                 | Características                                                                            |
| --------- | --------------------------------- | ------------------------------------------------------------------------------------------ |
| Alibaba   | `wan2.6-i2v`                      | Tongyi Wanxiang más reciente, imagen a vídeo                                               |
| Alibaba   | `wan2.5-i2v-preview`              | Tongyi Wanxiang 2.5, imagen a vídeo                                                        |
| Alibaba   | `wan2.2-i2v-plus`                 | Tongyi Wanxiang 2.2, imagen a vídeo                                                        |
| ByteDance | `doubao-seedance-2-0-260128`      | Entrada de referencia multimodal, soporta imagen/vídeo/audio                               |
| ByteDance | `doubao-seedance-2-0-fast-260128` | Versión rápida de Seedance 2.0                                                             |
| Kuaishou  | `kling-v1-6`, etc.                | Kling imagen a vídeo, soporta fotograma final y referencia de múltiples imágenes (hasta 4) |

<Note>
  Para imagen a vídeo, pasa la imagen de referencia mediante el parámetro `input_reference` (Tongyi Wanxiang de Alibaba); Doubao Seedance la pasa mediante el array `extra_body.content`, que admite varios tipos de referencia: imagen, vídeo y audio; Kling usa `image` / `image_tail` / `image_list` para pasar imágenes, consulta la sección [Kling](#kling) más abajo.
</Note>

## Descripción detallada de la API

### Cabeceras de la petición

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
Content-Type: application/json
```

### Crear tarea de generación de vídeo

```shellscript theme={null}
POST /v1/videos
```

#### **Cuerpo de la petición**

| Parámetro         | Tipo          | Obligatorio | Descripción                                                                                                      |
| :---------------- | :------------ | :---------- | :--------------------------------------------------------------------------------------------------------------- |
| `model`           | string        | Sí          | Nombre del modelo, como `wan2.6-t2v`、`sora-2`                                                                    |
| `prompt`          | string        | Sí          | Texto descriptivo del vídeo                                                                                      |
| `seconds`         | string        | No          | Duración del vídeo (segundos), se usa siempre el tipo string, como `"5"`、`"8"` (ver los detalles de cada modelo) |
| `size`            | string        | No          | Resolución, en formato `ancho x alto`, como `1920x1080` (los valores admitidos varían según el modelo)           |
| `input_reference` | string/object | No          | Imagen de referencia (imagen a vídeo), admite URL o base64                                                       |

> El formato de respuesta varía ligeramente según el modelo, pero todos incluyen los campos `id` (video\_id) y `status`. Basta con usar `status` para evaluar el progreso de la tarea.

#### Ejemplo de respuesta (**Tongyi Wanxiang / Veo / Jimeng**)

```json theme={null}
{
  "id": "eyJtb2RlbCI6IndhbjI...",
  "object": "video",
  "created": 1772460274,
  "model": "wan2.6-t2v",
  "status": "in_progress",
  "prompt": "A cat watching the rain on a windowsill",
  "duration": 5,
  "width": 1920,
  "height": 1080,
  "url": null,
  "error": null
}
```

**Ejemplo de respuesta (Sora)**

```json theme={null}
{
  "id": "eyJtb2RlbCI6InNvcmEtMi...",
  "object": "video",
  "created_at": 1772451930,
  "status": "queued",
  "model": "sora-2",
  "progress": 0,
  "prompt": "A cinematic drone shot over mountains",
  "seconds": "8",
  "size": "1280x720"
}
```

#### Descripción de los valores de estado generales

| Estado        | Descripción                                 |
| :------------ | :------------------------------------------ |
| `queued`      | En cola (exclusivo de Sora)                 |
| `in_progress` | Generando                                   |
| `completed`   | Generación completada, listo para descargar |
| `failed`      | Generación fallida                          |

### Consultar el estado del vídeo

```shellscript theme={null}
GET /v1/videos/{video_id}
```

Sondea esta interfaz para comprobar si la tarea ha terminado. Se recomienda consultar cada **15 segundos**.

#### **Ejemplo de respuesta (generación completada - Tongyi Wanxiang)**

```json theme={null}
{
  "id": "eyJtb2RlbCI6IndhbjI...",
  "object": "video",
  "status": "completed",
  "model": "wan2.5-t2v-preview",
  "duration": 5,
  "width": 1920,
  "height": 1080,
  "url": "https://aihubmix.com/v1/videos/eyJtb2RlbCI6IndhbjI.../content",
  "error": null
}
```

#### **Ejemplo de respuesta (generación completada - Sora)**

```json theme={null}
{
  "id": "eyJtb2RlbCI6InNvcmEtMi...",
  "object": "video",
  "created_at": 1772451930,
  "status": "completed",
  "completed_at": 1772452114,
  "expires_at": 1772538330,
  "model": "sora-2",
  "progress": 100,
  "prompt": "A cinematic drone shot over mountains",
  "seconds": "8",
  "size": "1280x720"
}
```

> Todos los modelos evalúan el estado de finalización mediante `status == "completed"` y luego llaman a la interfaz `/content` para descargar.

### Descargar el contenido del vídeo

```shellscript theme={null}
GET /v1/videos/{video_id}/content
```

Cuando el estado sea `completed`, llama a esta interfaz para descargar el archivo de vídeo MP4.

**Respuesta**: devuelve directamente el flujo binario del vídeo (`Content-Type: video/mp4`).

```shellscript theme={null}
curl https://aihubmix.com/v1/videos/{video_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output my_video.mp4
```

> **Nota**: el enlace de descarga del vídeo suele tener una validez de 24 horas; descárgalo y guárdalo a tiempo.

### Eliminar tarea de vídeo

Esta interfaz se usa para eliminar una tarea de vídeo ya creada.

```shellscript theme={null}
DELETE /v1/videos/{video_id}
```

## Detalle de los parámetros de cada modelo

### **OpenAI Sora**

| Parámetro          | Valores admitidos                                           |
| ------------------ | ----------------------------------------------------------- |
| Modelo             | `sora-2`、`sora-2-pro`                                       |
| Duración (seconds) | `"4"` (por defecto)、`"8"`、`"12"`                            |
| Resolución (size)  | `720x1280` (por defecto)、`1280x720`、`1024x1792`、`1792x1024` |
| Imagen a vídeo     | Compatible, pasa la imagen mediante `input_reference`       |

> Sugerencia: el parámetro `seconds` de todos los modelos se pasa siempre como tipo string (como `"8"`).

**Ejemplo**

<CodeGroup>
  ```shellscript Sora theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sora-2",
      "prompt": "A cinematic drone shot soaring over a misty mountain range at sunrise, golden light filtering through the clouds",
      "seconds": "8",
      "size": "1280x720"
    }'
  ```

  ```shellscript Sora Pro vídeo vertical theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sora-2-pro",
      "prompt": "A person walking through a neon-lit city street at night, rain reflecting on the pavement, cinematic lighting",
      "seconds": "12",
      "size": "720x1280"
    }'
  ```
</CodeGroup>

### Google Veo

| Parámetro                | Valores admitidos                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Modelo                   | `veo-3.1-generate-preview` (recomendado)、`veo-3.1-fast-generate-preview` (rápido)、`veo-3.0-generate-preview`、`veo-2.0-generate-001`                                                                                                                                                                                                                                                                                                                                 |
| Duración (seconds)       | Veo 3/3.1: `"4"`、`"6"`、`"8"`; Veo 2: `"5"`\~`"8"` (por defecto `"8"`)                                                                                                                                                                                                                                                                                                                                                                                               |
| Resolución (size)        | `720p` (por defecto)、`1080p`、`4k` (4K solo en Veo 3+), o formato de píxeles como `1280x720`、`1920x1080`                                                                                                                                                                                                                                                                                                                                                             |
| Relación de aspecto      | 16:9 (por defecto)、9:16                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Imagen a vídeo (Veo 3.1) | **Primer fotograma**: `first_frame` (o el campo compatible `input_reference`); **Último fotograma**: `last_frame`; **Imágenes de referencia**: `reference_images` (array, hasta 3). Las imágenes aceptan una URL pública, un data URL en base64 o un objeto `{"mime_type": "...", "data": "..."}`. **Duración**: primer fotograma / primer y último fotograma admiten `"4"`/`"6"`/`"8"`; cuando se usan imágenes de referencia, Google fija la salida en 8 segundos |

**Ejemplo**

<CodeGroup>
  ```shellscript Veo 3.1 theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-generate-preview",
      "prompt": "A tranquil Japanese garden, cherry blossom petals slowly drifting down, koi swimming in the pond, with the melodious sound of wind chimes in the background",
      "seconds": "8",
      "size": "1280x720"
    }'
  ```

  ```shellscript Veo 3.1 Fast theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-fast-generate-preview",
      "prompt": "Ocean waves crashing on rocky cliffs at sunset, seagulls flying overhead",
      "seconds": "8",
      "size": "1280x720"
    }'
  ```

  ```shellscript Primer y último fotograma theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-generate-preview",
      "prompt": "The camera slowly pushes in from a valley at dawn, transitioning naturally into sunset",
      "seconds": "8",
      "size": "1280x720",
      "first_frame": "https://example.com/first.jpg",
      "last_frame": "https://example.com/last.jpg"
    }'
  ```

  ```shellscript Imágenes de referencia (hasta 3) theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-generate-preview",
      "prompt": "The character from the reference images walks through a forest, cinematic shot",
      "seconds": "8",
      "size": "1280x720",
      "reference_images": [
        "https://example.com/ref1.jpg",
        "https://example.com/ref2.jpg"
      ]
    }'
  ```
</CodeGroup>

<Note>
  **Notas sobre los campos de imagen**:

  * Precedencia del primer fotograma: `first_frame` > `input_reference` (fotograma único compatible con OpenAI).
  * Cada elemento de `first_frame` / `last_frame` / `reference_images` acepta: una URL pública, un data URL en base64 (`data:image/png;base64,...`) o un objeto `{"mime_type":"image/png","data":"<base64>"}`.
  * También se aceptan los alias al estilo OpenRouter `frame_images` (elementos con `frame_type: first_frame | last_frame`) e `input_references`.
  * Hasta 3 imágenes de referencia; superarlo devuelve 400.
</Note>

> Sugerencia: Veo admite la generación de audio nativo; puedes describir los efectos de sonido en el prompt, como "de fondo se oye el canto de los pájaros" o "una melodía de piano".

### Tongyi Wanxiang

| Parámetro             | Valores admitidos                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| Modelo texto a vídeo  | `wan2.6-t2v` (recomendado)、`wan2.5-t2v-preview`、`wan2.2-t2v-plus`                                   |
| Modelo imagen a vídeo | `wan2.6-i2v` (recomendado)、`wan2.5-i2v-preview`、`wan2.2-i2v-plus`                                   |
| Duración (seconds)    | Varía según el modelo (ver la descripción más abajo), por defecto `"5"`                             |
| Resolución (size)     | Ver la tabla más abajo, se admiten tanto el separador `x` como `*` (como `1920x1080` o `1920*1080`) |
| Imagen a vídeo        | Pasa la URL de la imagen o base64 mediante `input_reference`                                        |

**Duraciones admitidas por cada modelo**

| Modelo                                      | Valores posibles de seconds            | Valor por defecto |
| :------------------------------------------ | :------------------------------------- | :---------------- |
| `wan2.6-t2v` / `wan2.6-i2v`                 | `"2"`\~`"15"` (cualquier valor entero) | `"5"`             |
| `wan2.5-t2v-preview` / `wan2.5-i2v-preview` | `"5"` o `"10"`                         | `"5"`             |
| `wan2.2-t2v-plus` / `wan2.2-i2v-plus`       | `"5"` (fijo)                           | `"5"`             |

**Resoluciones admitidas (ancho\*alto)**

| Definición | Resoluciones posibles                                                           |
| :--------- | :------------------------------------------------------------------------------ |
| 480P       | `832x480`、`480x832`、`624x624`                                                   |
| 720P       | `1280x720` (por defecto)、`720x1280`、`960x960`、`1088x832` (4:3)、`832x1088` (3:4) |
| 1080P      | `1920x1080`、`1080x1920`、`1440x1440`、`1632x1248` (4:3)、`1248x1632` (3:4)         |

> **Nota**: wan2.6 solo admite 720P y 1080P; wan2.5 admite 480P, 720P y 1080P; wan2.2 solo admite 480P y 1080P.

**Ejemplo**

<CodeGroup>
  ```shellscript Texto a vídeo theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "wan2.6-t2v",
      "prompt": "A winding stream flows through an autumn forest, golden fallen leaves drifting on the water surface, sunlight casting dappled light and shadow through the leaves",
      "seconds": "5",
      "size": "1920x1080"
    }'
  ```

  ```shellscript Imagen a vídeo theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "wan2.6-i2v",
      "prompt": "The character in the frame slowly turns their head and smiles, the camera slowly pushes in",
      "seconds": "5",
      "size": "1280x720",
      "input_reference": "https://example.com/my-image.jpg"
    }'
  ```
</CodeGroup>

> Sugerencia: las versiones wan2.5 y superiores generan por defecto vídeo con sonido (doblaje automático); los prompts en chino dan mejores resultados.

### Jimeng AI

| Parámetro          | Valores admitidos                                                        |
| ------------------ | ------------------------------------------------------------------------ |
| Modelo             | `jimeng-3.0-pro` (recomendado)、`jimeng-3.0-1080p`                        |
| Duración (seconds) | `"5"` o `"10"` (por defecto `"5"`)                                       |
| Resolución (size)  | Admite formato de relación de aspecto o formato de píxeles               |
| Imagen a vídeo     | Compatible, pasa la URL de la imagen o base64 mediante `input_reference` |

**Relaciones de aspecto admitidas y sus resoluciones correspondientes**

| Relación de aspecto (size) | Resolución real |
| :------------------------- | :-------------- |
| `16:9` o `1920x1080`       | 1920×1088       |
| `9:16` o `1080x1920`       | 1088×1920       |
| `4:3` o `1664x1248`        | 1664×1248       |
| `3:4` o `1248x1664`        | 1248×1664       |
| `1:1` o `1440x1440`        | 1440×1440       |
| `21:9` o `2176x928`        | 2176×928        |

**Ejemplo**

<CodeGroup>
  ```shellscript Jimeng AI theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "jimeng-3.0-pro",
      "prompt": "A young woman in Hanfu dances gracefully amid a bamboo forest, her long dress flowing in the wind, with a faint morning mist in the background",
      "seconds": "5",
      "size": "16:9"
    }'
  ```

  ```Jimeng AI versión vertical theme={null}
  curl -X POST https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "jimeng-3.0-1080p",
      "prompt": "A sunset over the ocean, waves gently rolling, warm golden light",
      "seconds": "5",
      "size": "9:16"
    }'
  ```
</CodeGroup>

### Doubao Seedance

| Parámetro                          | Valores admitidos                                                                                    |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Modelo                             | `doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128`                                       |
| Resolución (resolution)            | `"480p"`、`"720p"` (por defecto)                                                                      |
| Duración (duration)                | Entero, rango `4`\~`15`, o `-1` (el modelo lo decide automáticamente)                                |
| Relación de aspecto (ratio)        | `"adaptive"` (por defecto, adaptación automática)、`"16:9"`、`"9:16"`、`"1:1"`、`"4:3"`、`"3:4"`、`"21:9"` |
| Vídeo con sonido (generate\_audio) | Por defecto `true`; configúralo en `false` para generar vídeo sin sonido                             |
| Marca de agua (watermark)          | Por defecto `false`                                                                                  |
| Referencia multimodal              | Admite imagen, vídeo y audio                                                                         |

**Tipos de referencia admitidos por `extra_body.content`**

| Tipo                 | Valor de `type` | Valor de `role`   | Descripción                                             |
| -------------------- | --------------- | ----------------- | ------------------------------------------------------- |
| Imagen de referencia | `image_url`     | `reference_image` | Imagen de referencia de escena/estilo                   |
| Vídeo de referencia  | `video_url`     | `reference_video` | Vídeo de referencia de movimiento de cámara/composición |
| Audio de referencia  | `audio_url`     | `reference_audio` | Archivo de audio de música de fondo                     |

**Ejemplo**

```shellscript Seedance 2.0 / 2.0 Fast theme={null}
curl -X POST "https://aihubmix.com/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "Use the first-person POV framing from Video 1 throughout, and use Audio 1 as the background music for the entire clip. Create a first-person fruit tea commercial featuring the Seedance brand limited-edition apple fruit tea, "Ping Ping An An." 

Opening frame: Image 1. From a first-person perspective, your hand picks a dew-covered Aksu red apple, accompanied by a crisp, satisfying bite-like tapping sound.

Seconds 2–4: Fast-paced cuts. Your hand drops freshly cut apple chunks into a shaker, adds ice and tea base, then shakes vigorously. The sound of ice clinking and shaking syncs with upbeat percussion. Background voiceover: "Freshly cut, freshly shaken."

Seconds 4–6: First-person close-up of the finished drink. The layered fruit tea is poured into a clear cup. Your hand gently squeezes a creamy topping across the surface. A pink label is placed on the cup. The camera pushes in to highlight the rich texture and layering.

Seconds 6–8: First-person hand holding the drink. You raise the fruit tea from Image 2 toward the camera, as if offering it directly to the viewer. The label is clearly visible. Background voiceover: "Take a refreshing sip."

Final frame: Freeze on Image 2. 

All background voiceovers should be in a female voice.",
    "extra_body": {
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
          },
          "role": "reference_image"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
          },
          "role": "reference_image"
        },
        {
          "type": "video_url",
          "video_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
          },
          "role": "reference_video"
        },
        {
          "type": "audio_url",
          "audio_url": {
            "url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
          },
          "role": "reference_audio"
        }
      ],
      "ratio": "16:9",
      "duration": 11,
      "watermark": false
    }
  }'
```

### Kling

Kling admite cuatro tipos de capacidades: **texto a vídeo, imagen a vídeo, vídeo a partir de referencia de múltiples imágenes y OmniVideo multimodal**, todas invocadas de forma unificada mediante la interfaz `/v1/videos`. La pasarela enruta automáticamente al endpoint correspondiente de Kling según «nombre del modelo + tipo de entrada», sin que el llamante tenga que distinguirlos.

| Capacidad                        | Modelo                                                                                       |
| -------------------------------- | -------------------------------------------------------------------------------------------- |
| Texto a vídeo / Imagen a vídeo   | `kling-v1`、`kling-v1-5`、`kling-v1-6`、`kling-v2-1`、`kling-v2-5-turbo`、`kling-v2-6`、`kling-v3` |
| Referencia de múltiples imágenes | `kling-v1-6`                                                                                 |
| OmniVideo multimodal             | `kling-video-o1`、`kling-v3-omni`                                                             |

**Parámetros**

| Parámetro              | Tipo   | Descripción                                                                                                                                                      |
| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                | string | **Obligatorio**, `kling-*`, determina la capacidad y la versión                                                                                                  |
| `prompt`               | string | Prompt de texto                                                                                                                                                  |
| `negative_prompt`      | string | Prompt negativo                                                                                                                                                  |
| `mode`                 | string | Modo de generación: `std` (720P) / `pro` (1080P) / `4k`, por defecto `std`                                                                                       |
| `duration` / `seconds` | string | Duración (segundos), modelos antiguos `5`/`10`, modelos nuevos `3`\~`15`, por defecto `5`                                                                        |
| `aspect_ratio`         | string | Encuadre: `16:9` / `9:16` / `1:1` (obligatorio en omni con texto puro o referencia de vídeo; si se omite, se completa automáticamente con `16:9`)                |
| `cfg_scale`            | float  | Relevancia respecto al prompt `[0, 1]`, por defecto `0.5` (`kling-v2.x` no lo admite)                                                                            |
| `image`                | string | **Imagen a vídeo**: imagen única, URL de la imagen o Base64 (el Base64 va sin el prefijo `data:image/...;base64,`)                                               |
| `image_tail`           | string | **Imagen a vídeo**: imagen del fotograma final (opcional)                                                                                                        |
| `image_list`           | array  | **Referencia de múltiples imágenes**: array de URL de imágenes, hasta 4                                                                                          |
| `sound`                | string | **omni**: `on`/`off`, si se genera audio nativo, por defecto `off`                                                                                               |
| `video_list`           | array  | **omni**: vídeo de referencia `[{ "video_url": "...", "refer_type": "feature" }]`, `refer_type` toma `feature` (referencia de vídeo) / `base` (edición de vídeo) |

<Note>
  Los parámetros clave que no se admiten o no están mapeados producen un error explícito; no se descartan de forma silenciosa. El resto de parámetros nativos de Kling pueden colocarse en `extra_body` para reenviarlos al servicio upstream.
</Note>

**Ejemplo**

<CodeGroup>
  ```shellscript Texto a vídeo theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v1-6",
      "prompt": "An orange cat running on a sunlit grassy meadow",
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript Imagen a vídeo theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v1-6",
      "image": "https://example.com/first.png",
      "prompt": "The camera pulls back, the character smiles",
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript Referencia de múltiples imágenes theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v1-6",
      "image_list": ["https://example.com/a.png", "https://example.com/b.png"],
      "prompt": "Two characters meet on the street",
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript OmniVideo vídeo de referencia theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v3-omni",
      "prompt": "Generate the next shot based on the reference video",
      "video_list": [{ "video_url": "https://example.com/in.mp4", "refer_type": "feature" }],
      "mode": "std",
      "duration": "5"
    }'
  ```

  ```shellscript OmniVideo audio nativo theme={null}
  curl https://aihubmix.com/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "kling-v3-omni",
      "prompt": "A man smiles and says hello",
      "sound": "on",
      "aspect_ratio": "16:9",
      "duration": "5"
    }'
  ```
</CodeGroup>

**Notas**

* **Tres pasos asíncronos**: enviar para obtener `video_id` → sondear `GET /v1/videos/{video_id}` hasta que `status` sea `completed` → descargar el MP4 con `GET /v1/videos/{video_id}/content`. Valores de estado: `in_progress` / `completed` / `failed`.
* La producción del vídeo suele tardar de 1 a 3 minutos; la URL del vídeo resultante se **elimina a los 30 días**, así que transfiérelo y guárdalo a tiempo.
* **Eliminar tarea**: Kling no dispone de interfaz de eliminación; `DELETE /v1/videos/{video_id}` devuelve `501 not_supported`.
* **Facturación**: se cobra según modelo × `mode` × duración × capacidad (con o sin vídeo de referencia / con sonido); **las generaciones fallidas no se cobran**, y las consultas y descargas no se facturan.

## **Ejemplo completo de invocación**

<CodeGroup>
  ```python Tongyi Wanxiang theme={null}
  import requests
  import time

  API_KEY = "AIHUBMIX_API_KEY"
  BASE_URL = "https://aihubmix.com"
  HEADERS = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  # Paso uno: crear la tarea de generación de vídeo
  response = requests.post(
      f"{BASE_URL}/v1/videos",
      headers=HEADERS,
      json={
          "model": "wan2.6-t2v",
          "prompt": "A desert under a starry sky, a meteor streaking across the night sky, the glow of a distant campfire flickering in the breeze",
          "seconds": "5",
          "size": "1920x1080"
      }
  )
  result = response.json()
  video_id = result["id"]
  print(f"Tarea creada, video_id: {video_id}")

  # Paso dos: sondear el estado
  while True:
      status_response = requests.get(
          f"{BASE_URL}/v1/videos/{video_id}",
          headers=HEADERS
      )
      status_data = status_response.json()
      current_status = status_data["status"]
      print(f"Estado actual: {current_status}")

      if current_status == "completed":
          print("¡Generación de vídeo completada!")
          break
      elif current_status == "failed":
          error_msg = status_data.get("error", {})
          if isinstance(error_msg, dict):
              error_msg = error_msg.get("message", "Error desconocido")
          print(f"Generación fallida: {error_msg}")
          break

      time.sleep(15)  # Consultar cada 15 segundos

  # Paso tres: descargar el vídeo
  video_response = requests.get(
      f"{BASE_URL}/v1/videos/{video_id}/content",
      headers=HEADERS
  )
  with open("output.mp4", "wb") as f:
      f.write(video_response.content)
  print(f"Vídeo guardado como output.mp4 ({len(video_response.content) / 1024 / 1024:.1f} MB)")
  ```

  ```python Sora theme={null}
  import requests
  import time

  API_KEY = "AIHUBMIX_API_KEY"
  BASE_URL = "https://aihubmix.com"
  HEADERS = {
      "Authorization": f"Bearer {API_KEY}",
      "Content-Type": "application/json"
  }

  # Crear la tarea de generación de vídeo
  response = requests.post(
      f"{BASE_URL}/v1/videos",
      headers=HEADERS,
      json={
          "model": "sora-2",
          "prompt": "A cinematic shot of a futuristic city at sunset, flying cars in the background",
          "seconds": "8",       # Opciones "4"/"8"/"12"
          "size": "1280x720"    # Admite 1280x720, 720x1280, 1024x1792, 1792x1024
      }
  )
  result = response.json()
  video_id = result["id"]
  print(f"Tarea creada, video_id: {video_id}")

  # Sondeo del estado de Sora (puede aparecer queued -> in_progress -> completed)
  while True:
      status_response = requests.get(
          f"{BASE_URL}/v1/videos/{video_id}",
          headers=HEADERS
      )
      status_data = status_response.json()
      current_status = status_data["status"]
      progress = status_data.get("progress", "")
      print(f"Estado: {current_status}, progreso: {progress}%")

      if current_status == "completed":
          print("¡Generación de vídeo completada!")
          break
      elif current_status == "failed":
          print(f"Generación fallida: {status_data.get('error')}")
          break

      time.sleep(15)

  # Descargar el vídeo
  video_response = requests.get(
      f"{BASE_URL}/v1/videos/{video_id}/content",
      headers=HEADERS
  )
  with open("sora_output.mp4", "wb") as f:
      f.write(video_response.content)
  print("Vídeo guardado como sora_output.mp4")
  ```

  ```javascript Node.js theme={null}
  const API_KEY = "your_aihubmix_api_key";
  const BASE_URL = "https://aihubmix.com";

  async function generateVideo() {
    // Paso uno: crear la tarea (con Veo 3.1 como ejemplo)
    const createResponse = await fetch(`${BASE_URL}/v1/videos`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        model: "veo-3.1-generate-preview",
        prompt: "A desert under a starry sky, a meteor streaking across the night sky",
        seconds: "8",
        size: "1280x720"
      })
    });
    const { id: videoId } = await createResponse.json();
    console.log(`Tarea creada: ${videoId}`);

    // Paso dos: sondear el estado
    let status = "in_progress";
    while (status !== "completed" && status !== "failed") {
      await new Promise(resolve => setTimeout(resolve, 15000));
      const statusResponse = await fetch(`${BASE_URL}/v1/videos/${videoId}`, {
        headers: { "Authorization": `Bearer ${API_KEY}` }
      });
      const result = await statusResponse.json();
      status = result.status;
      console.log(`Estado actual: ${status}`);
    }

    if (status === "completed") {
      // Paso tres: descargar el vídeo
      const videoResponse = await fetch(`${BASE_URL}/v1/videos/${videoId}/content`, {
        headers: { "Authorization": `Bearer ${API_KEY}` }
      });
      const fs = require("fs");
      const buffer = Buffer.from(await videoResponse.arrayBuffer());
      fs.writeFileSync("output.mp4", buffer);
      console.log("Vídeo guardado como output.mp4");
    }
  }

  generateVideo();
  ```
</CodeGroup>

## **FAQ**

### **¿Cuánto tarda la generación de vídeo?**

La generación de vídeo suele tardar de 1 a 5 minutos; el tiempo concreto depende del modelo, la resolución y la duración. Se recomienda establecer un intervalo de sondeo de 15 segundos.

### ¿Cómo se usa el parámetro `input_reference`?

`input_reference` se usa en el escenario de imagen a vídeo y admite tres formas de pasarlo:

```json theme={null}
// Forma uno: pasar directamente la URL de la imagen
"input_reference": "https://example.com/image.jpg"

// Forma dos: pasar la imagen codificada en base64 (formato de objeto)
"input_reference": {
  "mime_type": "image/jpeg",
  "data": "<BASE64_ENCODED_IMAGE>"
}

// Forma tres: pasar una data URL
"input_reference": "data:image/jpeg;base64,<BASE64_ENCODED_IMAGE>"
```

### **¿Cuál es la validez del enlace de descarga del vídeo?**

El enlace de descarga del vídeo generado suele tener una validez de **24 horas**; descárgalo y guárdalo a tiempo.

### **¿Qué diferencias hay en el parámetro `seconds` entre los modelos?**

| Modelo                                                           | Valores posibles                | Valor por defecto |
| ---------------------------------------------------------------- | ------------------------------- | ----------------- |
| Sora (`sora-2` / `sora-2-pro`)                                   | `"4"`, `"8"`, `"12"`            | `"4"`             |
| Veo 3/3.1 (`veo-3.1-generate-preview`, etc.)                     | `"4"`, `"6"`, `"8"`             | `"8"`             |
| Veo 2 (`veo-2.0-generate-001`)                                   | `"5"`\~`"8"`                    | `"8"`             |
| Tongyi Wanxiang `wan2.6`                                         | `"2"`\~`"15"`                   | `"5"`             |
| Tongyi Wanxiang `wan2.5`                                         | `"5"`, `"10"`                   | `"5"`             |
| Tongyi Wanxiang `wan2.2`                                         | `"5"` (fijo)                    | `"5"`             |
| Jimeng AI (`jimeng-3.0-pro`, etc.)                               | `"5"`, `"10"`                   | `"5"`             |
| Doubao Seedance (`doubao-seedance-2-0-*`)                        | Entero `duration4`\~`15` o `-1` | `5`               |
| Kling versión nueva (`kling-v2-x` / `kling-v3`, etc.)            | `"3"`\~`"15"`                   | `"5"`             |
| Kling versión antigua (`kling-v1` / `kling-v1-5` / `kling-v1-6`) | `"5"`, `"10"`                   | `"5"`             |

\> **Sugerencia**: el parámetro `seconds` de todos los modelos se pasa siempre como tipo string (como `"8"`), y la API lo procesa automáticamente.

### ¿Qué diferencias hay en el formato del parámetro `size` entre los modelos?

| Modelo          | Valores de size admitidos                                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Sora            | `1280x720`、`720x1280`、`1024x1792`、`1792x1024`                                                                                               |
| Veo             | Formato de píxeles (`1280x720`, etc.) o etiquetas de resolución (`720p`、`1080p`、`4k`)                                                       |
| Tongyi Wanxiang | Formato de píxeles, tanto `x` como `*` (como `1920x1080` o `1920*1080`)                                                                     |
| Jimeng AI       | Formato de relación de aspecto (`16:9`、`9:16`, etc.) o formato de píxeles                                                                   |
| Doubao Seedance | Formato de relación de aspecto (`"adaptive"`、`"16:9"`、`"9:16"`, etc.)                                                                       |
| Kling           | No usa `size`; en su lugar usa `mode` (`std`/`pro`/`4k` controla la definición) + `aspect_ratio` (`16:9`/`9:16`/`1:1` controla el encuadre) |

### ¿Qué diferencia hay entre `seconds` y `duration`?

Ambos significan lo mismo: la duración del vídeo. La API admite ambos nombres de parámetro (excepto Sora, que solo acepta `seconds`). Se recomienda usar `seconds` de forma uniforme.

### ¿Cómo escribir un mejor prompt?

* **Describe escenas concretas**: incluye sujeto, acción, entorno, iluminación y ambiente
* **Especifica el lenguaje de cámara**: como "primer plano", "toma aérea", "travelling de aproximación", "cámara lenta"
* **Describe el estilo**: como "cinematográfico", "estilo documental", "estilo animación"
* **Los modelos para chino funcionan mejor con prompts en chino**: Tongyi Wanxiang está optimizado para el chino
* **Veo admite descripciones de audio**: puedes describir el sonido en el prompt, como "canto de pájaros" o "melodía de piano"

### ¿Cómo gestionar una tarea fallida?

Cuando `status` sea `failed`, el campo `error` de la respuesta incluirá la información del error:

```json theme={null}
{
  "status": "failed",
  "error": {
    "message": "Video generation failed due to content policy violation",
    "type": "video_generation_error"
  }
}
```

## Las causas frecuentes de fallo incluyen: contenido que infringe las políticas, prompt demasiado largo, formato de imagen no admitido, etc. Ajústalo según la información del error y vuelve a intentarlo.

Última actualización: 2026-06-01