Skip to main content
La generación de video y la generación de imágenes por lotes suelen tardar más de lo que resulta razonable esperar en una sola conexión HTTP; y si el cliente se desconecta durante una generación de texto largo, la respuesta ya producida tampoco se puede recuperar. Las tareas asíncronas (Async Tasks) unifican estos tres escenarios en un mismo objeto de tarea: imagen y video crean una tarea mediante los endpoints de generación y devuelven de inmediato un task_id; las solicitudes de LLM interrumpidas por el cliente las completa la plataforma, que guarda la respuesta final. Los tres comparten los mismos estados de tarea, el mismo endpoint de consulta y el mismo flujo de descarga de resultados.
Consulta las tareas y descarga los resultados con la misma API Key con la que creaste la tarea. Las tareas están aisladas por API Key: aunque dos Keys pertenezcan a la misma cuenta, no pueden leer las tareas de la otra.

Activa las tareas asíncronas en la consola

Antes de crear imágenes o videos asíncronos, activa la función de tareas asíncronas para tu cuenta. Si la consola aún no muestra esta opción, contacta con el soporte técnico de AIHubMix.
Si la función de tareas asíncronas no está activada, las solicitudes de creación de tareas multimedia devuelven 403 async_not_enabled. Las solicitudes de LLM no fallan por este motivo, pero la respuesta final no se podrá recuperar tras una interrupción del cliente.

1. Inicio rápido

El flujo completo de las tareas asíncronas de imagen y video consta de tres pasos:

2. Comparación entre llamadas síncronas y tareas asíncronas

Las llamadas síncronas devuelven el resultado dentro de una única respuesta HTTP y el resultado no se puede recuperar si la conexión se corta. Las tareas asíncronas guardan el resultado en la plataforma, y el task_id permite volver a consultarlo y descargarlo con la misma API Key antes de que el resultado expire, lo que resulta útil para solicitudes de generación de larga duración y para salidas de texto largo cuya respuesta final se necesita recuperar tras una interrupción.

3. Resumen de endpoints

Base URL: https://aihubmix.com, con autenticación mediante Bearer Token:
/ai/v1/tasks es un punto de consulta unificado de solo lectura y no ofrece POST /ai/v1/tasks. Las imágenes y los videos se crean con sus respectivos endpoints de generación; las solicitudes que cumplen las condiciones de recuperación de LLM tras interrupción se registran automáticamente como tareas llm cuando el cliente se interrumpe.

4. Modelos compatibles

Las tareas asíncronas definen su alcance de compatibilidad según el tipo de tarea, y la llamada no requiere parámetros adicionales.

4.1 Imágenes asíncronas

4.2 Videos asíncronos

4.3 Recuperación de LLM tras interrupción

El alcance admitido se seguirá ampliando y esta tabla se actualizará en consecuencia.

5. Cómo crear tareas asíncronas

5.1 Imágenes asíncronas

El endpoint de imágenes devuelve el resultado de forma síncrona por defecto. Al establecer async en true, el endpoint devuelve de inmediato el objeto de tarea y la generación continúa en segundo plano.
async debe ser un valor booleano. Si se omite o se establece en false, el endpoint de imágenes mantiene el comportamiento síncrono.

5.2 Videos asíncronos

El endpoint de video es siempre asíncrono. Tras una creación correcta devuelve el estado pending o in_progress, y no admite el cambio a espera síncrona mediante Prefer: wait.

5.3 Parámetros comunes

En los ejemplos, model, prompt, n, seconds y size son parámetros habituales de los modelos; los campos y valores admitidos por cada modelo se rigen por la documentación de API del modelo correspondiente, y para los modelos de video puedes consultar la documentación de generación de video. La siguiente tabla describe únicamente los parámetros comunes a todas las tareas asíncronas.
Las tareas de imagen solo pueden usar Webhook cuando se envían con async: true. Si se omite webhook_events_filter, la plataforma envía los tres estados finales completed, failed y cancelled; si se incluye, debe usarse junto con webhook_url, no puede estar vacío ni contener valores repetidos.

6. Cómo funciona la recuperación de LLM tras interrupción

La recuperación de LLM tras interrupción sirve para obtener la respuesta final después de que el cliente cierre la conexión. Esta capacidad reutiliza la forma actual de llamar al LLM, mantiene el mismo comportamiento de streaming y el mismo formato de respuesta, no requiere llamar a un endpoint de creación adicional y tampoco devuelve un task_id por adelantado.

6.1 Condiciones de aplicación

Se deben cumplir todas las condiciones siguientes: Endpoints admitidos:
No es necesario enviar campos adicionales en la llamada. El alcance admitido se indica en 4.3 Recuperación de LLM tras interrupción; para los modelos que no figuran en la tabla, puedes verificar la recuperación tras interrupción con una solicitud de bajo coste antes de la integración definitiva, y esa solicitud de verificación se factura con normalidad. Si alguna condición no se cumple, la solicitud se ejecuta igualmente y no se genera una tarea llm cuando el cliente se interrumpe.

6.2 Flujo de ejecución tras la interrupción

Las solicitudes de LLM que se completan correctamente y se devuelven al cliente no crean tareas ni aparecen en la lista de tareas. Las solicitudes interrumpidas aparecen en la lista una vez guardada la respuesta final, por lo que durante el procesamiento es posible que todavía no se encuentren en la consulta.

6.3 Localizar la solicitud interrumpida correspondiente

Las respuestas de LLM devuelven la cabecera X-Aihubmix-Request-Id. El cliente debe guardar ese valor en cuanto reciba las cabeceras de respuesta; tras una interrupción, puedes usar ese ID de solicitud en la lista de tareas asíncronas de la consola de AIHubMix para localizar la tarea correspondiente. La API pública de tareas todavía no admite el filtrado por ID de solicitud. Si no has guardado el ID de solicitud, la búsqueda solo puede hacerse con la misma API Key usada al crear la solicitud, por modelo y fecha de creación:
Cuando la misma API Key lanza varias solicitudes concurrentes al mismo modelo, el modelo y la fecha de creación no bastan para garantizar una correspondencia exacta. Si necesitas una recuperación fiable, guarda X-Aihubmix-Request-Id y localiza la tarea desde la consola; si no dispones de las cabeceras de respuesta, evita dar por hecho que la tarea más reciente de la lista corresponde a esa solicitud.
Las tareas de recuperación de LLM tras interrupción todavía no envían Webhook; consulta el resultado a través de la lista de tareas. La interrupción del cliente no detiene el procesamiento en la plataforma, y esa llamada se factura según las reglas del endpoint de LLM original.

7. Objeto de tarea y estados

Todas las tareas usan una estructura de respuesta unificada:
Campos de los resultados dentro de output:

7.1 Descripción de los estados

Se recomienda consultar cada 15 segundos hasta que el estado pase a completed, failed o cancelled.
Las tareas failed o cancelled también pueden contener resultados parciales ya generados. Para determinar si hay resultados, además del estado conviene comprobar si output está vacío.

8. Cómo consultar las tareas

8.1 Consultar el detalle de una tarea

Este endpoint devuelve la información más reciente de la tarea en el momento de la consulta. La consulta no modifica la tarea; el estado lo actualiza la plataforma automáticamente.

8.2 Consultar la lista de tareas

Si se pierde la respuesta de creación, o se necesita revisar tareas históricas por lotes, el endpoint de lista permite recuperar el task_id:
Ejemplo de respuesta:
Para solicitar la página siguiente:

9. Cómo obtener los resultados de una tarea

9.1 Tareas con un solo resultado

Cuando output contiene un único archivo, se puede acceder directamente:
También puedes usar directamente output[0].content_url. El Content-Type de la respuesta de descarga coincide con output[0].content_type.

9.2 Tareas con varios resultados

Cuando output contiene varios archivos, hay que indicar el result_id correspondiente:
Si en una tarea con varios resultados no se indica result_id, el endpoint devuelve 400 result_id_required.

9.3 Tareas de respuesta de LLM

Cuando se cumplen las condiciones de recuperación de LLM tras interrupción y la respuesta se ha guardado, el campo object de la tarea es llm y el type del elemento de output es response. El tipo de contenido puede ser:
  • application/json: respuesta JSON normal
  • text/event-stream: respuesta SSE en streaming guardada
La marca de truncado se encuentra en output[0].truncated dentro del detalle de la tarea. Cuando su valor es true, la respuesta guardada se truncó por el límite de tamaño. GET /ai/v1/tasks/{task_id}/content devuelve el contenido JSON o SSE original, sin envolverlo en un campo truncated, por lo que conviene consultar primero el detalle de la tarea y leer el contenido después.
Los resultados pueden expirar y también puede existir un límite de descargas. Guárdalos antes de expires_at. Un resultado expirado devuelve 410 artifact_expired y superar el límite de descargas devuelve 429 too_many_downloads.

10. Cómo usar Webhook

Actualmente se admite el envío de un Webhook a nivel de tarea durante la creación de tareas asíncronas. Si quieres que AIHubMix te notifique al terminar la tarea, incluye webhook_url y, opcionalmente, webhook_events_filter en el cuerpo de la solicitud de imagen o video asíncronos:
La dirección de callback debe usar HTTPS y no puede apuntar a la máquina local, a redes privadas ni a otras direcciones restringidas.

10.1 Solicitud de callback

AIHubMix envía una solicitud POST a la dirección de callback:
Las URL de results siguen requiriendo la API Key con la que se creó la tarea para poder accederse.

10.2 Reintentos y deduplicación

La plataforma intenta entregar el callback al menos una vez, por lo que un mismo evento puede enviarse de forma repetida:
  • HTTP 2xx indica recepción correcta.
  • HTTP 5xx, los errores de red y los tiempos de espera agotados provocan un reintento.
  • HTTP 3xx y 4xx no se reintentan.
  • Se entrega como máximo 6 veces, con intervalos de reintento de 1, 4, 16, 64 y 256 segundos.
El receptor debe guardar el event_id. Al recibir de nuevo el mismo event_id, omite la lógica de negocio y devuelve directamente 2xx.
El Webhook a nivel de tarea todavía no ofrece credenciales de firma independientes configurables. Al recibir la notificación, solicita GET /ai/v1/tasks/{task_id} con la API Key usada al crear la tarea y toma el resultado de la consulta como referencia.

11. Respuestas de error y códigos de error

Las respuestas de error usan una estructura unificada:

12. Ejemplo completo

Flujo completo para crear una tarea de video, sondear el estado y descargar todos los resultados:

Preguntas frecuentes

¿Con qué frecuencia conviene consultar el estado de la tarea? Se recomienda consultar cada 15 segundos y evitar el sondeo de alta frecuencia. Si usas Webhook, conviene mantener también una consulta de baja frecuencia como respaldo. ¿Cómo recupero la tarea si he perdido la respuesta de creación? Solicita GET /ai/v1/tasks con la misma API Key con la que creaste la tarea; puedes acotar la búsqueda con object, model y status. ¿Por qué otra API Key de la misma cuenta no encuentra la tarea? Las tareas están aisladas por API Key. Las solicitudes de consulta, descarga y lista deben usar la misma Key con la que se creó la tarea. ¿Por qué la tarea ha fallado pero output no es un array vacío? Algunos modelos pueden haber generado resultados aprovechables antes del fallo o la cancelación global. Siempre que exista content_url o b64_json en output, el resultado puede obtenerse por la vía correspondiente. ¿Qué hago si no recibo el Webhook? Comprueba que la dirección de callback sea accesible públicamente, que use HTTPS y que devuelva 2xx en menos de 10 segundos. Uses o no Webhook, siempre puedes consultar el estado final con GET /ai/v1/tasks/{task_id}. ¿La recuperación de LLM tras interrupción requiere cambiar el código actual? No. La forma de hacer la solicitud, el comportamiento de streaming y el formato de respuesta se mantienen. Se recomienda guardar la cabecera de respuesta X-Aihubmix-Request-Id para poder localizar la tarea correspondiente en la consola tras una interrupción.
Última actualización: 2026-07-28