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
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ónUsa 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
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:
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
auto | Valor 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. |
provider | Requiere una ruta con soporte asíncrono nativo. |
platform | Ejecuta 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.
queued | No | Guardada y en espera de envío. |
submitting | No | Enviándose al proveedor seleccionado. |
in_progress | No | La generación o la consulta al proveedor está en curso. |
cancel_requested | No | Se solicitó la cancelación; el proveedor aún puede finalizar. |
completed | Sí | result.data contiene las imágenes generadas. |
failed | Sí | La generación falló; consulta error. |
cancelled | Sí | Cancelada antes de que comenzara el trabajo del proveedor. |
expired | Sí | Superó la duración máxima de la tarea en el servidor. |
needs_attention | Sí | 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.
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":"..."}}.
400 | Modelo o modo de ejecución no válido, campos de streaming no compatibles, clave de idempotencia no válida o limit no entero. |
401 | Falta una clave de API de inferencia válida. |
404 | La tarea no existe o no pertenece al solicitante. |
409 | La clave de idempotencia ya se usó con una solicitud diferente. |
413 | La solicitud de tarea persistida supera el límite de tamaño configurado. |
500 | Error inesperado del servidor. Reintenta la creación solo con la clave de idempotencia original. |