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 necesitaEndpointUsar cuandoNo usar para
Text-to-imagePOST /v1/images/generationsEl usuario comienza solo con textoEditar un archivo de imagen GPT existente
Image-to-imagePOST /v1/images/generationsEl modelo acepta operation: "image-to-image" y URLs de imagenModelos que requieren entrada de edición multipart
Edición de imagenPOST /v1/images/editsUn modelo de edición compatible cambia una imagen existenteGeneración de referencia estilo Nano Banana
VariaciónPOST /v1/images/variationsUna integración existente ya utiliza la API de variacionesUna nueva función de imagen de referencia
EstadoGET /v1/tasks/{id}Una respuesta de creación devuelve task_id, status: "pending" o poll_urlLa 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-image o image-edit.
  • El endpoint de solicitud esperado por el modelo.
  • Cómo enviar referencias: 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.

Campos específicos del modelo

  • Las solicitudes estilo gpt-image-2 utilizan size, quality y campos de edición similares a OpenAI. Para la generación y ediciones con este modelo, background acepta auto u opaque; transparent no 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íe resolution cuando los detalles del modelo lo expongan. En modelos con niveles de resolución, un size de 1K, 2K o 4K se envía como resolution; un nivel que sea diferente de resolution será rechazado.
  • La función image-to-image 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; esas son formas de flujo de edición.
  • Las referencias de imágenes remotas deben ser URLs http o https pú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 con url o b64_json.
  • Las respuestas asíncronas devuelven id, task_id, status y, por lo general, poll_url. Envíe "async": true en 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 el id o task_id devuelto.
  • 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: true donde 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-Key hace 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 un 409 con idempotent_response_not_replayable. Sin una clave, verifique si se creó una tarea antes de volver a intentarlo.
  • Utilice Usage y billing_transaction_id para el cargo final.

Errores comunes

SíntomaCausa probableSolución
400 con param: "model"Falta el modelo explícitoConsulte /v1/models?recommended_for=image y envíe model
Campo no admitidoEl campo no está documentado para ese modeloElimine el campo o elija un modelo/endpoint que lo documente
No hay b64_json en el resultado asíncronoLas tareas de imagen asíncronas devuelven resultados orientados a URLUse el modo síncrono para salida base64
Imagen de referencia rechazadaEndpoint incorrecto o URL privada/caducadaCoincida con la forma de referencia documentada del modelo y use URLs accesibles

Referencia de la API

TemaReferencia
Crear imagenCrear imagen
Editar imagenEditar imagen
Crear variación de imagenCrear variación de imagen
Obtener estado de imagenObtener estado de la imagen
Obtener estado de tareaObtener estado de la tarea

En esta página