Generación asíncrona de imágenes

La generación asíncrona de imágenes de Token360 crea una tarea duradera y permite que tu aplicación consulte el resultado sin mantener abierta la conexión HTTP original.

El endpoint existente POST /v1/images/generations sigue siendo síncrono. La generación asíncrona usa el espacio de nombres independiente /v1/async/images/tasks.

Flujo de trabajo

text
11. POST /v1/async/images/tasks                  → id de tarea (HTTP 202)
22. GET  /v1/async/images/tasks/{task_id}        → consultar hasta un estado terminal
33. POST /v1/async/images/tasks/{task_id}/cancel → opcional, mejor esfuerzo
44. GET  /v1/billing/requests/image-task:{task_id}?type=image → conciliar la facturación

Usa GET /v1/async/images/tasks?limit=20 para listar tus tareas más recientes.

Todos los endpoints de tareas requieren una clave de API de inferencia en Authorization: Bearer .... Devuelven directamente el objeto JSON público V1 e incluyen Cache-Control: no-store.

Crear una tarea

Shell
1curl -X POST https://api.token360.ai/v1/async/images/tasks \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -H "Idempotency-Key: image-order-20260921-0001" \
5  -d '{
6    "model": "gpt-image-2.5-flare",
7    "prompt": "Un faro en acuarela al amanecer",
8    "size": "1024x1024",
9    "n": 1,
10    "execution": "auto"
11  }'

La respuesta es un objeto de tarea con HTTP 202 Accepted:

JSON
1{
2  "id": "img_task_...",
3  "object": "image_generation.task",
4  "model": "gpt-image-2.5-flare",
5  "status": "queued",
6  "execution": "auto",
7  "version": 1,
8  "created_at": "2026-09-21T12:00:00Z",
9  "updated_at": "2026-09-21T12:00:00Z"
10}

stream debe ser false u omitirse. partial_images no es compatible.

Modos de ejecución

autoValor predeterminado. Usa el modo asíncrono nativo del proveedor cuando la ruta seleccionada lo admite; en caso contrario, usa el modo asíncrono administrado por la plataforma.
providerRequiere una ruta con soporte asíncrono nativo.
platformEjecuta la solicitud normal al proveedor en el worker duradero en segundo plano de Token360.

La API de tareas es común para GPT-image, Nano Banana y otras familias de modelos de imagen. La disponibilidad del modo asíncrono nativo varía según el modelo y la ruta.

Idempotencia

Envía un Idempotency-Key (máximo 200 caracteres) en cada solicitud de creación.

  • La misma clave y la misma solicitud devuelven la tarea original con HTTP 202, incluso después de completarse.
  • La misma clave con una solicitud diferente devuelve HTTP 409.
  • Sin clave, cada solicitud aceptada crea una tarea nueva y puede generar un cargo independiente del proveedor.

Si la conexión de creación agota el tiempo de espera, reintenta con la misma clave. No generes una clave nueva para el reintento.

Consulta y estados

Consulta cada 2-5 segundos al principio y después usa backoff exponencial con jitter hasta unos 30 segundos. Actualmente no hay webhooks para las tareas asíncronas de imagen.

queuedNoGuardada y en espera de envío.
submittingNoEnviándose al proveedor seleccionado.
in_progressNoLa generación o la consulta al proveedor está en curso.
cancel_requestedNoSe solicitó la cancelación; el proveedor aún puede finalizar.
completedSíresult.data contiene las imágenes generadas.
failedSíLa generación falló; consulta error.
cancelledSíCancelada antes de que comenzara el trabajo del proveedor.
expiredSíSuperó la duración máxima de la tarea en el servidor.
needs_attentionSíEl resultado del envío es ambiguo; se evitó un reenvío automático.

Para needs_attention, no reintentes con una clave de idempotencia nueva. Conserva el ID de tarea y contacta con el soporte de Token360: un nuevo envío al proveedor podría crear una imagen y un cargo duplicados.

Facturación

El uso completado se correlaciona como image-task:<task_id>. La ingestión de facturación es asíncrona, por lo que el registro puede aparecer poco después de que termine la tarea.

Shell
1curl 'https://api.token360.ai/v1/billing/requests/image-task:img_task_...?type=image' \
2  -H "Authorization: Bearer sk-your-api-key"

Errores

Los errores usan el formato público V1: {"error":{"message":"...","type":"...","code":"..."}}.

400Modelo o modo de ejecución no válido, campos de streaming no compatibles, clave de idempotencia no válida o limit no entero.
401Falta una clave de API de inferencia válida.
404La tarea no existe o no pertenece al solicitante.
409La clave de idempotencia ya se usó con una solicitud diferente.
413La solicitud de tarea persistida supera el límite de tamaño configurado.
500Error inesperado del servidor. Reintenta la creación solo con la clave de idempotencia original.

Referencia de API relacionada

¿Ha sido de ayuda?
Generación asíncrona de imágenes · Token360