Guías de medios
Generación de imágenes
Genere o edite imágenes y gestione archivos terminados o tareas asíncronas
TokenLab admite text-to-image, image-to-image y edición de imágenes. Los parámetros difieren según el modelo, así que verifique los campos de solicitud del modelo seleccionado antes de enviar la petición.
Elegir un endpoint
| Lo que necesita | Endpoint | Usar cuando | No usar para |
|---|---|---|---|
| Text-to-image | POST /v1/images/generations | El usuario comienza solo con texto | Editar un archivo de imagen GPT existente |
| Image-to-image | POST /v1/images/generations | El modelo acepta operation: "image-to-image" y URLs de imagen | Modelos que requieren entrada de edición multipart |
| Edición de imagen | POST /v1/images/edits | Un modelo de edición compatible cambia una imagen existente | Generación de referencia estilo Nano Banana |
| Variación | POST /v1/images/variations | Una integración existente ya utiliza la API de variaciones | Una nueva función 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 |
Envíe siempre model; las APIs de imagen no eligen un modelo predeterminado por usted.
Elegir un modelo
Encuentre los modelos de imagen actuales con:
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
-H "Authorization: Bearer sk-your-api-key"Abra los detalles del modelo seleccionado para confirmar:
- La operación admitida, como
text-to-image,image-to-imageoimage-edit. - El endpoint de solicitud esperado por el modelo.
- Cómo enviar referencias:
image_url,image_urls,reference_image_urls, multipartimageo JSONimages[]. - Si el modelo acepta
size,aspect_ratio,resolution,quality,background,output_formatoresponse_format.
Campos específicos del modelo
- Las solicitudes estilo
gpt-image-2utilizansize,qualityy campos de edición similares a OpenAI. Para la generación y ediciones con este modelo,backgroundaceptaautouopaque;transparentno es compatible. Omita los campos opcionales para usar los valores predeterminados automáticos. - Las familias de imágenes Gemini y Nano Banana generalmente usan
aspect_ratio; solo envíeresolutioncuando los detalles del modelo lo expongan. En modelos con niveles de resolución, unsizede1K,2Ko4Kse envía comoresolution; un nivel que sea diferente deresolutionserá rechazado. - La función image-to-image de Nano Banana pertenece a
/v1/images/generationsconoperation: "image-to-image"y URLs de imágenes de referencia. /v1/images/generationsno aceptaimages[]ofile_idde nivel superior; esas son formas de flujo de edición.- Las referencias de imágenes remotas deben ser URLs
httpohttpspúblicas. No envíe URLs de redes privadas, credenciales integradas, fragmentos de URL o URLs firmadas que puedan caducar antes de que comience el procesamiento.
Ejemplo de text-to-image
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": "A clean product photo of a ceramic coffee cup on a walnut desk",
"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-2",
"operation": "image-to-image",
"prompt": "Keep the product shape, change the background to a bright studio setup",
"image_urls": ["https://example.com/input/product.png"],
"aspect_ratio": "1:1"
}'Obtener la imagen
Las respuestas de imagen pueden ser síncronas o asíncronas:
- Las respuestas síncronas devuelven
data[]final conurlob64_json. - Las respuestas asíncronas devuelven
id,task_id,statusy, por lo general,poll_url. Envíe"async": trueen un modelo que admita ejecución asíncrona pública para obtener una tarea en lugar de esperar la imagen. - Para verificar una tarea asíncrona, llame a
GET /v1/tasks/{id}con elidotask_iddevuelto. - Utilice una solicitud síncrona cuando necesite
b64_json; los resultados de imagen asíncronos utilizan URLs.
Las URLs de resultados de imagen son URLs de resultados multimedia de TokenLab que permanecen válidas durante 30 días. media_retention.items informa el estado de guardado de cada elemento y expires_at; la respuesta puede omitir media_retention cuando el estado de guardado no se conoce a tiempo, y la URL seguirá funcionando. Los resultados Base64 en línea están fuera de esta retención de copia de URL. Guardar manualmente una imagen en la Media Library le otorga un ciclo de vida separado. Consulte Retención de datos.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Conserve la URL de la imagen devuelta, el ID de la tarea, el modelo y su propio ID de usuario/trabajo. No continúe realizando sondeos después de un estado terminal.
Antes del lanzamiento
- Valide las entradas del usuario antes de llamar a TokenLab: longitud del prompt, recuento de imágenes, accesibilidad de la URL y tipo de archivo.
- Establezca los tiempos de espera (timeouts) de HTTP lo suficientemente altos para solicitudes síncronas de alta resolución. Use
async: truedonde el modelo lo admita para trabajos largos. - Almacene
request_id,task_id,poll_url, el modelo, el endpoint y los nombres de los campos enviados. - Cuando una solicitud de imagen devuelve una tarea, una
Idempotency-Keyhace que la solicitud de creación sea segura para reintentar: después de un tiempo de espera del cliente, envíe la misma solicitud con la misma clave para obtener esa tarea. Para una solicitud que devuelve la imagen directamente, un reintento con la misma clave puede devolver un estado de tarea en lugar de la imagen, o un409conidempotent_response_not_replayable. Sin una clave, verifique si se creó una tarea antes de volver a intentarlo. - Utilice Usage y
billing_transaction_idpara el cargo final.
Errores comunes
| Síntoma | Causa probable | Solución |
|---|---|---|
400 con param: "model" | Falta el modelo explícito | Consulte /v1/models?recommended_for=image y envíe model |
| Campo no admitido | El campo no está documentado para 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 síncrono para salida base64 |
| Imagen de referencia rechazada | Endpoint incorrecto o URL privada/caducada | Coincida con la forma de referencia documentada del modelo y use URLs accesibles |
Referencia de la 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 la imagen |
| Obtener estado de tarea | Obtener estado de la tarea |