Generación de imágenes

Inicio rápido

El endpoint nativo de imágenes es síncrono por defecto. Establece el booleano async en true para crear una tarea en segundo plano. El ejemplo usa qwen-image-2.0.

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",
    "async": true
  }'

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "in_progress",
  "output": [],
  "error": null,
  "created_at": 1784707200,
  "completed_at": null,
  "expires_at": null
}

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

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

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

Objeto de tarea multimedia

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

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "model": "qwen-image-2.0",
  "status": "completed",
  "output": [
    {
      "index": 0,
      "type": "file",
      "b64_json": null,
      "content_url": "https://aihubmix.com/ai/v1/images/task_01K0ABCDEF/content/result_01K0XYZ"
    }
  ],
  "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/images/{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/images?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": "image",
      "model": "qwen-image-2.0",
      "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=image&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": "image/png",
  "content_url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
}

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.

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/images/generations \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "prompt": "A tranquil garden at sunrise",
    "n": 1,
    "async": true,
    "size": "1024x1024",
    "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": "qwen-image-2.0",
    "results": [
      {
        "url": "https://aihubmix.com/ai/v1/tasks/task_01K0ABCDEF/content/result_01K0XYZ"
      }
    ]
  }
}

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

Esta sección se aplica a /ai/v1/images/* y a las tareas de imagen. Para los errores de vídeo, consulta la API de vídeo.

Fallo de la solicitud actual: un estado HTTP distinto de 2xx indica que ha fallado la creación, consulta o descarga actual. Consulta Fallos de solicitudes HTTP.
Fallo de ejecución de la tarea: la consulta devuelve HTTP 200, pero la tarea tiene status=failed y el motivo aparece en su campo error. Consulta Fallos de ejecución de tareas.
Fallo al leer el resultado de una entrada: la lista devuelve HTTP 200, pero una tarea incluye output_error. Consulta Fallos al leer resultados individuales.

La columna message muestra el texto en inglés devuelto por la API; la columna de explicación describe su significado y cómo actuar. Los errores de validación muestran mensajes generales; la respuesta real puede precisar los campos y las restricciones. Usa code para identificar el tipo de error, sin depender de una coincidencia exacta con el texto completo de message.

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

Notificar un error HTTP 5xx

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

Fallos de solicitudes HTTP

Los estados HTTP de las tablas siguientes corresponden al fallo de la solicitud actual. Los fallos de ejecución de tareas ya creadas se describen en la tabla de fallos de ejecución de tareas.

Parámetros de la solicitud y medios de entrada

HTTP	`code`	`message`	Explicación
400	`invalid_request`	`Invalid request. Check the request body and parameters.`	El cuerpo de la solicitud, los parámetros de consulta o los tipos de los parámetros son incorrectos. Comprueba el formato, los tipos y los valores indicados en el mensaje de error.
404	`model_not_found`	`The requested model was not found. Check the model name.`	El modelo solicitado no existe. Comprueba su nombre.
400	`schema_violation`	`One or more model parameters are invalid. Check the model schema and request values.`	Los parámetros no cumplen los requisitos de entrada del modelo seleccionado. Consulta su schema y corrige los campos indicados en el error.
400	`unsupported_input_combination`	`This model does not support this operation or media input combination. Change the inputs or choose another model.`	El modelo no admite esta combinación de operación y medios de entrada. Cambia la combinación o selecciona un modelo que la admita.
400	`capability_not_supported`	`One or more requested parameters are not supported by this model. Change the parameters or choose another model.`	Los parámetros solicitados exceden las capacidades del modelo. Ajústalos según el mensaje de error o elige otro modelo.
400	`unsupported_media_format`	`The {media_kind} format is not supported for this model.`	El modelo no admite este formato. Usa uno de los formatos del mensaje de error o de `error.details.allowed_mime_types`. Si no se proporciona una lista, consulta los requisitos de entrada del modelo.
400	`invalid_media_data`	`The media data is invalid. Provide valid media data.`	Se ha confirmado que los datos del medio no son válidos, por ejemplo, por base64 dañado o una estructura de URI de datos incorrecta. Comprueba la integridad y la codificación y proporciona datos válidos.
400	`media_url_unreachable`	`The media URL could not be accessed. Make sure it is publicly accessible and returns valid media data.`	No se puede acceder al enlace del medio o leerlo. Comprueba que sea válido, accesible públicamente y que devuelva contenido multimedia válido.
400	`invalid_media`	`The media input could not be processed. Check that its data or URL is valid and uses a supported format.`	No se puede procesar el medio de entrada y no se ha confirmado una causa más concreta. Comprueba que los datos o la URL sean válidos y que el modelo admita el formato.
413	`image_too_large`	`The image is too large. Reduce the image size to {max_bytes} bytes or less and try again.`	El contenido multimedia de la tarea de imagen supera el límite de procesamiento actual. Reduce su tamaño según `error.details.max_bytes` o el límite del mensaje de error e inténtalo de nuevo.
413	`request_too_large`	`The request body exceeds the 32 MiB limit. Reduce the request size and try again.`	El cuerpo HTTP completo supera los 32 MiB. Reduce el cuerpo enviado, incluido el texto, los parámetros y los medios codificados incluidos en él.

Límites de tamaño

Tamaño del medio: las tareas de imagen que superan el límite devuelven image_too_large. Consulta el límite en el mensaje de error o en error.details.max_bytes.
Tamaño total de la solicitud: request_too_large indica que el cuerpo HTTP supera los 32 MiB, incluidos el texto, los parámetros y los medios codificados. Si solo envías una URL, el enlace cuenta como parte del cuerpo; el archivo de destino debe seguir cumpliendo los límites multimedia del modelo.
Tamaño real: error.details.actual_bytes solo se incluye cuando se conoce el tamaño completo. Puede omitirse si la lectura de una URL se detiene al alcanzar el límite de lectura.

Formatos compatibles Dependen del modelo seleccionado. Consulta primero error.details.allowed_mime_types o la lista de formatos del mensaje de error. Si no hay lista, consulta el Schema del modelo. Marcadores de posición de los mensajes

{media_kind}: tipo real de medio. Cuando se conoce, los mensajes de invalid_media_data y media_url_unreachable también usan image o video.
{max_bytes}: límite en bytes. Si no se conoce el límite de la imagen, el mensaje es The image is too large. Reduce the image size and try again.
{allowed_formats}: lista de formatos permitidos. Los errores de formato pueden añadir Use one of: {allowed_formats}.

Solicitudes de generación y resultados devueltos

HTTP	`code`	`message`	Explicación
502	`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then try again. If the problem persists, contact support with the request ID.`	El proveedor de modelos completó la solicitud sin devolver una imagen utilizable. Ajusta la solicitud o elige otro modelo y vuelve a intentarlo. Si el problema persiste, contacta con soporte e indica el ID de solicitud. No repitas la generación automáticamente solo por recibir HTTP 502.
422	`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	El proveedor de modelos bloqueó el contenido generado y no devolvió una imagen utilizable. Modifica el prompt o el contenido de entrada y vuelve a intentarlo. Esta generación no se cobra.
400	`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	El proveedor de modelos rechazó la solicitud. Este código por sí solo no confirma una infracción de contenido. Comprueba y modifica los parámetros y el contenido antes de volver a intentarlo.
502	`upstream_bad_response`	`The model provider response could not be processed. Contact support with the request ID.`	El proveedor de modelos devolvió una respuesta que la plataforma no puede procesar. Esto no confirma la ausencia de resultados generados. Contacta con soporte e indica el ID de solicitud; no lo interpretes como un error de parámetros ni como un resultado vacío.
400	`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao devolvió un código específico de rechazo por privacidad de imágenes de personas reales. Completa la verificación de personas reales y utiliza un recurso `asset://` activado. Consulta la documentación de recursos de personas reales.
504	`sync_timeout`	`Generation did not complete within the waiting period. Contact support with the request ID.`	La generación no terminó dentro del tiempo de espera. El tiempo de espera agotado no demuestra que la solicitud no se ejecutara. Contacta con soporte e indica el ID de solicitud; no consultes un ID de tarea que no se te haya devuelto.
502	`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID or request ID.`	La tarea se envió al proveedor de modelos, pero no se puede confirmar su estado posterior. No la envíes de nuevo. Contacta con soporte e indica el ID de solicitud y, si lo tienes, el ID de tarea.

Cuenta y permisos

HTTP	`code`	`message`	Explicación
401	`authentication_failed`	`Authentication failed: invalid or missing API key.`	La API Key falta o no es válida. Comprueba la cabecera `Authorization` y la API Key.
402	`insufficient_quota`	`Your account has insufficient quota. Add credits and try again.`	La cuenta no tiene cuota suficiente. Añade créditos y vuelve a intentarlo.
403	`permission_denied`	`You do not have permission to access this resource. Check the account, API key permissions, and IP restrictions.`	La cuenta o la API Key no tienen acceso. Comprueba los permisos de la cuenta, de la API Key y las restricciones de IP.
403	`async_not_enabled`	`Asynchronous tasks are not enabled. Please go to https://console.aihubmix.com/async-tasks to activate.`	Las tareas asíncronas no están activadas en la cuenta. Actívalas mediante el enlace de la consola incluido en la respuesta y vuelve a intentarlo.

Disponibilidad del servicio y límites de solicitudes

HTTP	`code`	`message`	Explicación
429	`rate_limited`	`Too many requests. Reduce the request rate and try again later.`	La frecuencia de solicitudes es demasiado alta. Redúcela y vuelve a intentarlo.
429	`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	El proveedor de modelos está limitando las solicitudes. Inténtalo más tarde y evita los reenvíos inmediatos y repetidos.
500	`internal_error`	`An internal error occurred. Contact support with the request ID.`	Se produjo un error interno de la plataforma. Contacta con soporte e indica el ID de solicitud; no es necesario modificar repetidamente una entrada válida.
502	`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	El proveedor de modelos no está disponible temporalmente, posiblemente por un fallo de conexión, de su servicio o de lectura de la respuesta. Este código no permite confirmar si se generaron resultados. Si el problema persiste, contacta con soporte e indica el ID de solicitud.
502	`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	El proveedor de modelos no está disponible. La tabla muestra el mensaje predeterminado; la respuesta real puede incluir indicaciones más concretas. Identifica el tipo de error mediante `code` y contacta con soporte con el ID de solicitud.
503	`model_unavailable`	`The requested model is temporarily unavailable. Try again later or choose another model. If the problem persists, contact support with the request ID.`	El modelo no está disponible temporalmente. Inténtalo más tarde o elige otro modelo. Si el problema persiste, contacta con soporte e indica el ID de solicitud.
503	`service_unavailable`	`The service is temporarily unavailable. Try again later. If the problem persists, contact support with the request ID.`	El servicio no está disponible temporalmente. Reintenta la operación más tarde. Si falló una descarga, reintenta la descarga sin volver a generar.

provider_unavailable indica un fallo confirmado del proveedor de modelos. Un estado genérico 429 o 4xx no permite identificar por sí solo problemas de cuota, moderación de contenido o parámetros.

Consulta de tareas y descarga de resultados

HTTP	`code`	`message`	Explicación
404	`task_not_found`	`The task was not found.`	La tarea no existe o no pertenece a la cuenta actual. Comprueba el ID de tarea y que la API Key pertenezca a la cuenta que la creó.
404	`result_not_found`	`The result was not found.`	El resultado no existe o no tienes permiso para leerlo. Comprueba el ID de tarea, el ID de resultado y la API Key. Un ID de resultado conocido como inválido no pasa a devolver 409 porque la tarea siga ejecutándose.
400	`invalid_cursor`	`The cursor is invalid or expired. Start a new list request.`	El cursor de paginación no es válido o ha caducado. Elimina `after`, consulta desde la primera página y utiliza el nuevo cursor devuelto por esa lista.
400	`result_id_required`	`This task has multiple results. Specify result_id.`	La tarea tiene varios resultados y no se ha indicado `result_id`. Elige un resultado de la salida de la tarea e indica su `result_id`.
409	`result_not_ready`	`The result is not available yet. Check the task status before downloading.`	La tarea está en cola o en ejecución y el resultado aún no está listo. Sigue consultando el estado y descarga el resultado cuando esté disponible. No es necesario volver a generar.
410	`artifact_expired`	`The result has expired and is no longer available. Submit a new generation request.`	El resultado ha superado su periodo de conservación y ya no se puede descargar. Envía una nueva solicitud de generación si lo necesitas.
429	`too_many_downloads`	`Download limit exceeded for this result.`	Se alcanzó el límite de descargas. Comprueba los resultados que ya hayas guardado. Esperar no garantiza que se restablezca el número de descargas.

Fallos de ejecución de tareas

Cuando una tarea ya creada falla durante la generación, se indica mediante status=failed y el campo error de la tarea. Una consulta correcta sigue devolviendo HTTP 200.

{
  "id": "task_01K0ABCDEF",
  "object": "image",
  "status": "failed",
  "output": [],
  "error": {
    "code": "image_not_generated",
    "message": "The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task."
  }
}

Task `code`	`message`	Explicación
`image_not_generated`	`The model provider completed the request but did not return an image. Adjust the request or choose another model, then submit a new task.`	El proveedor de modelos completó la solicitud sin devolver una imagen utilizable. Ajusta la solicitud o elige otro modelo y envía una nueva tarea. No repitas la generación automáticamente sin evaluar el error.
`output_blocked`	`The model provider blocked the generated output. Change the prompt or input content and try again.`	El proveedor de modelos bloqueó el contenido generado y no devolvió una imagen utilizable. Modifica el prompt o el contenido de entrada y envía una nueva tarea. Esta generación no se cobra.
`output_policy_violation`	`Generated content was rejected by the content policy.`	El contenido generado no superó la moderación. Modifica el prompt o la entrada y envía una nueva tarea. Se aplican las reglas de cobro existentes para moderación; consulta los registros de facturación para los cargos anteriores.
`upstream_rejected`	`The model provider rejected the request. Check the request parameters and content.`	El proveedor de modelos rechazó la solicitud. Este código por sí solo no confirma una infracción de contenido. Comprueba y modifica los parámetros y la entrada antes de enviar una nueva tarea.
`upstream_bad_response`	`The model provider response could not be processed. Contact support with the task ID.`	La plataforma no puede procesar la respuesta del proveedor de modelos. Esto no confirma la ausencia de resultados generados. Contacta con soporte e indica el ID de tarea.
`task_status_unavailable`	`The model provider task state could not be confirmed. Do not submit it again. Contact support with the task ID.`	La tarea se envió al proveedor de modelos, pero no se puede confirmar su estado posterior. No la envíes de nuevo. Contacta con soporte e indica el ID de tarea.
`result_delivery_failed`	`The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID.`	Existe un resultado generado, pero la plataforma no pudo guardarlo o entregarlo. No vuelvas a generar automáticamente. Contacta con soporte con el ID de tarea para investigar primero el resultado existente.
`upstream_rate_limited`	`Upstream service is rate limiting. Please retry later.`	El proveedor de modelos está limitando las solicitudes. Inténtalo más tarde y evita los reenvíos inmediatos y repetidos.
`upstream_unreachable`	`Upstream service is temporarily unavailable. Please retry.`	Durante la ejecución falló la conexión con el proveedor de modelos, su servicio o la lectura de la respuesta. Este código no confirma si se generaron resultados. Si el problema persiste, contacta con soporte e indica el ID de tarea.
`provider_unavailable`	`The model provider is unavailable. Contact support with the request or task ID.`	El proveedor de modelos no está disponible. La tabla muestra el mensaje predeterminado; la respuesta real puede incluir indicaciones más concretas. Identifica el tipo de error mediante `code` y contacta con soporte con el ID de tarea.
`doubao_real_person_required`	`This request uses a real-person image. Complete real-person verification and use an active asset reference. See https://docs.aihubmix.com/cn/api/doubao-real-person-assets.`	Doubao devolvió un código específico de rechazo por privacidad de imágenes de personas reales. Completa la verificación de personas reales y utiliza un recurso `asset://` activado. Consulta la documentación de recursos de personas reales.
`sync_timeout`	`Generation timed out. Contact support with the task ID.`	La tarea de generación agotó el tiempo de espera. Contacta con soporte e indica el ID de tarea.
`internal_error`	`An internal error occurred. Contact support with the task ID.`	Se produjo un error interno de la plataforma. Contacta con soporte e indica el ID de tarea; no es necesario modificar repetidamente una entrada válida.

Los errores de medios de entrada también pueden aparecer en una Task fallida y tienen el mismo significado que en la tabla anterior. Una consulta correcta sigue devolviendo HTTP 200. El message de los errores de tamaño termina en submit a new task., indicando que debes reducir el tamaño y enviar una nueva tarea. output_blocked indica un bloqueo confirmado sin imagen utilizable; esta generación no se cobra. Para output_policy_violation se aplican las reglas de cobro existentes para moderación. Consulta los registros de facturación para los cargos anteriores.

Fallos al leer resultados individuales

Algunas entradas de las listas de tareas de imagen y vídeo pueden incluir output_error:

{
  "output_error": {
    "code": "internal_error",
    "type": "server_error",
    "message": "The task output could not be read. Contact support with the request ID.",
    "tid": "req_01K0ABCDEF"
  }
}

Este campo indica que no se pudo leer el resultado de esa entrada en esta consulta. La lista sigue devolviendo HTTP 200 y esa entrada tiene output=[]. Se conservan su id, status, error y la paginación, y las demás tareas legibles no se ven afectadas. Comprueba output_error incluso con status=completed antes de considerar disponible el resultado. Contacta con soporte e indica output_error.tid. Si el campo no incluye tid, proporciona el ID de solicitud de las cabeceras de la respuesta actual. Este error no cambia el estado de la tarea ni los cargos y no activa un Webhook. Las listas de imágenes y vídeos conservan el expires_at obtenido. Las entradas con errores de lectura en la lista unificada /ai/v1/tasks pueden devolver expires_at=null; los resultados siguen sujetos al periodo de conservación original. Este tratamiento solo se aplica cuando no se puede leer el resultado de una entrada y no hay una alternativa disponible. Un fallo de consulta de todo el lote en la API unificada de tareas sigue devolviendo un error HTTP; el mismo fallo al consultar detalles sigue devolviendo HTTP 500. Documentación relacionada: API de imágenes · API de vídeo · Tareas asíncronas

Ejemplo completo

Estos ejemplos crean una tarea asíncrona, la consultan y guardan todas las imágenes devueltas.

import base64
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/images/generations",
    headers=headers,
    json={
        "model": "qwen-image-2.0",
        "prompt": "A flower shop with delicate windows, warm sunlight streaming in",
        "n": 1,
        "size": "1024x1024",
        "async": True,
    },
    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/images/{task['id']}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()

if task["status"] != "completed":
    raise RuntimeError(task.get("error") or task["status"])

for output in task["output"]:
    filename = f"result-{output['index']}.png"
    if output.get("b64_json"):
        content = base64.b64decode(output["b64_json"])
    else:
        result = requests.get(output["content_url"], headers=headers, timeout=120)
        result.raise_for_status()
        content = result.content
    with open(filename, "wb") as file:
        file.write(content)

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/images/generations`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    model: "qwen-image-2.0",
    prompt: "A flower shop with delicate windows, warm sunlight streaming in",
    n: 1,
    size: "1024x1024",
    async: true,
  }),
});
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/images/${task.id}`, { headers });
  if (!polled.ok) throw new Error(await polled.text());
  task = await polled.json();
}

if (task.status !== "completed") {
  throw new Error(JSON.stringify(task.error ?? task.status));
}

for (const output of task.output) {
  let content;
  if (output.b64_json) {
    content = Buffer.from(output.b64_json, "base64");
  } else {
    const result = await fetch(output.content_url, { headers });
    if (!result.ok) throw new Error(await result.text());
    content = Buffer.from(await result.arrayBuffer());
  }
  await writeFile(`result-${output.index}.png`, content);
}

Empezar

Funciones de gateway

Capacidades del modelo

Referencia de protocolo

Gestión de plataforma

Generación de imágenes

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 imagen

Imágenes síncronas

Imágenes asíncronas

Campos estándar de imagen

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

Cómo usar Webhooks

Solicitud de devolución de llamada

Reintentos y deduplicación

Respuestas y códigos de error

Notificar un error HTTP 5xx

Fallos de solicitudes HTTP

Parámetros de la solicitud y medios de entrada

Solicitudes de generación y resultados devueltos

Cuenta y permisos

Disponibilidad del servicio y límites de solicitudes

Consulta de tareas y descarga de resultados

Fallos de ejecución de tareas

Fallos al leer resultados individuales

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 imagen

​Imágenes síncronas

​Imágenes asíncronas

​Campos estándar de imagen

​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

​Cómo usar Webhooks

​Solicitud de devolución de llamada

​Reintentos y deduplicación

​Respuestas y códigos de error

Notificar un error HTTP 5xx

​Fallos de solicitudes HTTP

​Parámetros de la solicitud y medios de entrada

​Solicitudes de generación y resultados devueltos

​Cuenta y permisos

​Disponibilidad del servicio y límites de solicitudes

​Consulta de tareas y descarga de resultados

​Fallos de ejecución de tareas

​Fallos al leer resultados individuales

​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 imagen

Imágenes síncronas

Imágenes asíncronas

Campos estándar de imagen

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

Cómo usar Webhooks

Solicitud de devolución de llamada

Reintentos y deduplicación

Respuestas y códigos de error

Fallos de solicitudes HTTP

Parámetros de la solicitud y medios de entrada

Solicitudes de generación y resultados devueltos

Cuenta y permisos

Disponibilidad del servicio y límites de solicitudes

Consulta de tareas y descarga de resultados

Fallos de ejecución de tareas

Fallos al leer resultados individuales

Ejemplo completo