De imagen a imagen (edición de imágenes)

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Use this reference image to create a more polished square product hero image while preserving the main style.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image=@reference.png'

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)",
      "revised_prompt": "<string>"
    }
  ]
}

POST

images

edits

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Use this reference image to create a more polished square product hero image while preserving the main style.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image=@reference.png'

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)",
      "revised_prompt": "<string>"
    }
  ]
}

POST /v1/images/edits El endpoint de imagen a imagen usa un cuerpo de solicitud multipart/form-data. Sube una o varias imágenes de referencia y envía el prompt y los parámetros como campos de formulario.

Usa https://bettertoken.ai/v1 como Base URL. Envía tu BetterToken API Key mediante Authorization: Bearer YOUR_API_KEY.

Puedes completar los campos del formulario y subir imágenes de referencia en el Playground de la derecha. Después, envía la solicitud directamente a https://bettertoken.ai/v1/images/edits.

No uses un cuerpo JSON normal para las solicitudes de imagen a imagen. Envía los campos de texto y archivo mediante multipart/form-data.

Valores recomendados

Envía estos campos de forma explícita en cada solicitud:

model=gpt-image-2
n=1
response_format=b64_json
output_format=png

Usa image para una sola imagen de referencia. Para varias imágenes de referencia, repite el campo image[].

Una imagen de referencia

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Use this reference image to create a more polished square product hero image while keeping the main style consistent.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image=@reference.png'

Varias imágenes de referencia

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Combine these reference images into one consistent promotional poster.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image[]=@reference-1.png' \
  -F 'image[]=@reference-2.jpg' \
  -F 'image[]=@reference-3.png'

Edita una zona seleccionada con una máscara

Añade el campo de archivo opcional mask cuando quieras orientar la edición a una zona seleccionada. El endpoint actual de BetterToken admite un solo archivo en mask. No envíes campos mask[] repetidos.

La imagen original y la máscara deben tener el mismo formato y las mismas dimensiones en píxeles. Cada archivo debe pesar menos de 50 MB. Para obtener la máxima compatibilidad, usa PNG con canal Alpha en ambos archivos.
La máscara debe incluir un canal Alpha. Los píxeles totalmente transparentes (Alpha 0) marcan la zona que el modelo puede volver a dibujar. Los píxeles totalmente opacos (Alpha 255) indican al modelo que conserve esa zona.
Una imagen RGB normal en blanco y negro no es una máscara válida si no contiene realmente un canal Alpha.
Si envías varios campos image[], la máscara se aplica a la primera imagen de entrada.
La máscara orienta al modelo. No garantiza que los píxeles fuera de la zona transparente permanezcan exactamente iguales.

curl 'https://bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -F 'model=gpt-image-2' \
  -F 'prompt=Replace only the masked area with a blue circle. Preserve everything else.' \
  -F 'n=1' \
  -F 'size=1024x1024' \
  -F 'response_format=b64_json' \
  -F 'output_format=png' \
  -F 'image=@original.png' \
  -F 'mask=@mask.png'

Edición con máscara en Python

Abre ambos archivos en una sola sentencia with para que Python los cierre después de la solicitud:

import requests

url = "https://bettertoken.ai/v1/images/edits"
headers = {"Authorization": "Bearer sk-***REDACTED***"}
data = {
    "model": "gpt-image-2",
    "prompt": "Replace only the masked area with a blue circle. Preserve everything else.",
    "n": "1",
    "size": "1024x1024",
    "response_format": "b64_json",
    "output_format": "png",
}

with open("original.png", "rb") as image_file, open("mask.png", "rb") as mask_file:
    files = {
        "image": ("original.png", image_file, "image/png"),
        "mask": ("mask.png", mask_file, "image/png"),
    }
    response = requests.post(url, headers=headers, data=data, files=files, timeout=300)

response.raise_for_status()
result = response.json()

Comprueba los archivos antes de subirlos

Esta comprobación mínima con Pillow verifica los requisitos de formato, dimensiones y canal Alpha. Para una máscara local típica, también muestra una advertencia si el canal Alpha no incluye zonas totalmente transparentes y opacas:

from pathlib import Path
from PIL import Image

image_path = Path("original.png")
mask_path = Path("mask.png")

if image_path.stat().st_size >= 50 * 1024 * 1024 or mask_path.stat().st_size >= 50 * 1024 * 1024:
    raise ValueError("Each file must be smaller than 50 MB")

with Image.open(image_path) as image, Image.open(mask_path) as mask:
    if image.format != mask.format:
        raise ValueError("The image and mask formats must match")
    if image.size != mask.size:
        raise ValueError("The image and mask dimensions must match")
    if "A" not in mask.getbands():
        raise ValueError("The mask must contain an Alpha channel")
    alpha_min, alpha_max = mask.getchannel("A").getextrema()
    if alpha_min > 0 or alpha_max < 255:
        print("Warning: for a typical local mask, include fully transparent and fully opaque areas")

Ejemplo con Python

import requests

url = "https://bettertoken.ai/v1/images/edits"
headers = {
    "Authorization": "Bearer sk-***REDACTED***",
}

data = {
    "model": "gpt-image-2",
    "prompt": "Use this reference image to create a more polished square product hero image while keeping the main style consistent.",
    "n": "1",
    "size": "1024x1024",
    "response_format": "b64_json",
    "output_format": "png",
}

with open("reference.png", "rb") as image_file:
    files = {
        "image": ("reference.png", image_file, "image/png"),
    }
    response = requests.post(url, headers=headers, data=data, files=files, timeout=300)

response.raise_for_status()
result = response.json()
b64_json = result["data"][0]["b64_json"]

Tamaños recomendados

`size`	Proporción	Uso
`auto`	Automática	Selección automática del tamaño
`1024x1024`	`1:1`	Imágenes cuadradas, avatares, portadas y recursos
`1536x1024`	`3:2`	Pósteres horizontales, banners y escenas
`1024x1536`	`2:3`	Portadas móviles y pósteres verticales
`1536x1152`	`4:3`	Imágenes horizontales estándar, productos y gráficos de contenido
`1152x1536`	`3:4`	Imágenes verticales estándar, portadas móviles y pósteres verticales
`2048x2048`	`1:1`	Imágenes cuadradas de alta resolución
`2048x1152`	`16:9`	Imágenes horizontales de alta resolución
`3840x2160`	`16:9`	Imágenes horizontales 4K
`2160x3840`	`9:16`	Imágenes verticales 4K

size representa la proporción y el nivel de tamaño esperados. El servidor puede asignar o ajustar los píxeles devueltos. Usa las dimensiones de la imagen decodificada en lugar de recortar la salida por la fuerza al valor solicitado.

Guarda la imagen

Una respuesta correcta sigue la estructura de imagen compatible con OpenAI:

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)"
    }
  ]
}

Lee data[0].b64_json y guárdalo como contenido de imagen en base64. Define siempre output_format: "png" para poder guardar la imagen decodificada como .png.

Flujo de respuesta

Este endpoint es síncrono. Después de enviar POST /images/edits, mantén abierta la solicitud HTTP hasta que responda el servidor. Cuando la generación se completa, el contenido de la imagen se devuelve en data[0].b64_json. El endpoint no devuelve un task_id, y no existe un endpoint separado para consultar el estado o descargar el resultado.

Documentación relacionada

Autorizaciones

Authorization

string

header

requerido

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Cuerpo

multipart/form-data

model

enum<string>

predeterminado:gpt-image-2

requerido

Use the GPT Image 2 model ID.

Opciones disponibles:

gpt-image-2

Ejemplo:

"gpt-image-2"

prompt

string

requerido

Instructions for editing the image or generating from reference images.

Ejemplo:

"Use this reference image to create a more polished square product hero image while preserving the main style."

image

file

The reference image field for a single input image.

image[]

file[]

Repeat this field for each input when sending multiple reference images.

mask

file

An optional single mask file. The mask and original image must have the same format and dimensions, each file must be smaller than 50 MB, and the mask must contain an Alpha channel. For maximum compatibility, use PNG with an Alpha channel for both files. With multiple image[] inputs, the mask applies to the first image.

predeterminado:1

Use 1. Send separate requests when you need multiple output images.

Ejemplo:

"1"

size

enum<string>

predeterminado:1024x1024

The requested image size or aspect-ratio tier. The server may map or adjust the final pixel dimensions, so inspect the decoded image for its actual size.

Opciones disponibles:

auto,

1024x1024,

1536x1024,

1024x1536,

1536x1152,

1152x1536,

2048x2048,

2048x1152,

3840x2160,

2160x3840

Ejemplo:

"1024x1024"

response_format

enum<string>

predeterminado:b64_json

Use b64_json.

Opciones disponibles:

b64_json

Ejemplo:

"b64_json"

output_format

enum<string>

predeterminado:png

Use png. Do not rely on jpeg or webp being returned directly in the selected format.

Opciones disponibles:

png

Ejemplo:

"png"

Respuesta

Image editing result.

created

integer

Ejemplo:

1710000000

data

object[]

Show child attributes

​Valores recomendados

​Una imagen de referencia

​Varias imágenes de referencia

​Edita una zona seleccionada con una máscara

​Edición con máscara en Python

​Comprueba los archivos antes de subirlos

​Ejemplo con Python

​Tamaños recomendados

​Guarda la imagen

​Flujo de respuesta

​Documentación relacionada

Autorizaciones

Cuerpo

Respuesta

Valores recomendados

Una imagen de referencia

Varias imágenes de referencia

Edita una zona seleccionada con una máscara

Edición con máscara en Python

Comprueba los archivos antes de subirlos

Ejemplo con Python

Tamaños recomendados

Guarda la imagen

Flujo de respuesta

Documentación relacionada