Image to image (image editing)

curl 'https://www.bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=YOUR_MODEL_ID' \
  -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)"
    }
  ]
}

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

POST

images

edits

curl 'https://www.bettertoken.ai/v1/images/edits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'model=YOUR_MODEL_ID' \
  -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)"
    }
  ]
}

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

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.

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

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

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:YOUR_MODEL_ID

required

固定使用 YOUR_MODEL_ID。

Available options:

YOUR_MODEL_ID

Example:

"YOUR_MODEL_ID"

prompt

string

required

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

Example:

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

image

file

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

image[]

file[]

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

default:1

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

Example:

"1"

size

enum<string>

default:1024x1024

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

Available options:

auto,

1024x1024,

1536x1024,

1024x1536,

1536x1152,

1152x1536,

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

Show child attributes

​Recommended values

​Single reference image

​Multiple reference images

​Python example

​Recommended sizes

​Save the image

​Response flow

​Related docs

Authorizations

Body

Response

Recommended values

Single reference image

Multiple reference images

Python example

Recommended sizes

Save the image

Response flow

Related docs