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 EndpointCopy Anchor Link

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 ModeloCopy Anchor Link

Comience con el descubrimiento del modelo, luego inspeccione el detalles del modelo en 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 GET /v1/models. Las páginas de detalles del modelo pueden exponer el GET /v1/models/{model} 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 SolicitudCopy Anchor Link

• Las solicitudes estilo gpt-image-2 utilizan campos de size, quality y edición similares a OpenAI. Para generación y edición, background acepta auto u opaque; transparent no es compatible. 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 detalle 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 ImagenCopy Anchor Link

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 ReferenciaCopy Anchor Link

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "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 ResultadosCopy Anchor Link

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ónCopy Anchor Link

• 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 ComunesCopy Anchor Link

Referencia de APICopy Anchor Link