Generación de vídeo

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.

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"
  }'

{
  "id": "task_01K0ABCDEF",
  "object": "video",
  "model": "wan2.6-t2v",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

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

curl https://aihubmix.com/ai/v1/videos/{id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

Cómo descubrir modelos multimedia asíncronos y obtener sus esquemas

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.

Listar modelos compatibles con las API asíncronas

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.

# 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

{
  "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
    }
  ]
}

Obtener el esquema de solicitud de un modelo

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.

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

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

Cómo crear tareas de video

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:

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"
  }'

Campos estándar de video

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:

{
  "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:

{
  "frame_type": "first_frame",
  "image_url": {
    "url": "https://example.com/first-frame.png"
  }
}

frame_type puede ser first_frame o last_frame.

Objeto de tarea multimedia

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

{
  "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

Estados de tarea

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.

Cómo consultar tareas multimedia

Consultar detalles multimedia

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

Consultar la lista de tareas multimedia

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

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`

{
  "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.

Cómo usar el endpoint de tareas unificadas

El endpoint de tareas unificadas admite los siguientes filtros:

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:

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

Elemento output unificado de una tarea multimedia:

{
  "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.

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.

Cómo descargar resultados multimedia

Descargar videos

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

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.

Cómo usar Webhooks

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

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.

Solicitud de devolución de llamada

{
  "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.

Reintentos y deduplicación

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.

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.

Respuestas y códigos de error

{
  "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.

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"])

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));
}

Empezar

Funciones de gateway

Capacidades del modelo

Referencia de protocolo

Gestión de plataforma

Privacidad y términos

Generación de vídeo

Inicio rápido

Cómo descubrir modelos multimedia asíncronos y obtener sus esquemas

Listar modelos compatibles con las API asíncronas

Obtener el esquema de solicitud de un modelo

Cómo crear tareas de video

Campos estándar de video

Objeto de tarea multimedia

Estados de tarea

Cómo consultar tareas multimedia

Consultar detalles multimedia

Consultar la lista de tareas multimedia

Cómo usar el endpoint de tareas unificadas

Cómo descargar resultados multimedia

Descargar videos

Cómo usar Webhooks

Solicitud de devolución de llamada

Reintentos y deduplicación

Respuestas y códigos de error

Ejemplo completo

​Inicio rápido

​Cómo descubrir modelos multimedia asíncronos y obtener sus esquemas

​Listar modelos compatibles con las API asíncronas

​Obtener el esquema de solicitud de un modelo

​Cómo crear tareas de video

​Campos estándar de video

​Objeto de tarea multimedia

​Estados de tarea

​Cómo consultar tareas multimedia

​Consultar detalles multimedia

​Consultar la lista de tareas multimedia

​Cómo usar el endpoint de tareas unificadas

​Cómo descargar resultados multimedia

​Descargar videos

​Cómo usar Webhooks

​Solicitud de devolución de llamada

​Reintentos y deduplicación

​Respuestas y códigos de error

​Ejemplo completo

Inicio rápido

Cómo descubrir modelos multimedia asíncronos y obtener sus esquemas

Listar modelos compatibles con las API asíncronas

Obtener el esquema de solicitud de un modelo

Cómo crear tareas de video

Campos estándar de video

Objeto de tarea multimedia

Estados de tarea

Cómo consultar tareas multimedia

Consultar detalles multimedia

Consultar la lista de tareas multimedia

Cómo usar el endpoint de tareas unificadas

Cómo descargar resultados multimedia

Descargar videos

Cómo usar Webhooks

Solicitud de devolución de llamada

Reintentos y deduplicación

Respuestas y códigos de error

Ejemplo completo