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 ampliada a partir de una imagen original y un prompt.
Este endpoint admite tanto:
- el flujo de subida
multipart/form-datacompatible con OpenAI documentado a continuación - solicitudes JSON que proporcionan
image_url,image_urlso referencias oficiales aimagespara familias image-to-image compatibles
gpt-image-2 es compatible aquí. Acepta subidas 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 primero una tarea; cada modelo que liste async entre sus parámetros admitidos, como gpt-image-2 y los modelos de edición FLUX, utiliza el mismo flujo de sondeo de tareas.
Las ediciones de gpt-image-2 no aceptan resolution; use 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 imágenes de referencia de Nano Banana (nano-banana-2, nano-banana-2.1, nano-banana-2-lite y nano-banana-pro) están expuestas en /v1/images/generations con operation: "image-to-image" e image_urls, no en este endpoint /v1/images/edits. Las solicitudes de edición de imágenes 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 image-edit. Sus solicitudes image-to-image utilizan /v1/images/generations con operation: "image-to-image".
Los modelos de edición de imágenes xAI Grok Imagine aceptan un número limitado de imágenes de origen: grok-imagine-image-2.0 acepta como máximo 5 y grok-imagine-image acepta como máximo 3. Las solicitudes con más imágenes de origen de las que el modelo acepta fallan en la validación de entrada con 400 too_many_images. Sus solicitudes image-to-image también utilizan este endpoint.
Los detalles de cada modelo (GET /v1/models/{model}, consulte Get Model) indican el endpoint para cada operación en tokenlab.request_format_summary.request_endpoint_by_operation, así como los campos y límites aceptados en tokenlab.request_format_details.operation_constraints. Una operación enviada al endpoint incorrecto devuelve 400 unsupported_endpoint.
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 para solicitudes síncronas: Algunas solicitudes de imágenes devuelven la imagen final en línea y esperan a que finalice la generación. Las solicitudes de alta resolución o alta calidad pueden tardar cerca de un minuto o más, por lo que debe configurar 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, sondee GET /v1/tasks/{task_id} en su lugar.
URL de imágenes remotas: cuando se necesita una entrada multipart, TokenLab obtiene image_url, image_urls o images[].image_url en JSON y envía los bytes como partes multipart image. Las URL deben ser públicas de tipo http/https, sin credenciales ni fragmentos incrustados, y no deben resolver a localhost ni a rangos de IP privados o reservados; cada redirección se comprueba nuevamente. La carga útil obtenida debe ser una imagen PNG, JPEG o WebP real. Los límites son de 50 MiB por imagen, 200 MiB en total para imágenes obtenidas mediante URL en una sola solicitud, un tiempo de espera de obtención de 30s 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 acumulado 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, con hasta 16 imágenes de origen y 50 MiB cada una. Los modelos de edición de xAI Grok Imagine utilizan los mismos campos de entrada pero limitan las imágenes de origen: como máximo 5 para grok-imagine-image-2.0 y como máximo 3 para los demás modelos de edición de xAI.
Una descripción en texto de la edición deseada, de hasta 32.000 caracteres. Obligatorio para cada modelo cuyos detalles listen prompt. Las herramientas sin prompt, como stability-upscale-fast, se llaman sin este.
Una imagen adicional cuyas áreas completamente transparentes indican dónde debe editarse la imagen. Debe ser un archivo PNG válido, de menos de 50 MiB y con 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 de file_id deben proceder de /v1/files y permanecer vinculados a la misma configuración de image-edit.
El modelo que se utilizará para las ediciones de imágenes. Use gpt-image-2 para ediciones de GPT Image, u otro modelo actual de edición de imágenes devuelto por GET /v1/models?recommended_for=image.
1Número de imágenes a generar (1-10, depende del modelo).
El tamaño de la imagen generada. Para gpt-image-2, use auto o WIDTHxHEIGHT; las dimensiones deben ser múltiplos de 16, el lado más largo como máximo de 3840px, la relación lado largo/corto como máximo de 3:1 y los píxeles totales 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 admita, o un nivel que sea 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 ha almacenado. Cuando el modelo devuelve un enlace, cada imagen está endata[].url. url: cada imagen está únicamente endata[].url.b64_json: cada imagen está únicamente endata[].b64_jsoncomo datos en Base64.
Los enlaces son URL de resultados multimedia de TokenLab. Permanecen válidos durante 30 días. Consulte Retención de datos.
falseEstablézcalo en true para devolver una tarea antes de que la imagen final esté lista. Solo los modelos que listen async entre sus parámetros admitidos lo aceptan, por ejemplo gpt-image-2; para cualquier otro modelo, la solicitud devuelve 400 unsupported_async_mode. Las ediciones asíncronas completadas devuelven URL independientemente del response_format solicitado; utilice solicitudes síncronas cuando necesite b64_json.
Un identificador único que representa a su usuario final para la supervisión de abusos.
Respuesta
Marca de tiempo Unix de cuándo se crearon las imágenes.
Array de imágenes generadas.
Cada objeto contiene:
url(string): URL de resultado multimedia de TokenLab de la imagen editada, válida durante 30 días. No está presente cuandoresponse_formatesb64_json. Cuando se omiteresponse_format, no aparece 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.
Recuentos de tokens (input_tokens, output_tokens, total_tokens y sus detalles) para modelos con precios por token como gpt-image-2, cuando estén disponibles.
Respuesta de tarea asíncrona
Establezca async: true en un modelo compatible 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 alcance el estado completed o failed.
Las tareas de edición asíncronas solo devuelven URL de imagen final. Si necesita datos de imagen en bruto b64_json, utilice una solicitud síncrona.
La facturación puede reservar el importe estimado al crear la tarea. Las tareas completadas se facturan según el uso real, y las tareas fallidas o con tiempo de espera agotado se liberan o se 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 al obtener imágenes remotas se devuelven como errores de entrada antes de que comience la generación. Las URL inaccesibles, los tiempos de espera agotados, las respuestas 403/404, los hosts privados/internos, las credenciales o fragmentos en la URL, el contenido que no sea imagen, los formatos no admitidos y las infracciones de límites de tamaño devuelven 400 o 413 e identifican la entrada image_url / image_urls[n]. El código es invalid_image_url, unsupported_image_content_type, too_many_images, o, con 413, image_too_large o image_input_too_large. Para recursos privados o protegidos mediante encabezados, suba archivos image multipart directamente o cree referencias con /v1/files.
Envíe un encabezado Idempotency-Key para reintentar una solicitud de forma segura después de un tiempo de espera agotado; consulte Reintentar de forma segura con una clave de idempotencia.
Hy Image 3.5 Preview edita una imagen de referencia a partir de una instrucción escrita. Solo admite size 1024x1024 y n 1:
{
"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"
Clave opcional que hace que una solicitud de imagen sea segura para reintentar si la solicitud creó una tarea. Envíe un nuevo valor único, como un UUID, para cada solicitud. Un reintento con la misma clave y el mismo cuerpo devuelve entonces esa tarea y no crea, envía ni cobra una segunda 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 409 con idempotent_response_not_replayable. Un cuerpo diferente con una clave que ya fue aceptada se rechaza; el código de estado y el código de error para ese caso no están garantizados. Se ignora una clave de más de 255 caracteres y la solicitud no tendrá protección de idempotencia. Consulte Reintente de forma segura con una clave de idempotencia.
1 <= length <= 255Respuesta
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json