Skip to main content
POST
/
v1
/
images
/
edits
curl 'https://www.bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer sk-***REDACTED***' \
  -F 'model=gpt-image-2' \
  -F 'prompt=参考这张图片，生成一张更精致的方形产品主视觉，保持主体风格一致。' \
  -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)"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt

Use this file to discover all available pages before exploring further.

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://www.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://www.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.
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://www.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://www.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'

​
Python example

import requests

url = "https://www.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"]
sizeRatioUse case
autoAutoAutomatic size selection
1024x10241:1Square images, avatars, covers, assets
1536x10243:2Landscape posters, banners, scenes
1024x15362:3Portrait mobile covers and posters
2048x20481:1High-resolution square images
2048x115216:9High-resolution landscape images
3840x216016:94K landscape images
2160x38409:164K 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

Use your BetterToken API Key as a bearer token. Do not expose API keys in frontend browser code, screenshots, logs, tickets, or Git repositories.

Body

multipart/form-data
​
model
enum<string>
default:gpt-image-2
required

固定使用 gpt-image-2。

Available options:
gpt-image-2
Example:

"gpt-image-2"

​
prompt
string
required

图片编辑或参考图生成说明。

Example:

"参考这张图片，生成一张更精致的方形产品主视觉，保持主体风格一致。"

​
image
file

单张参考图字段名。单参考图时使用 image。

​
image[]
file[]

多张参考图字段名。多参考图时重复提交 image[]。

​
n
default:1

推荐固定为 1。多张图片建议发起多次独立请求。

Example:

"1"

​
size
enum<string>
default:1024x1024

图片尺寸和比例档位。auto 为自动；1024x1024 和 2048x2048 为 1:1；1536x1024 为 3:2；1024x1536 为 2:3；2048x1152 和 3840x2160 为 16:9；2160x3840 为 9:16。实际返回像素可能由服务端映射或调整，客户端应以解码后的真实图片尺寸为准。

Available options:
auto,
1024x1024,
1536x1024,
1024x1536,
2048x2048,
2048x1152,
3840x2160,
2160x3840
Example:

"1024x1024"

​
response_format
enum<string>
default:b64_json

推荐固定为 b64_json。

Available options:
b64_json
Example:

"b64_json"

​
output_format
enum<string>
default:png

推荐固定为 png。不要依赖 jpeg 或 webp 直接返回对应格式。

Available options:
png
Example:

"png"

Response

Image generation result.

OpenAI-compatible image response. Clients should read data[0].b64_json and allow additional fields such as revised_prompt.

​
created
integer
Example:

1710000000

​
data
object[]