Resumen
Para agentes de código, descubre primero la lista corta recomendada de imágenes conGET /v1/models?recommended_for=image, y luego envía explícitamente el model elegido a este endpoint.
gpt-image-2 es un modelo GPT Image con facturación por tokens. TokenLab sigue el desglose oficial de usage de OpenAI para liquidar tokens de entrada de texto, entrada de imagen, entrada en caché cuando se reporta, y salida de imagen; no se factura como un precio fijo por imagen.
Para generación de imágenes con gpt-image-2, los parámetros públicos admitidos son prompt, n, size, quality, response_format, async, background, output_format, output_compression o compression, moderation y user. Si omites size o quality, TokenLab usa auto; los valores personalizados de size deben usar el contrato flexible WIDTHxHEIGHT documentado abajo.
input_fidelity no forma parte del campos admitidos actual de TokenLab para gpt-image-2; omítelo o la solicitud devolverá 400 unsupported_parameter.
Notas de comportamiento del modelo
Google Gemini no comparten el mismo contrato de selección:gemini-3.1-flash-image,gemini-3-pro-imageynano-banana-proadmitenaspect_ratiojunto conresolution(1k,2k,4k) para sus operaciones públicas de texto a imagen e image-edit/image-to-image.nano-banana-2admiteaspect_ratiojunto conresolution(1k,2k,4k) solo para texto a imagen en el contrato actual de TokenLab.gemini-2.5-flash-image,nano-bananaynano-banana-editadmitenaspect_ratio, pero no exponen selección pública deresolution.- Para solicitudes Nano Banana con imagen de referencia, usa
nano-banana-editonano-banana-proen este endpoint (/v1/images/generations) conoperation: "image-to-image"eimage_urls. No envíes solicitudes de referencia Nano Banana a/v1/images/edits. - En solicitudes Nano Banana image-to-image,
nano-banana-propuede incluirresolution(1k,2k,4k);nano-banana-editdebe omitirlo.nano-bananaynano-banana-2son modelos de texto a imagen en el detalles del modelo actual. - Las imágenes de referencia en este endpoint pueden enviarse como JSON
image_url/image_urls, o como archivo multipartimage./v1/images/generationsno aceptaimages[]nifile_id; las referencias de/v1/filessolo aplican a modelos de/v1/images/editsque documentanimages[].file_id.
aspect_ratio y envía resolution solo cuando el modelo lo admita explícitamente.
Los modelos de imagen xAI Grok Imagine (grok-imagine-image, grok-imagine-image-quality y el legacy grok-imagine-image-pro) admiten aspect_ratio junto con resolution (1k, 2k). grok-imagine-image-pro se conserva como ID de compatibilidad para grok-imagine-image-quality.
Cuerpo de la solicitud
Tiempo de espera de solicitudes síncronas: algunas solicitudes de imagen devuelven la imagen final inline y esperan a que termine la generación. Las solicitudes de alta resolución o alta calidad pueden tardar cerca de un minuto o más, así que configura el timeout de tu cliente HTTP en al menos120s. Si la respuesta de creación incluye status: "pending", task_id o poll_url, sigue el poll_url devuelto en su lugar.
Modelo a usar (por ejemplo,
gpt-image-2, flux-pro, qwen-image-plus o nano-banana-pro). Consulta GET /v1/models?recommended_for=image para la lista recomendada actual.Descripción textual de la imagen deseada.
URL HTTPS pública de imagen de referencia para generación image-to-image. En solicitudes Nano Banana con imagen de referencia, establece
operation en image-to-image; nano-banana-pro puede incluir resolution, mientras que nano-banana-edit debe omitirlo.URLs HTTPS públicas de imágenes de referencia. Úsalo para una o más imágenes de referencia en solicitudes JSON. Este endpoint no admite
file_id ni images[].URLs adicionales de referencia específicas del modelo para proveedores que distinguen imágenes de entrada principales y referencias.
Archivo multipart de imagen de referencia para generación image-to-image. Úsalo cuando la imagen fuente sea privada o requiera cabeceras. No es un
file_id de /v1/files; este endpoint no acepta file_id.Número de imágenes a generar (1-10, según el modelo).
Tamaño de la imagen. Úsalo para familias de imágenes al estilo OpenAI y otros modelos que aceptan tamaños exactos en píxeles.Para
gpt-image-2, size acepta auto o WIDTHxHEIGHT. Las dimensiones personalizadas deben ser múltiplos de 16 en ambos lados, el lado más largo debe ser como máximo 3840px, la proporción lado largo/lado corto debe ser como máximo 3:1, y el total de píxeles debe estar entre 655,360 y 8,294,400. aspect_ratio y resolution no forman parte del detalles del modelo actual de TokenLab para gpt-image-2.Para las familias de imágenes de Google Gemini, size actúa como un alias de compatibilidad que se mapea al detalles del modelo de aspect_ratio y, cuando está disponible, resolution. Para esos modelos, prefiere enviar aspect_ratio directamente.Selector de relación de aspecto dependiente del modelo.Los valores comunes en familias de imágenes de Google incluyen
1:1, 16:9, 9:16, 3:2 y 2:3.Selector de resolución de salida dependiente del modelo.Se admite en
gemini-3.1-flash-image y gemini-3-pro-image para texto a imagen e image-edit, en nano-banana-pro para texto a imagen e image-to-image, y en nano-banana-2 solo para texto a imagen. Los valores típicos son 1k, 2k y 4k. No envíes este parámetro a familias de imagen Gemini que solo aceptan proporción salvo que el modelo lo documente explícitamente. Para los modelos de imagen xAI Grok Imagine, usa 1k o 2k.Calidad de imagen. Los modelos GPT Image como
gpt-image-2 usan auto, low, medium o high. Otras familias de imagen pueden usar valores específicos del proveedor; revisa los metadatos del modelo antes de enviar valores no predeterminados.Formato de respuesta:
url o b64_json. El valor predeterminado es url.Para solicitudes gpt-image-2 de Azure Official o compatibles con Azure, TokenLab recibe los datos de imagen como b64_json. Para solicitudes url, TokenLab sube cada imagen al CDN y devuelve data[].url. Si el almacenamiento CDN no está disponible o la subida falla, la solicitud falla en lugar de convertirse en una respuesta Base64. Para b64_json, devuelve el Base64 sin procesar.Establécelo en
true con gpt-image-2 o modelos de imagen oficiales FLUX/BFL para crear una tarea primero. Las tareas asíncronas completadas devuelven URL sin importar el response_format solicitado; usa solicitudes síncronas si necesitas b64_json.Selector de estilo opcional. Envíalo solo cuando el modelo seleccionado lo documente explícitamente; omítelo para
gpt-image-2 salvo que los metadatos del modelo indiquen lo contrario.Un identificador único para el usuario final.
Respuesta
Respuesta en línea
Marca de tiempo Unix de creación.
Array de imágenes generadas.Cada objeto contiene:
url(string): URL de la imagen generadab64_json(string): Imagen codificada en Base64, si se solicitarevised_prompt(string): Revisión opcional del prompt cuando el modelo seleccionado la devuelve
Respuesta de tarea asíncrona
Usaasync: true con gpt-image-2 o modelos de imagen oficiales FLUX/BFL para crear una tarea en lugar de esperar la imagen final en la solicitud de creación. La respuesta incluye status: "pending", task_id y poll_url. Consulta /v1/tasks/{task_id} hasta que la tarea llegue a completed o failed.
Las tareas asíncronas de imagen solo devuelven las URL finales. Si necesitas datos de imagen b64_json sin procesar, usa una solicitud síncrona.
Al crear la tarea puede reservarse el importe estimado. Las tareas completadas se cobran por uso real; las fallidas o vencidas liberan o reembolsan la reserva.
Marca de tiempo Unix de creación.
Identificador único de la tarea para el sondeo.
Estado inicial:
pending.URL relativa para sondear resultados, por ejemplo
/v1/tasks/{id}.Vacío mientras la tarea está pendiente. Las tareas de imagen completadas devuelven las URL de imágenes generadas en
data[].url.status: "pending", usa poll_url o GET /v1/tasks/{task_id} para recuperar el resultado.
Modelos disponibles
Estos son ejemplos actuales, no un catálogo fijo. ConsultaGET /v1/models?recommended_for=image o la página Models para ver disponibilidad y precios actualizados.
| Modelo | Tipo | Funciones |
|---|---|---|
gpt-image-2 | Inline o basado en tareas | Modelo GPT Image con precio por token y tamaños flexibles |
flux-pro | A menudo basado en tareas | Fotorrealista, alta calidad |
qwen-image-plus | A menudo basado en tareas | Buen renderizado de texto y seguimiento del prompt |
nano-banana-pro | A menudo basado en tareas | Flujos con imágenes de referencia y salida de alta resolución |
grok-imagine-image | A menudo basado en tareas | Generación de imagen xAI con selección de aspecto y resolución |
ideogram-v3 | A menudo basado en tareas | Buen renderizado de texto |
status: "pending", sigue poll_url y haz polling hasta que termine.
Manejo de respuestas basadas en tareas
Para los modelos de imagen, comprueba siempre si la respuesta contienestatus: "pending":