API de edición de imágenes de GPT en TokenLab: Endpoint correcto y formatos de entrada de imagen

La edición de imágenes es una de las partes más exigentes dentro de la superficie de un producto de IA: un usuario sube una foto, describe un cambio y espera un resultado. Las ediciones que utilizan varias imágenes de origen, un lienzo grande o un prompt más pesado tardan más de lo que una llamada HTTP sincrónica típica permite cómodamente. Esta guía cubre el endpoint correcto de TokenLab, los dos formatos de entrada de imagen admitidos, las ediciones con múltiples imágenes y la ruta asíncrona para solicitudes lentas.

El endpoint

La edición de imágenes reside en POST /v1/images/edits — ten en cuenta el plural edits. (Un error común es escribir /images/edit, que no es la ruta documentada).

El endpoint admite dos formatos de solicitud:

• Un flujo de subida multipart/form-data compatible con OpenAI.
• Una solicitud JSON que proporciona image_url, image_urls o referencias oficiales images[] para familias admitidas de imagen a imagen (image-to-image).

Todos los campos de solicitud y respuesta están documentados en la referencia de la API de Edit Image.

Lo que gpt-image-2 acepta aquí

• Subidas image en multipart.
• image_url o image_urls en JSON.
• Referencias oficiales images[], donde cada objeto contiene exactamente uno de image_url o file_id.
• Hasta 16 imágenes de origen por solicitud.

Algunas restricciones que conviene conocer antes de escribir código:

• Las ediciones con gpt-image-2 no aceptan resolution; utiliza size para las dimensiones de salida (ya sea auto o WIDTHxHEIGHT, con dimensiones en múltiplos de 16, el borde más largo como máximo de 3840px y una relación largo/corto de como máximo 3:1).
• background acepta auto u opaque; transparent no es compatible.
• input_fidelity no forma parte de los campos admitidos para gpt-image-2; enviarlo devuelve 400 unsupported_parameter.
• Para solicitudes JSON, proporciona exactamente uno de image_url, image_urls o images. Cada objeto de images[] debe contener exactamente uno de image_url o file_id. Los valores de file_id deben crearse primero a través de /v1/files.
• Las solicitudes con imagen de referencia de Nano Banana corresponden a /v1/images/generations con operation: "image-to-image" e image_urls — no a /v1/images/edits.

Subidas multipart frente a referencias de imagen en JSON

Ambas opciones funcionan para gpt-image-2. Elige la que coincida con el lugar donde ya se encuentran los bytes de tu imagen.

Multipart: utilízalo cuando la aplicación contenga el archivo, ya sea a partir de la subida de un usuario o de un recurso generado. Repite el campo image para enviar múltiples orígenes. Los archivos deben ser PNG, JPEG o WebP, de 50 MiB como máximo cada uno.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@subject.png" \
  -F "image=@background.png" \
  -F "prompt=Combine the subject with the new background." \
  -F "size=1024x1024"

URLs de imagen en JSON: utilízalo cuando las imágenes ya residan en una URL pública, o si las generaste en una solicitud anterior de TokenLab y ya tienes una URL.

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/subject.png"},
      {"image_url": "https://example.com/background.png"}
    ],
    "prompt": "Combine the subject with the new background.",
    "size": "1024x1024",
    "async": true
  }'

Las URLs remotas deben ser públicas bajo http/https, sin credenciales incrustadas ni fragmentos, y no deben resolver a localhost ni a rangos de IP privadas o reservadas. TokenLab obtiene los bytes y se los entrega al modelo como partes image en multipart. El límite por imagen es de 50 MiB; el límite agregado para imágenes obtenidas mediante URL en una solicitud es de 200 MiB; el tiempo de espera de obtención es de 30 segundos; se siguen hasta 3 redirecciones.

Ediciones con múltiples imágenes y sondeo asíncrono

Las ediciones con múltiples imágenes son el caso de uso más claro para async: true. Enviar varias imágenes con un conjunto de instrucciones complejo a través de una llamada sincrónica implica mantener una conexión abierta durante todo el tiempo que el modelo necesite. Establece async: true en gpt-image-2 (y en los modelos oficiales de edición FLUX/BFL) para recibir una tarea en su lugar:

{
  "created": 1706000000,
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "data": []
}

Sondea la poll_url devuelta, o recurre a GET /v1/tasks/{task_id}. Los estados son pending, processing, completed y failed. Una tarea de imagen completada devuelve data[].url. Verificar cada 3–5 segundos es suficiente; detente al llegar a un estado terminal en lugar de continuar sondeando.

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

Las tareas de edición asíncronas devuelven URLs de imagen finales independientemente del response_format solicitado. Si necesitas b64_json en bruto, utiliza una solicitud sincrónica.

La facturación puede reservar la cantidad estimada cuando se crea la tarea; una tarea completada se factura según el uso real, y una tarea fallida o con tiempo de espera agotado libera o reembolsa la reserva. Consulta Trabajos asíncronos y sondeo para ver el ciclo de vida completo, y Obtener estado de imagen para los campos de respuesta.

Cuándo usar cada modo

Usa async: true cuando:

• Estés enviando múltiples imágenes de origen en una sola solicitud.
• Tu prompt o conjunto de instrucciones sea lo suficientemente complejo como para que el tiempo de generación sea impredecible.
• Ejecutes ediciones en un trabajo en segundo plano, cola o proceso por lotes en lugar de una solicitud directa orientada al usuario.

Mantén el modo sincrónico cuando:

• Estés realizando una edición de una sola imagen con un prompt corto.
• Tu cliente prefiera fallar rápido en lugar de sondear.

Para llamadas sincrónicas, establece el tiempo de espera de tu cliente HTTP en al menos 120s; las solicitudes de alta resolución o alta calidad pueden tardar cerca de un minuto o más. Si la respuesta de creación aún devuelve status: "pending", task_id o poll_url, pasa al flujo de sondeo devuelto.

Errores de entrada esperados

Los fallos al obtener imágenes remotas se devuelven como errores de entrada antes de que comience la generación. Las URLs inaccesibles, los tiempos de espera agotados, las respuestas 403/404, los hosts privados o internos, las credenciales o fragmentos en la URL, el contenido que no sea imagen, los formatos no compatibles y las violaciones del límite de tamaño devuelven 400 o 413 e identifican la image_url o image_urls[n] infractora. Para recursos privados o protegidos por encabezados, sube archivos image multipart directamente, o crea referencias /v1/files y pásalas como images[].file_id.

Los modelos de edición de imágenes Grok Imagine de xAI (por ejemplo, grok-imagine-image y grok-imagine-image-quality) utilizan los mismos campos de entrada pero limitan las imágenes de origen a 3; enviar más devuelve 400 too_many_images.

Lista de verificación de integración

• Dirígete a POST /v1/images/edits y envía el model explícitamente.
• Elige subidas multipart o referencias JSON según dónde residan ya tus imágenes.
• Envía exactamente uno de image_url, image_urls o images[] en las solicitudes JSON; cada entrada de images[] tiene exactamente uno de image_url o file_id.
• Usa async: true para ediciones pesadas o con múltiples imágenes; sondea la poll_url devuelta hasta que la tarea alcance completed o failed.
• Establece los tiempos de espera del cliente en al menos 120 segundos para solicitudes sincrónicas y gestiona una respuesta pending siguiendo la poll_url.
• Si ocurre un tiempo de espera en el cliente, verifica si se creó una tarea antes de reintentar la solicitud de creación para evitar cobros duplicados.

Comienza ahora

Consulta GET /v1/models?recommended_for=image para ver los modelos de imagen actuales, luego abre la página de detalles de un modelo para confirmar sus operaciones y campos de solicitud admitidos antes de enviar una solicitud. Crea una clave de API desde la consola para probar el endpoint de edición con tus propias imágenes.