Tareas asíncronas

AIHubMix ofrece tres grupos de endpoints de tareas: /ai/v1/images para imágenes, /ai/v1/videos para videos y /ai/v1/tasks para registros unificados de tareas.

La generación de imágenes es síncrona de forma predeterminada y se ejecuta de forma asíncrona al enviar async: true.
La generación de videos siempre es asíncrona.
Los endpoints de detalles de imágenes y videos permiten obtener el estado más reciente de las tareas multimedia.
/ai/v1/tasks proporciona una vista unificada y de solo lectura de las tareas de imagen, video y LLM.

Si un video de Doubao Seedance necesita referencias a recursos de personas reales, completa la confirmación de la propia persona y prepara los recursos siguiendo la guía de recursos de personas reales de Doubao antes de crear la tarea de video.

Tutorial en video: tareas asíncronas

Explica el funcionamiento general de las tareas asíncronas y muestra un flujo completo de generación asíncrona de imágenes.

Activa las tareas asíncronas en la consola

Antes de usar los endpoints de tareas multimedia de /ai/v1, activa las tareas asíncronas para la cuenta actual.

Si las tareas asíncronas no están activadas, las solicitudes de creación de tareas de imagen y video devuelven 403 async_not_enabled.

Inicio rápido

El siguiente ejemplo usa wan2.6-t2v para crear un video. Este modelo acepta duration y size; los campos válidos pueden variar según el modelo.

# 1. Crear una tarea de video y guardar el id de la respuesta
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 cat playing jazz on a piano, warm lighting, cinematic shot",
    "duration": 5,
    "size": "1280x720"
  }'

# 2. Consultar los detalles multimedia cada 15 segundos
curl https://aihubmix.com/ai/v1/videos/{task_id} \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

# 3. Descargar el video cuando el estado sea completed
curl https://aihubmix.com/ai/v1/videos/{task_id}/content \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.mp4

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

Cómo elegir entre los tres grupos de endpoints

Caso de uso	Método	Ruta	Comportamiento
Generar imágenes	POST	`/ai/v1/images/generations`	Síncrono de forma predeterminada; puede cambiarse a asíncrono con `async: true`
Consultar detalles de una imagen	GET	`/ai/v1/images/{id}`	Devuelve el estado de la tarea de imagen; consultar una tarea activa puede actualizar su estado
Consultar la lista de imágenes	GET	`/ai/v1/images`	Devuelve instantáneas de las tareas de imagen
Descargar una imagen específica	GET	`/ai/v1/images/{id}/content/{result_id}`	Descarga un resultado específico de una tarea con varias imágenes
Crear un video	POST	`/ai/v1/videos`	Siempre asíncrono
Consultar detalles de un video	GET	`/ai/v1/videos/{id}`	Devuelve el estado de la tarea de video; consultar una tarea activa puede actualizar su estado
Consultar la lista de videos	GET	`/ai/v1/videos`	Devuelve instantáneas de las tareas de video
Descargar un video	GET	`/ai/v1/videos/{id}/content`	Descarga el resultado de video principal de la tarea
Listar modelos multimedia asíncronos	GET	`/api/v1/models?type={type}&schema_checked=true`	Devuelve modelos de texto a imagen o texto a video con esquema de solicitud
Obtener el esquema de solicitud de un modelo	GET	`/call/schema/models/{model}/endpoints`	Devuelve endpoints de texto a imagen o texto a video y sus esquemas JSON
Consultar la lista unificada de tareas	GET	`/ai/v1/tasks`	Consulta de solo lectura de tareas de imagen, video y LLM
Consultar detalles de una tarea unificada	GET	`/ai/v1/tasks/{id}`	Devuelve una instantánea de solo lectura de la tarea en el momento de la consulta
Obtener el resultado de una tarea unificada	GET	`/ai/v1/tasks/{id}/content`	Descarga un artefacto único o lee una respuesta LLM archivada
Obtener un resultado específico de una tarea unificada	GET	`/ai/v1/tasks/{id}/content/{result_id}`	Descarga un resultado específico de una tarea con varios artefactos

La URL base es https://aihubmix.com. La autenticación usa un Bearer Token:

Authorization: Bearer $AIHUBMIX_API_KEY

Los endpoints de lista de modelos y de esquema de modelos son públicos y no requieren Bearer Token. Los demás endpoints requieren autenticación.

/ai/v1/tasks no ofrece un endpoint de creación. Las imágenes y los videos deben crearse mediante los endpoints de generación multimedia correspondientes. La plataforma guarda automáticamente las tareas de recuperación de LLM después de una interrupción del cliente.

Diferencias entre los endpoints multimedia y los de tareas unificadas

Los endpoints de detalles multimedia y los endpoints de tareas unificadas devuelven los mismos campos de nivel superior, pero los elementos de output y el comportamiento de consulta son distintos:

Comparación	Detalles multimedia `/images/{id}`, `/videos/{id}`	Detalles de tarea unificada `/tasks/{id}`
Tipos de tarea	Imagen o video	Imagen, video o LLM
Comportamiento de consulta	Consultar una tarea activa puede actualizar su estado	Devuelve una instantánea de solo lectura en el momento de la consulta
Campos de salida multimedia	`index`, `type`, `content_url`, `b64_json`	`index`, `result_id`, `type`, `content_type`, `content_url`
Campos de salida LLM	No aplicable	`index`, `type=response`, `content_type`, `content_url`, `truncated`
Alcance de acceso	Tareas multimedia correspondientes creadas por la cuenta actual	Tareas creadas con el Bearer Token actual

Por lo tanto, usa el endpoint de detalles de imagen o video para sondear el estado de generación multimedia. Usa /ai/v1/tasks para filtrar tareas de forma unificada, leer metadatos de resultados o recuperar respuestas LLM.

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.

Modelos y campos compatibles

Los protocolos de imagen y video definen campos estándar entre modelos, pero cada modelo restringe los campos, las enumeraciones y los rangos numéricos según sus capacidades. Antes de realizar una solicitud, obtén las restricciones actuales del modelo desde el endpoint de esquema del modelo. Por ejemplo:

wan2.6-t2v admite duration, size y seed. No acepta resolution, aspect_ratio, frame_images, input_references ni generate_audio.
qwen-image-2.0 admite n, size, seed, negative_prompt, image e images. No acepta aspect_ratio ni mask.

El conjunto de campos estándar no implica que todos los modelos admitan todos los campos. Si se envía un campo no compatible con el modelo actual, se devuelve un error de parámetros.

Modelos para la recuperación de LLM tras una interrupción

Actualmente se admiten los siguientes modelos:

gpt-5.6-sol
gpt-5.5-pro
gpt-5.4-pro
gpt-5.2-pro
claude-fable-5
claude-opus-5

El alcance de compatibilidad puede cambiar. Consulta la lista de esta página. Para usar la recuperación tras una interrupción, la cuenta actual también debe tener activadas las tareas asíncronas. Si alguna condición no se cumple, la solicitud LLM original sigue ejecutándose con normalidad, pero no se guarda una tarea de recuperación después de que el cliente se desconecte.

Cómo crear tareas de imagen

Imágenes síncronas

Cuando se omite async o se establece en false, el endpoint espera a que finalice la generación y devuelve un objeto de tarea:

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

Las tareas de imagen síncronas también guardan un registro de tarea. Si se interrumpe la conexión del cliente o se pierde la respuesta de creación, usa GET /ai/v1/images para encontrar la tarea correspondiente.

Imágenes asíncronas

Cuando async se establece en el valor booleano true, el endpoint devuelve inmediatamente un objeto de tarea y la generación continúa en segundo plano:

curl -X POST https://aihubmix.com/ai/v1/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
    "n": 2,
    "size": "1024x1024",
    "async": true
  }'

Usa GET /ai/v1/images/{id} para consultar una tarea de imagen asíncrona. Cuando termine, solicita directamente el content_url de cada elemento de output; esta URL ya contiene el result_id de la imagen correspondiente.

async en una solicitud de imagen debe ser un valor booleano. webhook_url y webhook_events_filter solo pueden usarse con async: true.

Campos estándar de imagen

Campo	Tipo	Obligatorio	Descripción
`model`	string	Sí	Nombre del modelo
`prompt`	string	Sí	Descripción de la imagen; no puede estar vacía
`n`	integer/null	No	Número de imágenes, mínimo `1`, predeterminado `1`
`size`	string/null	No	`{width}x{height}`, por ejemplo `1024x1024`
`aspect_ratio`	string/null	No	Relación de aspecto; excluyente con `size`
`seed`	integer/null	No	Semilla aleatoria
`negative_prompt`	string/null	No	Prompt negativo
`image`	string/object	No	Una imagen de entrada como URL, Data URI, Base64 u objeto `{url}`
`images`	array/null	No	Varias imágenes de entrada
`mask`	string/object	No	Máscara para editar imágenes
`output_format`	string/null	No	`png`, `jpeg` o `webp`; predeterminado `png`
`response_format`	string/null	No	`url` o `b64_json`; predeterminado `url`
`async`	boolean	No	Establécelo en `true` para la ejecución asíncrona
`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

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 imágenes

Cuando termine la tarea de imagen, solicita cada output[].content_url del objeto de tarea multimedia:

curl "{content_url}" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  --output result.png

La ruta de descarga multimedia de imágenes es /ai/v1/images/{id}/content/{result_id}. El objeto de tarea multimedia no expone result_id por separado, por lo que el cliente puede usar directamente content_url. Cuando b64_json no esté vacío, puede descodificarse directamente desde Base64.

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.

Cómo funciona la recuperación de LLM tras una interrupción

La recuperación de LLM tras una interrupción permite obtener la respuesta final después de que el cliente se desconecte. El método de solicitud, el comportamiento de streaming y el formato de respuesta permanecen sin cambios. Tampoco se devuelve un ID de tarea por anticipado al iniciar la solicitud. Deben cumplirse todas las condiciones siguientes:

Condición	Descripción
Las tareas asíncronas están activadas para la cuenta	Activa la función para la cuenta actual en la consola de AIHubMix
El modelo admite recuperación tras interrupciones	El modelo actual figura en la lista de Modelos para la recuperación de LLM tras una interrupción
El endpoint es compatible	Chat Completions, Anthropic Messages, Responses API o Gemini `generateContent` / `streamGenerateContent`
El cliente se interrumpe	El cliente cancela, la red se desconecta o el invocador cancela la solicitud

La plataforma solo crea una tarea de recuperación y guarda el JSON o SSE final cuando detecta que la respuesta no se ha entregado por completo y que el cliente se ha desconectado. Las solicitudes LLM que terminan con normalidad y se entregan por completo al cliente no crean tareas de recuperación. Los encabezados de respuesta LLM contienen X-Aihubmix-Request-Id. El cliente debe guardar este valor lo antes posible para localizar la solicitud correspondiente en la consola. La API pública de tareas no permite actualmente filtrar por ID de solicitud; las tareas LLM recientes pueden consultarse por modelo y hora de creación:

curl "https://aihubmix.com/ai/v1/tasks?object=llm&model={model}&order=desc&limit=20" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY"

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

El elemento output unificado de una tarea LLM contiene type=response, content_type, content_url y truncated. GET /ai/v1/tasks/{id}/content devuelve el JSON o SSE original guardado.

Las tareas de recuperación de LLM tras una interrupción no envían actualmente Webhooks a nivel de tarea. Una interrupción del cliente no detiene el procesamiento de la solicitud por parte de la plataforma y la llamada se sigue facturando según las reglas del endpoint original.

Respuestas y códigos de error

Esta sección se aplica a /ai/v1/images/*, /ai/v1/videos/* y a las tareas multimedia con object=image u object=video en /ai/v1/tasks/*. El cliente debe gestionar tanto las respuestas HTTP distintas de 2xx como el estado terminal HTTP 200 con status=failed.

{
  "error": {
    "message": "Task not found.",
    "type": "invalid_request_error",
    "code": "task_not_found",
    "tid": "req_01K0ABCDEF"
  }
}

Enviar comentarios sobre errores HTTP 5xx

Si la solicitud devuelve HTTP 5xx, envía comentarios e incluye error.tid.

Errores HTTP distintos de 2xx

Las filas invalid_request y schema_violation muestran mensajes de respaldo. Cuando el servicio puede identificar un campo o una restricción, devuelve un message dinámico; el cliente debe usar code para clasificar el error y no comparar message con un texto fijo.

HTTP	`code`	`message`	Descripción
400	`invalid_request`	`Invalid request. Check the request body and parameters.` (mensaje de respaldo; el mensaje real puede ser dinámico)	El cuerpo común, los tipos de campo o los parámetros de listado no son válidos; el `message` de este `code` no es fijo y puede incluir detalles dinámicos cuando se conoce el campo.
400	`model_not_found`	`The requested model is not available. Check the model name and your account access.`	El modelo no existe, no está disponible o la cuenta no tiene acceso.
400	`schema_violation`	`Invalid request: one or more parameters are invalid.` (mensaje de respaldo; el mensaje real puede ser dinámico)	La solicitud no cumple el Schema de parámetros del modelo; el `message` de este `code` no es fijo y puede identificar dinámicamente el campo o la restricción.
400	`capability_not_supported`	`The requested parameters are not supported for this model.`	El modelo no admite un campo, una cantidad o un límite solicitado.
400	`media_form_unsupported`	Mensaje multimedia dinámico; consulta la tabla siguiente.	No se puede procesar el formato, los datos, la URL o el tamaño de una imagen, un video, una referencia o un fotograma inicial/final.
400	`result_id_required`	`This task has multiple results. Specify result_id.`	La tarea tiene varios resultados y la descarga no especificó `result_id`.
400	`upstream_rejected`	`Upstream service rejected the request.`	El proveedor de modelos rechazó la solicitud de creación.
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	Falta la API Key o no es válida.
402	`insufficient_quota`	`Insufficient quota.`	La cuenta de AIHubMix no tiene saldo disponible suficiente.
403	`permission_denied`	`You do not have permission to access this resource.`	La cuenta, la API Key o el origen de acceso no tienen permiso para usar el recurso.
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to <console-url>/async-tasks to activate.`	La cuenta no tiene activadas las tareas asíncronas; la URL de la consola depende del sitio de la solicitud.
404	`task_not_found`	`Task not found.`	La tarea no existe, el cursor de paginación no es válido o la cuenta no puede verla.
404	`result_not_found`	`Result not found.`	El resultado no existe, aún no está listo, el ID no coincide o la cuenta no puede descargarlo.
410	`artifact_expired`	`The result has expired.`	El resultado superó su período de conservación.
413	`request_too_large`	`Request body is too large. Reduce the request size and try again.`	El cuerpo completo de la solicitud supera los 32 MiB.
413	`image_too_large`	`Image is too large. Reduce the image size and try again.`	Una imagen decodificada de la interfaz de imágenes supera el límite de procesamiento del modelo.
422	`image_not_generated`	`The expected image was not generated.`	El proveedor de modelos completó la solicitud, pero no devolvió una imagen utilizable.
429	`rate_limited`	`Too many requests. Please slow down and retry.`	AIHubMix limita la frecuencia de la cuenta o de la API Key.
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	El proveedor de modelos devolvió un error de límite de frecuencia.
429	`too_many_downloads`	`Download limit exceeded for this result.`	El resultado alcanzó su límite de descargas.
500	`internal_error`	`Internal error. Please retry.`	Se produjo un error interno que el cliente no puede corregir.
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	No fue posible conectar con el proveedor de modelos o leer por completo su respuesta.
502	`upstream_bad_response`	`Upstream service returned an invalid response.`	El proveedor de modelos devolvió una respuesta que la plataforma no pudo procesar.
502	`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	El proveedor de modelos devolvió un error de servicio.
503	`model_unavailable`	`The requested model is temporarily unavailable.`	El modelo seleccionado no está disponible temporalmente.
503	`service_unavailable`	`Service is temporarily unavailable. Please retry.`	El servicio de consulta, descarga o resultados no está disponible temporalmente.
504	`sync_timeout`	`Generation timed out. Please retry.`	La generación síncrona no terminó dentro del tiempo de espera.

El message de media_form_unsupported se genera a partir de una causa confirmada:

Caso	`message`
Formato no admitido	`Unsupported <media-kind> format: <detected-format>. Supported formats for this model: <allowed-formats>.`
Datos de imagen o video no válidos	`The <media-kind> data is invalid. Provide a valid <media-kind>.`
Datos no válidos sin un tipo multimedia determinado	`The media data is invalid. Provide valid media data.`
URL multimedia inaccesible	`The <media-kind> URL could not be accessed. Make sure it is publicly accessible and returns a valid <media-kind>.`
No se puede decodificar el contenido	`Unable to process the <media-kind>. Check that the <media-kind> data or URL is valid and supported.`
Contenido demasiado grande en una tarea que no es de imagen	`The <media-kind> is too large. Reduce the <media-kind> size and try again.`
No se puede determinar una causa segura	`Unable to process the media. Check that the media data or URL is valid and supported.`

Por ejemplo, si un modelo admite PNG, JPEG, WebP, HEIC y HEIF, una imagen GIF devuelve:

Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF.

HTTP 200 + Task con `status=failed`

Una consulta correcta no implica que la generación haya terminado correctamente. Cuando la tarea tiene status=failed, el cliente obtiene la causa de error.code y error.message:

{
  "id": "task_01K0ABCDEF",
  "status": "failed",
  "error": {
    "code": "media_form_unsupported",
    "message": "Unsupported image format: GIF. Supported formats for this model: PNG, JPEG, WebP, HEIC, and HEIF."
  }
}

Task `code`	`message`	Descripción
`media_form_unsupported`	Mensaje multimedia dinámico, como se indicó antes.	Error de formato, datos, URL, decodificación o tamaño del contenido multimedia de una tarea asíncrona.
`image_too_large`	`Image is too large. Reduce the image size and try again.`	La imagen de entrada de una tarea asíncrona supera el límite.
`image_not_generated`	`The expected image was not generated.`	El proveedor de modelos no devolvió una imagen utilizable.
`upstream_rejected`	`Upstream service rejected the request.`	El proveedor de modelos rechazó la creación de la tarea.
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	El proveedor de modelos limitó la frecuencia de solicitudes.
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	No fue posible conectar con el proveedor de modelos al crear la tarea o leer por completo su respuesta.
`upstream_bad_response`	`Upstream service returned an invalid response.`	No fue posible procesar la respuesta del proveedor de modelos.
`upstream_error`	`Upstream service is temporarily unavailable. Please retry.`	El proveedor de modelos no pudo crear o ejecutar la tarea.
`upstream_empty_output`	`The upstream service completed without producing a usable result. Please retry.`	El proveedor de modelos terminó sin producir un resultado utilizable.
`output_policy_violation`	`Generated content was rejected by the content policy.`	El contenido generado fue rechazado por la política de contenido.
`sync_timeout`	`Generation timed out. Please retry.`	Se agotó el tiempo de espera de la generación.
`internal_error`	`Internal error. Please retry.`	Se produjo un error interno al procesar la tarea asíncrona.

Ejemplo completo de video

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

Preguntas frecuentes

¿Las tareas multimedia deben consultarse mediante /ai/v1/tasks/{id} o mediante el endpoint de detalles multimedia? Usa el endpoint de detalles multimedia para sondear el estado de generación: /ai/v1/images/{id} para imágenes y /ai/v1/videos/{id} para videos. /ai/v1/tasks/{id} devuelve una instantánea de solo lectura. ¿Por qué seconds en una solicitud de video devuelve un error de parámetros? El protocolo estándar de /ai/v1/videos usa el entero duration, expresado en segundos. Los valores permitidos dependen de los parámetros compatibles con el modelo correspondiente. ¿Por qué resolution devuelve un error de parámetros con algunos modelos de video? El protocolo de video estándar incluye resolution y size, pero cada modelo restringe los campos. Por ejemplo, wan2.6-t2v usa size y no acepta resolution. ¿Cómo se recupera una tarea multimedia si se pierde la respuesta de creación? Solicita GET /ai/v1/images para imágenes o GET /ai/v1/videos para videos. Las listas admiten los parámetros de paginación after, limit y order. ¿Por qué los dos endpoints de detalles tienen campos output diferentes? Los endpoints de detalles multimedia proporcionan los campos simplificados necesarios para la descarga directa. Los endpoints de tareas unificadas también proporcionan result_id y content_type, además de truncated para respuestas LLM archivadas. ¿Qué debo hacer si no se recibe un Webhook? Confirma que la URL de devolución de llamada sea accesible públicamente y devuelva 2xx con rapidez. Después, consulta el estado final mediante el endpoint de detalles multimedia.

Última actualización: 2026-08-12

Tutorial en video: tareas asíncronas

Activa las tareas asíncronas en la consola

​Inicio rápido

​Cómo elegir entre los tres grupos de endpoints

​Diferencias entre los endpoints multimedia y los de tareas unificadas

​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

​Modelos y campos compatibles

​Modelos para la recuperación de LLM tras una interrupción

​Cómo crear tareas de imagen

​Imágenes síncronas

​Imágenes asíncronas

​Campos estándar de imagen

​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 imágenes

​Descargar videos

​Cómo usar Webhooks

​Solicitud de devolución de llamada

​Reintentos y deduplicación

​Cómo funciona la recuperación de LLM tras una interrupción

​Respuestas y códigos de error

Enviar comentarios sobre errores HTTP 5xx

​Errores HTTP distintos de 2xx

​HTTP 200 + Task con status=failed

​Ejemplo completo de video

​Preguntas frecuentes

Inicio rápido

Cómo elegir entre los tres grupos de endpoints

Diferencias entre los endpoints multimedia y los de tareas unificadas

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

Modelos y campos compatibles

Modelos para la recuperación de LLM tras una interrupción

Cómo crear tareas de imagen

Imágenes síncronas

Imágenes asíncronas

Campos estándar de imagen

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 imágenes

Descargar videos

Cómo usar Webhooks

Solicitud de devolución de llamada

Reintentos y deduplicación

Cómo funciona la recuperación de LLM tras una interrupción

Respuestas y códigos de error

Errores HTTP distintos de 2xx

HTTP 200 + Task con `status=failed`

Ejemplo completo de video

Preguntas frecuentes