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 creadas por la cuenta actual
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 creadas por la cuenta actual
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 /ai/v1/tasks/* cuando la tarea se ha identificado como imagen o vídeo. Las tareas LLM mantienen su contrato de errores existente. Las consultas sin tipo de medio especificado y sin una Task recuperada siguen usando el contrato de errores general.

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	`media_too_large`	`The {media_kind} exceeds the allowed size of {max_bytes} bytes. Reduce its size and try again.`	El contenido de otras tareas multimedia supera el límite de procesamiento actual. Reduce su tamaño según `error.details.max_bytes` o el límite del mensaje 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; las demás tareas multimedia devuelven media_too_large. Las tareas de vídeo también usan media_too_large al cargar imágenes de referencia. 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 tienes acceso. Las API específicas de imágenes y vídeos comprueban la pertenencia a la cuenta; la API unificada `/ai/v1/tasks` requiere la API Key usada para crear la tarea. Comprueba el ID de tarea y las credenciales.
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": "result_delivery_failed",
    "message": "The generated result could not be delivered. Do not resubmit automatically. Contact support with the task ID."
  }
}

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.
`provider_empty_output`	`The model provider completed the task without a usable result. Adjust the request or choose another model, then submit a new task.`	Se ha confirmado que la generación de vídeo u otro medio terminó sin un resultado utilizable. Ajusta la solicitud o elige otro modelo y envía una nueva tarea.
`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 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. Las listas específicas de imágenes y vídeos conservan la fecha de caducidad obtenida. 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 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

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

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

Preguntas frecuentes