Image to image (image editing)

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 The image-to-image endpoint uses a multipart/form-data request body. Upload one or more reference images and submit prompt and parameter fields as form fields.

Use https://bettertoken.ai/v1 as the Base URL. Pass your BetterToken API Key through Authorization: Bearer YOUR_API_KEY.

You can fill in form fields and upload reference images in the Playground on the right side of the page, then send the request directly to https://bettertoken.ai/v1/images/edits.

Do not use a regular JSON body for image-to-image requests. Submit text fields and file fields with multipart/form-data.

Recommended values

Send these fields explicitly in every request:

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

Use image for a single reference image. Use repeated image[] fields for multiple reference images.

Single reference image

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'

Multiple reference images

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'

Edit a selected area with a mask

Add the optional mask file field when you want to guide editing to a selected area. The current BetterToken endpoint reads one mask file. Do not send repeated mask[] fields.

The original image and mask must use the same file format and pixel dimensions. Each file must be smaller than 50 MB. For maximum compatibility, use PNG with an Alpha channel for both files.
The mask must contain an Alpha channel. Fully transparent pixels (Alpha 0) mark the area the model may redraw. Fully opaque pixels (Alpha 255) guide the model to preserve that area.
A regular RGB black-and-white image is not a valid mask unless it actually contains an Alpha channel.
If you send multiple image[] fields, the mask applies to the first input image.
The mask guides the model. It does not guarantee that pixels outside the transparent area remain absolutely identical.

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'

Masked edit with Python

Open both files in one with statement so Python closes them after the request:

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()

Check the files before upload

This minimal Pillow check verifies the required format, dimensions, and Alpha channel. For a typical local mask, it also warns when the Alpha channel does not include both fully transparent and fully opaque areas:

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")

Python example

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"]

Recommended sizes

`size`	Ratio	Use case
`auto`	Auto	Automatic size selection
`1024x1024`	`1:1`	Square images, avatars, covers, assets
`1536x1024`	`3:2`	Landscape posters, banners, scenes
`1024x1536`	`2:3`	Portrait mobile covers and posters
`1536x1152`	`4:3`	Standard landscape images, product images, content graphics
`1152x1536`	`3:4`	Standard portrait images, mobile covers, vertical posters
`2048x2048`	`1:1`	High-resolution square images
`2048x1152`	`16:9`	High-resolution landscape images
`3840x2160`	`16:9`	4K landscape images
`2160x3840`	`9:16`	4K portrait images

size represents the expected aspect ratio and size tier. The actual returned pixels may be mapped or adjusted by the server. Use the decoded image dimensions instead of forcibly cropping the output to the requested value.

Save the image

A successful response follows the OpenAI-compatible image response shape:

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

Read data[0].b64_json and save it as base64 image content. Always set output_format: "png" so you can save the decoded image as .png.

Response flow

This endpoint is synchronous. After sending POST /images/edits, keep the current HTTP request open until the server responds. When generation succeeds, the image content is returned in data[0].b64_json. The endpoint does not return a task_id, and there is no separate status query or result download endpoint.

Authorizations

Authorization

string

header

required

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

Body

multipart/form-data

model

enum<string>

default:gpt-image-2

required

Use the GPT Image 2 model ID.

Available options:

gpt-image-2

Example:

"gpt-image-2"

prompt

string

required

Instructions for editing the image or generating from reference images.

Example:

"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.

default:1

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

Example:

"1"

size

enum<string>

default: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.

Available options:

auto,

1024x1024,

1536x1024,

1024x1536,

1536x1152,

1152x1536,

2048x2048,

2048x1152,

3840x2160,

2160x3840

Example:

"1024x1024"

response_format

enum<string>

default:b64_json

Use b64_json.

Available options:

b64_json

Example:

"b64_json"

output_format

enum<string>

default:png

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

Available options:

png

Example:

"png"

Response

Image editing result.

created

integer

Example:

1710000000

data

object[]

Show child attributes

​Recommended values

​Single reference image

​Multiple reference images

​Edit a selected area with a mask

​Masked edit with Python

​Check the files before upload

​Python example

​Recommended sizes

​Save the image

​Response flow

​Related docs

Authorizations

Body

Response

Recommended values

Single reference image

Multiple reference images

Edit a selected area with a mask

Masked edit with Python

Check the files before upload

Python example

Recommended sizes

Save the image

Response flow

Related docs