Generación de Imágenes

TokenLab admite texto a imagen, imagen a imagen y edición de imágenes a través de endpoints de imagen públicos. Los modelos de imagen no comparten un conjunto de parámetros universal, por lo que los clientes de producción deben primero elegir el endpoint, luego elegir el modelo y luego enviar solo los campos admitidos por ese modelo.

Cuándo Usar Cada Endpoint

Flujo de trabajo del usuario	Endpoint	Usar cuando	Evitar cuando
Texto a imagen	`POST /v1/images/generations`	El usuario comienza solo con un aviso	Necesita un flujo de edición de imagen GPT oficial
Imagen a imagen	`POST /v1/images/generations`	Los documentos del modelo hacen referencia a imágenes a través de `operation: "image-to-image"` más `image_url`, `image_urls` o `reference_image_urls`	El modelo espera entrada de edición multipart
Edición de imagen	`POST /v1/images/edits`	Está editando una imagen existente con un modelo de edición compatible, como un modelo de la familia GPT Image	Está utilizando generación de imagen a imagen estilo Nano Banana
Variación	`POST /v1/images/variations`	Mantiene una integración compatible con variaciones heredadas	Está construyendo un nuevo flujo de trabajo de imagen de referencia
Estado	`GET /v1/tasks/{id}`	Una respuesta de creación devuelve `task_id`, `status: "pending"` o `poll_url`	La respuesta de creación ya contiene `data[]` final

Siempre envíe model. Los endpoints de imagen intencionalmente no dependen de un modelo predeterminado implícito histórico para el tráfico de producción.

Elegir Un Modelo

Comience con el descubrimiento del modelo, luego inspeccione el contrato de TokenLab del modelo seleccionado:

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

Para modelos que no son de chat, la respuesta de la lista puede incluir tokenlab.public_contract_summary. Las páginas de detalles del modelo pueden exponer el tokenlab.public_contract más completo. Use esos campos para confirmar:

La operación admitida, como text-to-image, image-to-image o image-edit.
El endpoint de solicitud esperado por el modelo.
Qué forma usar para referencias, como image_url, image_urls, reference_image_urls, multipart image o JSON images[].
Si el modelo acepta size, aspect_ratio, resolution, quality, background, output_format o response_format.

Reglas de Forma de Solicitud

Las solicitudes estilo gpt-image-2 utilizan campos de size, quality y edición similares a OpenAI. Deje fuera los campos opcionales cuando desee que el modelo o TokenLab utilicen valores predeterminados automáticos.
Las familias de imágenes Gemini y Nano Banana generalmente utilizan aspect_ratio; solo envíe resolution cuando el contrato del modelo lo exponga.
La generación de imagen a imagen de Nano Banana pertenece a /v1/images/generations con operation: "image-to-image" y URLs de imágenes de referencia.
/v1/images/generations no acepta images[] o file_id de nivel superior; esos son formas de flujo de edición.
Las referencias de imágenes remotas deben ser URLs públicas http o https. No envíe URLs de red privada, credenciales incrustadas, fragmentos de URL o URLs firmadas que puedan expirar antes de que comience el procesamiento.

Ejemplo de Texto a Imagen

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Una foto de producto limpia de una taza de café de cerámica sobre un escritorio de nogal",
    "size": "1024x1024",
    "response_format": "url"
  }'

Ejemplo de Imagen de Referencia

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "operation": "image-to-image",
    "prompt": "Mantén la forma del producto, cambia el fondo a un entorno de estudio brillante",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

Manejo de Resultados

Las respuestas de imagen pueden ser sincrónicas o asíncronas:

Las respuestas sincrónicas devuelven data[] final con url o b64_json.
Las respuestas asíncronas devuelven id, task_id, status y generalmente poll_url.
Prefiera poll_url cuando esté presente. Si necesita una ruta fija, consulte GET /v1/tasks/{id}.
Use solicitudes sincrónicas cuando necesite específicamente b64_json; los resultados de imagen asíncronos están orientados a URL.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Conserve la URL de imagen devuelta, el ID de tarea, el modelo y su propio ID de usuario/trabajo. No siga consultando después de un estado terminal.

Lista de Verificación de Producción

Valide las entradas del usuario antes de llamar a TokenLab: longitud del aviso, cantidad de imágenes, accesibilidad de URL y tipo de archivo.
Establezca los tiempos de espera HTTP lo suficientemente altos para solicitudes sincrónicas de alta resolución. Use el modo asíncrono donde esté disponible para trabajos largos.
Almacene request_id, task_id, poll_url, modelo, endpoint y forma de solicitud saneada para soporte.
En caso de tiempo de espera del cliente, verifique si se creó una tarea antes de volver a intentar la solicitud de creación.
Concilie el costo con los registros de uso y billing_transaction_id cuando esté presente, no con los IDs de tarea del proveedor.

Errores Comunes

Síntoma	Causa probable	Solución
`400` con `param: "model"`	Modelo explícito faltante	Consulte `/v1/models?recommended_for=image` y envíe `model`
Campo no soportado	El campo no está en el contrato público de ese modelo	Elimine el campo o elija un modelo/endpoint que lo documente
No hay `b64_json` en el resultado asíncrono	Las tareas de imagen asíncronas devuelven resultados orientados a URL	Use el modo sincrónico para salida base64
Imagen de referencia rechazada	Endpoint incorrecto o URL privada/expirada	Coincida con la forma de referencia documentada del modelo y use URLs accesibles

Referencia de API

Tema	Referencia
Crear Imagen	Crear Imagen
Editar Imagen	Editar Imagen
Crear Variación de Imagen	Crear Variación de Imagen
Obtener Estado de Imagen	Obtener Estado de Imagen
Obtener Estado de Tarea	Obtener Estado de Tarea

​Cuándo Usar Cada Endpoint

​Elegir Un Modelo

​Reglas de Forma de Solicitud

​Ejemplo de Texto a Imagen

​Ejemplo de Imagen de Referencia

​Manejo de Resultados

​Lista de Verificación de Producción

​Errores Comunes

​Referencia de API