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.
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 establecerasync 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 estadopending 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 untask_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
6.3 Localizar la solicitud interrumpida correspondiente
Las respuestas de LLM devuelven la cabeceraX-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:
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
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 eltask_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
Cuandooutput contiene un único archivo, se puede acceder 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
Cuandooutput contiene varios archivos, hay que indicar el result_id correspondiente:
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 campoobject de la tarea es llm y el type del elemento de output es response. El tipo de contenido puede ser:
application/json: respuesta JSON normaltext/event-stream: respuesta SSE en streaming guardada
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.
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, incluyewebhook_url y, opcionalmente, webhook_events_filter en el cuerpo de la solicitud de imagen o video asíncronos:
10.1 Solicitud de callback
AIHubMix envía una solicitudPOST 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
2xxindica recepción correcta. - HTTP
5xx, los errores de red y los tiempos de espera agotados provocan un reintento. - HTTP
3xxy4xxno se reintentan. - Se entrega como máximo 6 veces, con intervalos de reintento de 1, 4, 16, 64 y 256 segundos.
event_id. Al recibir de nuevo el mismo event_id, omite la lógica de negocio y devuelve directamente 2xx.
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? SolicitaGET /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