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

# Generación de vídeo

> Crea tareas de vídeo asíncronas con el protocolo nativo de AIHubMix, consulta su estado y descarga resultados.

<Note>
  [API Schema del modelo](/es/api/async-tasks#model-schema)
</Note>

## Inicio rápido

La generación de vídeo siempre es asíncrona. El ejemplo usa `wan2.6-t2v` y un entero `duration` en segundos.

<CodeGroup>
  ```bash Crear tarea theme={null}
  curl -X POST https://aihubmix.com/ai/v1/videos \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "wan2.6-t2v",
      "prompt": "Ocean waves crashing on rocky cliffs at sunset",
      "duration": 5,
      "size": "1280x720"
    }'
  ```

  ```json Respuesta de creación theme={null}
  {
    "id": "task_01K0ABCDEF",
    "object": "video",
    "model": "wan2.6-t2v",
    "status": "in_progress",
    "output": [],
    "error": null,
    "created_at": 1784707200,
    "completed_at": null,
    "expires_at": null
  }
  ```

  ```bash Consultar tarea theme={null}
  curl https://aihubmix.com/ai/v1/videos/{id} \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY"
  ```

  ```bash Descargar resultado theme={null}
  curl https://aihubmix.com/ai/v1/videos/{id}/content \
    -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
    --output result.mp4
  ```
</CodeGroup>

<h2 id="model-schema">
  Cómo descubrir modelos multimedia asíncronos y obtener sus esquemas
</h2>

El proceso de descubrimiento tiene dos pasos. Primero, obtén del catálogo público los modelos de texto a imagen o texto a video compatibles con las API asíncronas. Después, usa el `model_id` del modelo para obtener el esquema de solicitud de sus endpoints.

<h3 id="async-media-model-list">
  Listar modelos compatibles con las API asíncronas
</h3>

El catálogo de modelos usa la misma fuente de datos que Playground. Usa `type=image_generation` para los modelos de texto a imagen y `type=video` para los modelos de texto a video. Al añadir `schema_checked=true`, la lista se limita a los modelos cuyo esquema de solicitud se ha publicado y revisado.

```bash theme={null}
# Modelos de texto a imagen
curl "https://aihubmix.com/api/v1/models?type=image_generation&schema_checked=true&sort_by=order"

# Modelos de texto a video
curl "https://aihubmix.com/api/v1/models?type=video&schema_checked=true&sort_by=order"
```

Ambas solicitudes usan el mismo endpoint. El filtro `type` acepta actualmente un solo valor, por lo que debes solicitar cada tipo de modelo por separado.

La respuesta tiene la forma `{success, message, data}`. Los siguientes campos de `data` son relevantes para las integraciones multimedia asíncronas.

| Campo                     | Descripción                                                                      |
| ------------------------- | -------------------------------------------------------------------------------- |
| `data[].model_id`         | ID del modelo usado en la generación y en las solicitudes posteriores de esquema |
| `data[].model_name`       | Nombre visible del modelo                                                        |
| `data[].types`            | Tipos separados por comas; puede incluir `image_generation` y `llm`              |
| `data[].input_modalities` | Modalidades de entrada separadas por comas                                       |
| `data[].schema_checked`   | `true` cuando el esquema de solicitud se ha publicado y revisado                 |

```json theme={null}
{
  "success": true,
  "message": "",
  "data": [
    {
      "model_id": "qwen-image-2.0",
      "model_name": "Qwen Image 2.0",
      "types": "image_generation",
      "input_modalities": "text,image",
      "schema_checked": true
    }
  ]
}
```

<h3 id="single-model-schema">
  Obtener el esquema de solicitud de un modelo
</h3>

Los campos, las enumeraciones y los rangos numéricos compatibles pueden variar según el modelo. Antes de enviar una solicitud de imagen o video, usa el siguiente endpoint público para obtener los endpoints disponibles y los esquemas JSON de solicitud del modelo seleccionado.

```bash theme={null}
# Modelo de texto a imagen
curl "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints"

# Modelo de texto a video
curl "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints"
```

El valor de `modality` en la respuesta es `image` o `video`. Cada elemento del array `endpoints` describe un protocolo de llamada disponible.

| Campo                        | Descripción                                                                                                                         |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `default_endpoint`           | Identificador del endpoint predeterminado del modelo                                                                                |
| `endpoints[].endpoint`       | Identificador del endpoint                                                                                                          |
| `endpoints[].method`         | Método HTTP, como `POST`                                                                                                            |
| `endpoints[].path`           | Ruta de la solicitud                                                                                                                |
| `endpoints[].content_types`  | Tipos de contenido aceptados por el endpoint                                                                                        |
| `endpoints[].lifecycle`      | Modo síncrono o asíncrono, ruta de consulta y valores de estado                                                                     |
| `endpoints[].request.schema` | Esquema JSON completo de la solicitud para este modelo y endpoint, incluidos los campos obligatorios y las restricciones de valores |

Un modelo puede devolver endpoints `/ai/v1` y endpoints `/v1` compatibles con OpenAI. Es posible que los endpoints compatibles con OpenAI todavía no admitan los modelos más recientes, por lo que se recomienda usar primero los endpoints `/ai/v1`. Para las API de tareas asíncronas, selecciona el elemento cuyo `path` sea `/ai/v1/images/generations` o `/ai/v1/videos` y utiliza su `request.schema`. No dependas de la posición de un elemento en el array `endpoints`.

Los siguientes comandos extraen directamente el esquema de solicitud de cada endpoint de tareas asíncronas.

```bash theme={null}
# Texto a imagen
curl -s "https://aihubmix.com/call/schema/models/qwen-image-2.0/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/images/generations") | .request.schema'

# Texto a video
curl -s "https://aihubmix.com/call/schema/models/wan2.6-t2v/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'
```

El endpoint devuelve `404 model_not_found` si el modelo no existe o no tiene endpoints detectables. Devuelve `500 endpoints_unavailable` cuando los datos de los endpoints no están disponibles temporalmente.

***

<h2 id="create-async-video">
  Cómo crear tareas de video
</h2>

Las solicitudes de video siempre son asíncronas y no admiten cambiar a una espera síncrona mediante `Prefer: wait`. El protocolo estándar usa el entero `duration` para indicar la cantidad de segundos:

```bash theme={null}
curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "Ocean waves crashing on rocky cliffs at sunset",
    "duration": 5,
    "size": "1280x720"
  }'
```

<h3 id="video-parameters">
  Campos estándar de video
</h3>

| Campo                   | Tipo         | Obligatorio | Descripción                                                         |
| ----------------------- | ------------ | ----------- | ------------------------------------------------------------------- |
| `model`                 | string       | Sí          | Nombre del modelo                                                   |
| `prompt`                | string       | Sí          | Descripción del video; no puede estar vacía                         |
| `duration`              | integer/null | No          | Duración del video en segundos; el rango depende del modelo         |
| `aspect_ratio`          | string/null  | No          | Relación de aspecto; valor predeterminado del protocolo `16:9`      |
| `resolution`            | string/null  | No          | `480p`, `720p`, `1080p`, `1K`, `2K` o `4K`                          |
| `size`                  | string/null  | No          | `{width}x{height}`; puede sustituir a `resolution` y `aspect_ratio` |
| `seed`                  | integer/null | No          | Semilla aleatoria                                                   |
| `input_references`      | array/null   | No          | Recursos de referencia de imagen, video o audio                     |
| `frame_images`          | array/null   | No          | Imágenes del primer o último fotograma                              |
| `generate_audio`        | boolean/null | No          | Indica si se genera una pista de audio                              |
| `webhook_url`           | string       | No          | URL HTTPS de devolución de llamada, hasta 512 caracteres            |
| `webhook_events_filter` | string\[]    | No          | Subconjunto no vacío de `completed`, `failed` y `cancelled`         |
| `extra`                 | object/null  | No          | Parámetros de extensión específicos del modelo                      |

Estructura de un elemento de `input_references`:

```json theme={null}
{
  "type": "image_url",
  "url": "https://example.com/reference.png"
}
```

`type` puede ser `image_url`, `video_url` o `audio_url`.

Estructura de un elemento de `frame_images`:

```json theme={null}
{
  "frame_type": "first_frame",
  "image_url": {
    "url": "https://example.com/first-frame.png"
  }
}
```

`frame_type` puede ser `first_frame` o `last_frame`.

***

<h2 id="task-object">
  Objeto de tarea multimedia
</h2>

Los endpoints específicos de imagen y video devuelven la siguiente estructura:

```json theme={null}
{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/videos/task_01K0ABCDEF/content"
    }
  ],
  "error": null,
  "created_at": 1784707200,
  "completed_at": 1784707320,
  "expires_at": null
}
```

| Campo          | Tipo         | Descripción                                                                 |
| -------------- | ------------ | --------------------------------------------------------------------------- |
| `id`           | string       | ID de tarea de la plataforma                                                |
| `object`       | string       | `image` o `video`                                                           |
| `model`        | string       | Nombre del modelo                                                           |
| `status`       | string       | Estado actual de la tarea                                                   |
| `output`       | array        | Resultados generados; matriz vacía cuando aún no hay resultados             |
| `error`        | object/null  | Información del error; puede contener `code`, `message` y `upstream_detail` |
| `created_at`   | integer      | Hora de creación en segundos Unix                                           |
| `completed_at` | integer/null | Hora del estado final en segundos Unix                                      |
| `expires_at`   | null         | Los endpoints multimedia específicos devuelven actualmente `null`           |

Elemento `output` multimedia:

| Campo         | Tipo        | Descripción                              |
| ------------- | ----------- | ---------------------------------------- |
| `index`       | integer     | Orden del resultado, desde `0`           |
| `type`        | string      | Actualmente `file`                       |
| `content_url` | string/null | URL de descarga del resultado            |
| `b64_json`    | string/null | Resultado de imagen codificado en Base64 |

<h3 id="task-status">
  Estados de tarea
</h3>

| Estado        | Final | Descripción                                                  |
| ------------- | ----- | ------------------------------------------------------------ |
| `pending`     | No    | La plataforma ha recibido la tarea y espera su ejecución     |
| `in_progress` | No    | La tarea se está ejecutando                                  |
| `completed`   | Sí    | La tarea ha terminado y se puede leer `output`               |
| `failed`      | Sí    | La tarea ha fallado; consulta `error` para conocer el motivo |
| `cancelled`   | Sí    | La tarea se ha cancelado                                     |

Los clientes pueden consultar el estado cada 15 segundos hasta que cambie a `completed`, `failed` o `cancelled`. Los 15 segundos son una recomendación de sondeo para el cliente, no un límite del protocolo del servidor.

***

<h2 id="query-tasks">
  Cómo consultar tareas multimedia
</h2>

<h3 id="query-task-detail">
  Consultar detalles multimedia
</h3>

```bash theme={null}
# Imagen
curl https://aihubmix.com/ai/v1/images/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# Video
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

Los endpoints de detalles multimedia pueden devolver un estado actualizado de la tarea. Por ello, el sondeo multimedia debe usar el endpoint de detalles de imagen o video correspondiente.

<h3 id="query-task-list">
  Consultar la lista de tareas multimedia
</h3>

Si se pierde la respuesta de creación, puedes recuperar el ID de la tarea mediante la lista multimedia correspondiente:

```bash theme={null}
curl "https://aihubmix.com/ai/v1/videos?limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

| Parámetro | Tipo    | Predeterminado | Descripción                                                            |
| --------- | ------- | -------------- | ---------------------------------------------------------------------- |
| `after`   | string  | -              | Cursor de paginación; usa `next_after` de la página anterior           |
| `limit`   | integer | `20`           | Cantidad por página, máximo `100`                                      |
| `order`   | string  | `desc`         | `asc` para orden ascendente; los demás valores se procesan como `desc` |

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "task_01K0ABCDEF",
      "object": "video",
      "model": "wan2.6-t2v",
      "status": "in_progress",
      "output": [],
      "error": null,
      "created_at": 1784707200,
      "completed_at": null,
      "expires_at": null
    }
  ],
  "has_more": true,
  "next_after": "task_01K0ABCDEF"
}
```

Las listas multimedia devuelven instantáneas de las tareas en el momento de la consulta y no actualizan activamente su estado.

***

<h2 id="unified-tasks">
  Cómo usar el endpoint de tareas unificadas
</h2>

El endpoint de tareas unificadas admite los siguientes filtros:

```bash theme={null}
curl "https://aihubmix.com/ai/v1/tasks?object=video&status=in_progress&limit=20&order=desc" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

| Parámetro | Tipo    | Predeterminado | Descripción                                                   |
| --------- | ------- | -------------- | ------------------------------------------------------------- |
| `object`  | string  | -              | `llm`, `image` o `video`                                      |
| `status`  | string  | -              | `pending`, `in_progress`, `completed`, `failed` o `cancelled` |
| `model`   | string  | -              | Filtro exacto por nombre de modelo                            |
| `after`   | string  | -              | Cursor de paginación                                          |
| `limit`   | integer | `20`           | Rango de `1` a `100`                                          |
| `order`   | string  | `desc`         | `asc` o `desc`                                                |

Detalles de una tarea unificada:

```bash theme={null}
curl https://aihubmix.com/ai/v1/tasks/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"
```

Elemento `output` unificado de una tarea multimedia:

```json theme={null}
{
  "index": 0,
  "result_id": "result_01K0XYZ",
  "type": "file",
  "content_type": "video/mp4",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
}
```

Para una tarea de un solo artefacto, solicita directamente `/ai/v1/tasks/{id}/content`. Para una tarea con varios artefactos, solicita `/ai/v1/tasks/{id}/content/{result_id}`. Si no se especifica el ID del resultado, se devuelve `400 result_id_required`.

<Note>
  Los endpoints de lista, detalles y contenido de tareas unificadas están
  aislados por el Bearer Token usado para crear la tarea. Otras API Keys de la
  misma cuenta no pueden leerla.
</Note>

***

<h2 id="get-task-results">
  Cómo descargar resultados multimedia
</h2>

<h3 id="single-artifact">
  Descargar videos
</h3>

```bash theme={null}
curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4
```

<Warning>
  Los resultados pueden caducar y puede haber límites de descarga. Un resultado
  caducado devuelve `410 artifact_expired`; superar el límite de descargas
  devuelve `429 too_many_downloads`.
</Warning>

***

<h2 id="webhooks">
  Cómo usar Webhooks
</h2>

Las imágenes y los videos asíncronos admiten Webhooks a nivel de tarea:

```bash theme={null}
curl -X POST https://aihubmix.com/ai/v1/videos \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A tranquil garden at sunrise",
    "duration": 5,
    "size": "1280x720",
    "webhook_url": "https://example.com/webhooks/aihubmix",
    "webhook_events_filter": ["completed", "failed"]
  }'
```

`webhook_url` admite hasta 512 caracteres y no puede apuntar a localhost, redes privadas ni otras direcciones restringidas. Cuando se omite `webhook_events_filter`, la plataforma envía `completed`, `failed` y `cancelled`. Cuando se proporciona explícitamente, la matriz no puede estar vacía ni contener duplicados, y debe usarse junto con `webhook_url`.

Cuando la solicitud no incluye `webhook_url`, las imágenes y los videos asíncronos intentan usar la URL de devolución de llamada predeterminada configurada en la cuenta. Una URL predeterminada no válida se ignora y no impide la creación de la tarea.

<h3 id="webhook-payload">
  Solicitud de devolución de llamada
</h3>

```json theme={null}
{
  "event_id": "evt_01K0ABCDEF",
  "event_type": "completed",
  "created_at": "2026-08-12T12:00:00Z",
  "data": {
    "task_id": "task_01K0ABCDEF",
    "status": "completed",
    "model": "wan2.6-t2v",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content"
      }
    ]
  }
}
```

| Campo                | Descripción                                                         |
| -------------------- | ------------------------------------------------------------------- |
| `event_id`           | ID del evento de devolución de llamada, usado para la deduplicación |
| `event_type`         | `completed`, `failed` o `cancelled`                                 |
| `created_at`         | Hora del evento en formato RFC 3339                                 |
| `data.task_id`       | ID de tarea de la plataforma                                        |
| `data.status`        | Estado final actual                                                 |
| `data.model`         | Nombre del modelo                                                   |
| `data.results[].url` | URL de descarga del resultado, si está disponible al finalizar      |
| `data.error`         | Información del error, si está disponible cuando falla              |

`results` solo aparece cuando los resultados se han archivado. Las descargas siguen requiriendo un Bearer Token.

<h3 id="webhook-retry">
  Reintentos y deduplicación
</h3>

La plataforma usa una entrega al menos una vez, por lo que el mismo evento puede entregarse más de una vez:

* HTTP `2xx` indica que se recibió correctamente.
* HTTP `5xx`, los errores de red o los tiempos de espera agotados activan un reintento.
* HTTP `3xx` y `4xx` no se vuelven a intentar.
* Se realizan hasta 6 intentos de entrega, con intervalos de 1, 4, 16, 64 y 256 segundos.

El receptor debe guardar `event_id` y devolver `2xx` inmediatamente cuando vuelva a recibir el mismo evento.

<Warning>
  Los Webhooks a nivel de tarea no incluyen una clave de firma independiente. Si
  se requiere verificar la firma, configura una suscripción de Webhook a nivel
  de cuenta y conserva la consulta de detalles de la tarea como método para
  confirmar los resultados.
</Warning>

***

<h2 id="error-codes">
  Respuestas y códigos de error
</h2>

```json theme={null}
{
  "error": {
    "message": "Task not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0ABCDEF"
  }
}
```

| Estado HTTP | Código de error                 | Descripción                                                                                |
| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------ |
| 400         | `invalid_request`               | El tipo o el valor de un parámetro no es correcto                                          |
| 400         | `result_id_required`            | La tarea unificada tiene varios resultados, pero no se especificó `result_id` al descargar |
| 400         | `webhook_invalid`               | La URL del Webhook no es válida o el filtro no tiene URL                                   |
| 400         | `webhook_events_filter_invalid` | La lista de eventos de Webhook no es válida                                                |
| 401         | `authentication_failed`         | Falta la API Key o no es válida                                                            |
| 403         | `async_not_enabled`             | Las tareas asíncronas no están activadas para la cuenta                                    |
| 404         | `task_not_found`                | La tarea o el cursor de paginación no existe                                               |
| 404         | `result_not_found`              | El resultado no existe o no se puede descargar actualmente                                 |
| 410         | `artifact_expired`              | El resultado ha caducado                                                                   |
| 413         | `request_too_large`             | El cuerpo de la solicitud supera los 32 MiB                                                |
| 429         | `too_many_downloads`            | Se ha superado el límite de descargas del resultado                                        |
| 503         | `async_unavailable`             | El servicio de imágenes asíncronas no está disponible temporalmente                        |

`error.tid` es el ID de seguimiento de la solicitud. Inclúyelo cuando contactes con el soporte técnico para investigar un problema.

***

## Ejemplo completo

Estos ejemplos crean una tarea, la consultan y descargan el resultado MP4.

<CodeGroup>
  ```python Python theme={null}
  import os
  import time

  import requests

  base_url = "https://aihubmix.com"
  headers = {
      "Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}",
      "Content-Type": "application/json",
  }

  response = requests.post(
      f"{base_url}/ai/v1/videos",
      headers=headers,
      json={
          "model": "wan2.6-t2v",
          "prompt": "A cat playing jazz on a piano",
          "duration": 5,
          "size": "1280x720",
      },
      timeout=60,
  )
  response.raise_for_status()
  task = response.json()

  while task["status"] not in {"completed", "failed", "cancelled"}:
      time.sleep(15)
      response = requests.get(
          f"{base_url}/ai/v1/videos/{task['id']}",
          headers=headers,
          timeout=30,
      )
      response.raise_for_status()
      task = response.json()

  if task["status"] == "completed":
      result = requests.get(
          f"{base_url}/ai/v1/videos/{task['id']}/content",
          headers=headers,
          timeout=120,
      )
      result.raise_for_status()
      with open("result.mp4", "wb") as file:
          file.write(result.content)
  else:
      raise RuntimeError(task.get("error") or task["status"])
  ```

  ```typescript TypeScript theme={null}
  import { writeFile } from "node:fs/promises";

  const baseUrl = "https://aihubmix.com";
  const headers = {
    Authorization: `Bearer ${process.env.AIHUBMIX_API_KEY}`,
    "Content-Type": "application/json",
  };

  const created = await fetch(`${baseUrl}/ai/v1/videos`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      model: "wan2.6-t2v",
      prompt: "A cat playing jazz on a piano",
      duration: 5,
      size: "1280x720",
    }),
  });
  if (!created.ok) throw new Error(await created.text());
  let task = await created.json();

  const finished = new Set(["completed", "failed", "cancelled"]);
  while (!finished.has(task.status)) {
    await new Promise((resolve) => setTimeout(resolve, 15_000));
    const polled = await fetch(`${baseUrl}/ai/v1/videos/${task.id}`, { headers });
    if (!polled.ok) throw new Error(await polled.text());
    task = await polled.json();
  }

  if (task.status === "completed") {
    const result = await fetch(`${baseUrl}/ai/v1/videos/${task.id}/content`, {
      headers,
    });
    if (!result.ok) throw new Error(await result.text());
    await writeFile("result.mp4", Buffer.from(await result.arrayBuffer()));
  } else {
    throw new Error(JSON.stringify(task.error ?? task.status));
  }
  ```
</CodeGroup>