Imágenes
Editar imagen
Edita una imagen a partir de un prompt y una imagen de origen
Descripción general
Crea una imagen editada o extendida a partir de una imagen original y un prompt.
Este endpoint admite tanto:
- el flujo de carga
multipart/form-datacompatible con OpenAI documentado a continuación - solicitudes JSON que proporcionan
image_url,image_urlso referencias oficialesimagespara familias de imagen a imagen compatibles
gpt-image-2 es compatible aquí. Acepta cargas image multipart, image_url / image_urls en JSON y referencias oficiales images[] (image_url o file_id), con hasta 16 imágenes de origen. Cree valores file_id a través de /v1/files primero. Establezca async: true para devolver una tarea primero; los modelos de edición oficiales FLUX/BFL también utilizan el mismo flujo de sondeo de tareas.
Las ediciones de gpt-image-2 no aceptan resolution; utilice size para las dimensiones de salida. background acepta auto u opaque; transparent no es compatible. Para ediciones con múltiples imágenes o de alta latencia, prefiera async: true y sondee la tarea devuelta.
Las solicitudes de imagen de referencia de Nano Banana (nano-banana-2, nano-banana-2.1, nano-banana-2-lite y nano-banana-pro) se exponen en /v1/images/generations con operation: "image-to-image" y image_urls, no en este endpoint /v1/images/edits. Las solicitudes de edición de imagen para nano-banana-2, nano-banana-2.1, nano-banana-2-lite y nano-banana-pro también utilizan /v1/images/generations, con operation: "image-edit".
gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3.1-flash-lite-image y gemini-3-pro-image utilizan este endpoint para la edición de imágenes. Sus solicitudes de imagen a imagen utilizan /v1/images/generations con operation: "image-to-image".
Los modelos de edición de imágenes xAI Grok Imagine (grok-imagine-image, grok-imagine-image-quality y el legado grok-imagine-image-pro) aceptan como máximo 3 imágenes de origen. Las solicitudes con más de 3 imágenes de origen fallan en la validación de entrada con 400 too_many_images.
input_fidelity no forma parte de los campos admitidos actualmente por TokenLab para gpt-image-2; omítalo o la solicitud devolverá 400 unsupported_parameter.
Cuerpo de la solicitud
Tiempo de espera de solicitud síncrona: Algunas solicitudes de imagen devuelven la imagen final en línea y esperan a que termine la generación. Las solicitudes de alta resolución o alta calidad pueden tardar cerca de un minuto o más, así que establezca el tiempo de espera de su cliente HTTP en al menos 120s. Si la respuesta de creación incluye status: "pending", task_id o poll_url, siga la poll_url devuelta en su lugar.
URLs de imágenes remotas: cuando se necesita una entrada multipart, TokenLab obtiene image_url, image_urls o images[].image_url en formato JSON y envía los bytes como partes image multipart. Las URLs deben ser http/https públicas, sin credenciales o fragmentos incrustados, y no deben resolverse a localhost, rangos de IP privados o reservados; cada redirección se verifica nuevamente. La carga útil obtenida debe ser una imagen real PNG, JPEG o WebP. Los límites son 50 MiB por imagen, 200 MiB en total para imágenes obtenidas por URL en una sola solicitud, 30s de tiempo de espera de obtención y hasta 3 redirecciones.
Para solicitudes JSON, proporcione exactamente uno de image_url, image_urls o images. Cada objeto images[] debe contener exactamente uno de image_url o file_id. El límite agregado de 200 MiB incluye todas las imágenes de origen y la máscara.
Imágenes de origen multipart. Repita image para proporcionar múltiples fuentes de GPT Image. Los archivos deben ser PNG, JPEG o WebP, hasta 16 imágenes de origen y 50 MiB cada una. Los modelos de edición xAI Grok Imagine utilizan los mismos campos de entrada pero limitan las imágenes de origen a 3.
Una descripción textual de la edición deseada.
Una imagen adicional cuyas áreas totalmente transparentes indican dónde debe editarse la imagen. Debe ser un archivo PNG válido, de menos de 50 MiB y tener las mismas dimensiones que image.
Para solicitudes JSON, mask también puede ser un objeto con exactamente uno de image_url o file_id; los valores file_id deben provenir de /v1/files y permanecer vinculados a la misma configuración de edición de imagen.
El modelo a utilizar para las ediciones de imagen. Utilice gpt-image-2 para ediciones de GPT Image, u otro modelo de edición de imagen actual devuelto por GET /v1/models?recommended_for=image.
1Número de imágenes a generar (1-10, dependiendo del modelo).
El tamaño de la imagen generada. Para gpt-image-2, utilice auto o WIDTHxHEIGHT; las dimensiones deben ser múltiplos de 16, el borde más largo como máximo 3840px, la relación largo/corto como máximo 3:1 y el total de píxeles entre 655,360 y 8,294,400.
Para gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image y gemini-3.1-flash-lite-image, size acepta un tamaño de salida de la tabla de tamaños del modelo o un nivel de resolución: 1K, 2K o 4K. TokenLab envía un nivel como resolution. Un nivel que el modelo no admite, o un nivel que es diferente de resolution, devuelve 400 con el código invalid_image_size_contract. La forma recomendada es aspect_ratio con resolution.
Cómo se devuelven las imágenes: url o b64_json.
- Omitido: cuando el modelo devuelve bytes de imagen, cada imagen está en
data[].b64_json, y también endata[].urlcuando TokenLab la almacenó. Cuando el modelo devuelve un enlace, cada imagen está endata[].url. url: cada imagen está solo endata[].url.b64_json: cada imagen está solo endata[].b64_jsoncomo datos Base64.
Los enlaces son URLs de resultados multimedia de TokenLab. Permanecen válidos durante 30 días. Consulte Retención de datos.
falseEstablezca en true con gpt-image-2 o modelos de edición oficiales FLUX/BFL para devolver una tarea antes de que la imagen final esté lista. Las ediciones asíncronas completadas devuelven URLs independientemente del response_format solicitado; utilice solicitudes síncronas cuando necesite b64_json.
Un identificador único que representa a su usuario final para el monitoreo de abusos.
Respuesta
Marca de tiempo Unix de cuándo se crearon las imágenes.
Matriz de imágenes generadas.
Cada objeto contiene:
url(string): URL de resultado multimedia de TokenLab de la imagen editada, válida por 30 días. No presente cuandoresponse_formatesb64_json. Cuando se omiteresponse_format, falta si TokenLab no pudo almacenar la imagen.b64_json(string): Datos de imagen en Base64. Presente cuandoresponse_formatesb64_json, o cuando se omite y el modelo devuelve bytes de imagen.
Respuesta de tarea asíncrona
Establezca async: true con gpt-image-2 o modelos de edición oficiales FLUX/BFL para crear una tarea en lugar de esperar la imagen editada en la solicitud. La respuesta incluye status: "pending", task_id y poll_url. Sondee /v1/tasks/{task_id} hasta que la tarea llegue a completed o failed.
Las tareas de edición asíncronas devuelven solo URLs de imágenes finales. Si necesita datos de imagen b64_json sin procesar, utilice una solicitud síncrona.
La facturación puede reservar el monto estimado cuando se crea la tarea. Las tareas completadas se facturan según el uso real, y las tareas fallidas o que excedieron el tiempo de espera se liberan o reembolsan.
Solicitud
curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
-H "Authorization: Bearer sk-your-api-key" \
-F "model=gpt-image-2" \
-F "image=@sunlit_lounge.png" \
-F "mask=@mask.png" \
-F "prompt=A sunlit indoor lounge area with a pool" \
-F "n=1" \
-F "size=1024x1024"Respuesta
{
"created": 1706000000,
"data": [
{
"url": "https://..."
}
]
}Notas
Los fallos en la obtención de imágenes remotas se devuelven como errores de entrada antes de que comience la generación. Las URLs inalcanzables, los tiempos de espera, las respuestas 403/404, los hosts privados/internos, las credenciales o fragmentos en la URL, el contenido que no es una imagen, los formatos no admitidos y las violaciones de límites de tamaño devuelven 400 o 413 e identifican la entrada image_url / image_urls[n]. Para activos privados o protegidos por encabezados, cargue archivos image multipart directamente o cree referencias /v1/files.
Hy Image 3.5 Preview crea imágenes cuadradas de 1024 píxeles a partir de texto y edita imágenes de referencia utilizando instrucciones escritas. Es útil para esbozar visuales y refinar una composición.
{
"model": "hy-image-v3.5-preview",
"prompt": "Change the table to pale blue",
"image_url": "https://example.com/reference.png",
"size": "1024x1024",
"n": 1,
"response_format": "url"
}Autorización
BearerAuth Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.
Ubicación: header
Encabezados
Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.
Valores permitidos
- "auto"
- "verified"
- "official"
Respuesta
application/json
application/json
application/json
application/json
application/json
application/json