Image Edit API Reference

gpt-image-2 image edit API reference and live testing — upload reference images (up to 16) + instructions for single-image edit, multi-image fusion, or mask inpainting

POST /v1/images/edits

Image Edit: edit or fuse reference images by instruction

cURL

curl --request POST \
  --url https://api.apiyi.com/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form model=gpt-image-2 \
  --form 'prompt=Place subject from image 1 into scene from image 2, using color style from image 3' \
  --form 'image=<string>' \
  --form image.items='@example-file' \
  --form mask='@example-file'

import requests

url = "https://api.apiyi.com/v1/images/edits"

files = {
    "image.items": ("example-file", open("example-file", "rb")),
    "mask": ("example-file", open("example-file", "rb"))
}
payload = {
    "model": "gpt-image-2",
    "prompt": "Place subject from image 1 into scene from image 2, using color style from image 3",
    "image": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('model', 'gpt-image-2');
form.append('prompt', 'Place subject from image 1 into scene from image 2, using color style from image 3');
form.append('image', '<string>');
form.append('image.items', '{
  "fileName": "example-file"
}');
form.append('mask', '{
  "fileName": "example-file"
}');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.apiyi.com/v1/images/edits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apiyi.com/v1/images/edits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apiyi.com/v1/images/edits"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/edits")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.com/v1/images/edits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"model\"\r\n\r\ngpt-image-2\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace subject from image 1 into scene from image 2, using color style from image 3\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"mask\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

200

{
  "created": 1776832476,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 1280,
    "output_tokens": 6240,
    "total_tokens": 7520
  }
}

The interactive Playground on the right supports direct local image upload. Fill in your API Key in Authorization (format: Bearer sk-xxx), select image / mask files, fill in prompt and model, and send.

Use case: This page is for “edit / fuse / inpaint based on one or more reference images”. Request format is multipart/form-data. For pure text-to-image, use the Text-to-Image endpoint.

🖥️ Browser Playground limitation (important)

This endpoint returns a raw base64 string (typically several MB) in the response. Due to browser rendering limits, the Playground on the right may show 请求时发生错误: unable to complete request after the response arrives — the request actually succeeded; the browser just can’t render such a long base64 string.

Recommended workflow (beginner-friendly):

• Copy the Python / Node.js / cURL sample below and run it locally. The code automatically base64.b64decodes the response and writes the image to a file.
• If you must use the in-browser Playground, use a tiny reference image (< 50KB), set size to the smallest tier (e.g. 1024x1024), and quality to low.

⚠️ Key differences (when migrating from gpt-image-1.5)

• Do not pass input_fidelity — gpt-image-2 forces high-fidelity; passing it returns 400
• Edit requests have noticeably higher input tokens — references convert to many tokens via Vision pricing; budget accordingly
• background: transparent not supported — use opaque or post-process
• Multi-image fusion: max 16 — repeat the image[] field; more than 16 errors out

📎 Multi-image fusion order matters

The image[] field accepts multiple reference images. Upload order maps to “image 1 / image 2 / image 3” references in the prompt. Reference them explicitly:

Place subject from image 1 into scene from image 2, using color style from image 3

Per-file limit: under 50MB each (multipart file upload), formats: png / jpg / webp; in practice compress to within 1.5MB before uploading (see “Upload Size Limits” below).

Code Examples

Python (OpenAI SDK · single-image edit)

from openai import OpenAI
import base64

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.apiyi.com/v1"
)

resp = client.images.edit(
    model="gpt-image-2",
    image=open("photo.png", "rb"),
    prompt="Replace the background with a seaside sunset, preserve subject details",
    size="1536x1024",
    quality="high"
)

# b64_json is raw base64 (no prefix) — decode manually
with open("edited.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

Python (OpenAI SDK · multi-image fusion)

resp = client.images.edit(
    model="gpt-image-2",
    image=[
        open("person.png", "rb"),
        open("scene.png", "rb"),
        open("style.png", "rb"),
    ],
    prompt="Place subject from image 1 into scene from image 2, using color style from image 3, keep lighting consistent",
    size="1536x1024",
    quality="high"
)

with open("fused.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

cURL (multi-image fusion)

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "prompt=Place subject from image 1 into scene from image 2, using color style from image 3" \
  -F "size=1536x1024" \
  -F "quality=high" \
  -F "image[]=@person.png" \
  -F "image[]=@scene.png" \
  -F "image[]=@style.png"

cURL (mask inpainting)

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "prompt=Replace the sky with pink sunset clouds" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "image[]=@photo.png" \
  -F "mask=@mask.png" \
  | jq -r '.data[0].b64_json' | base64 -d > photo_edited.png

Node.js (Native fetch + FormData · multi-image fusion)

import fs from 'node:fs';

const form = new FormData();
form.append('model', 'gpt-image-2');
form.append('prompt', 'Place subject from image 1 into scene from image 2');
form.append('size', '1536x1024');
form.append('quality', 'high');
form.append('image[]', new Blob([fs.readFileSync('./person.png')]), 'person.png');
form.append('image[]', new Blob([fs.readFileSync('./scene.png')]), 'scene.png');

const resp = await fetch('https://api.apiyi.com/v1/images/edits', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer sk-your-api-key' },
    body: form
});

const { data } = await resp.json();
fs.writeFileSync('fused.png', Buffer.from(data[0].b64_json, 'base64'));

Parameter Reference

Field	Type	Required	Default	Description
model	text	Yes	—	Fixed: gpt-image-2
prompt	text	Yes	—	Edit / fusion instruction
image[]	file	Yes	—	Reference images, can repeat (max 16)
mask	file	No	—	Mask image (only applies to first image, alpha channel required)
size	text	No	auto	Output size, same as text-to-image
quality	text	No	auto	low / medium / high / auto
output_format	text	No	png	png / jpeg / webp
output_compression	text	No	—	0–100, only for jpeg / webp
background	text	No	auto	auto / opaque (not supported: transparent)

Do not pass the legacy DALL·E values standard / hd for quality. Only the four official enum values low / medium / high / auto are accepted. The legacy values behave inconsistently across backend channels: sometimes they fail immediately with a 400 (invalid_value), and sometimes they are silently ignored and the request runs at auto (unpredictable cost). Always pass one of the four official values explicitly.

Upload Size Limits

Item	Limit	Notes
Reference image count	Up to 16	Repeat the image[] field
Per image (multipart file upload)	Under 50MB each	Formats: png / jpg / webp
Per image (base64 data URL)	Field length ~20MiB	This is a length limit on the URL/base64 string field (schema maxLength: 20971520) — not the same as the 50MB multipart cap; base64 inflates size by ~1/3, so keep original images within 15MB
Mask file	PNG under 4MB	Must match the original image’s dimensions, with an alpha channel

Don’t max out the total request size: even though the per-image cap is 50MB with up to 16 images, multiple near-cap images make a single request body enormous and prone to gateway / CDN / timeout failures. In practice, compress each image to within 1.5MB (JPEG quality 80-90) — success rate and generation speed both improve noticeably, and output quality is unrelated to input file size.

Reference Image Format Requirements and Preprocessing

/v1/images/edits only accepts png / jpg / webp standard formats. If you receive this 400:

{
  "error": {
    "message": "Invalid image file or mode for image 1, please check your image file. ...",
    "type": "shell_api_error",
    "code": "invalid_image_file"
  }
}

the reference image is most likely not a standard JPEG/PNG. The most common trap is MPO format (Multi-Picture Object, a multi-frame JPEG container) from phone cameras: .jpg files straight out of Huawei Mate-series phones embed an HDR gain-map sub-frame and are actually MPO. These files start with the same FFD8 header — the extension and the file command both report JPEG — so they’re impossible to spot by eye; only frame-aware parsing (e.g. Pillow) can tell. The “image 1” in the error refers to the Nth reference image (1-indexed), so use the index to locate the offending file.

Verified July 2026: MPO files failed with 400 on 5/5 uploads; the same images re-encoded as standard JPEG/PNG succeeded at the full original 3072×4096 resolution — the problem is the format, not the dimensions or file size. The error is returned quickly (~4s) at the input-validation stage and is not billed.

Detection and fix: if Image.open(f).format returns "MPO", the file needs conversion. A single re-encode step in your upload pipeline also covers HEIC and other phone formats:

from PIL import Image
import io

def normalize_image(path: str) -> bytes:
    """Convert phone photos (MPO/HDR multi-frame etc.) to standard JPEG that passes edits validation"""
    im = Image.open(path)
    im.load()                      # for MPO, keeps only the first (full-size) frame
    if im.mode not in ("RGB", "RGBA"):
        im = im.convert("RGB")
    out = io.BytesIO()
    im.save(out, format="JPEG", quality=92)   # or format="PNG"
    return out.getvalue()

If your product accepts user-shot photos (interior renders, product shots, etc.), re-encode uniformly on the server side rather than debugging images one by one — phone HDR photos will keep showing up. More input-handling tips: Image API Essentials and Best Practices.

Mask Inpainting Requirements

• Same size as original, PNG format, under 4MB
• Must have alpha channel: transparent (alpha=0) = inpaint area, opaque = preserve
• Mask only applies to the first image
• Mask is a “soft guide” — the model may extend or contract around the masked region

Multi-turn iteration: feed the previous output back as the next call’s image[] with a new instruction to incrementally refine. Each round is independently token-billed — watch cumulative cost.

Response Format

{
    "created": 1776832476,
    "data": [
        {
            "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
        }
    ],
    "usage": {
        "input_tokens": 848,
        "input_tokens_details": {
            "image_tokens": 832,
            "text_tokens": 16
        },
        "output_tokens": 196,
        "output_tokens_details": {
            "image_tokens": 196,
            "text_tokens": 0
        },
        "total_tokens": 1044
    }
}

b64_json is raw base64, without the data:image/...;base64, prefix — different from gpt-image-2-all. Decode it client-side to write a file, or prepend the prefix for browser rendering.

Edit requests’ input_tokens are typically significantly higher than text-to-image at the same size, because reference images are billed per Vision pricing rules — the exact amount is available directly in usage.input_tokens_details.image_tokens, tracked separately from the text portion (text_tokens). Multi-image fusion increases image_tokens strictly linearly per additional reference image (verified July 2026: 4 × 1024² images = 4 × 1024 tokens) — see How Multiple Input Images Affect the Price for the measurement table. See How to check the real token count for each call on the overview page for the full field reference.

Authorizations

Authorization · string · header · required

API Key obtained from APIYI Console

Body

multipart/form-data

model · enum<string> · default: gpt-image-2 · required

Model name, fixed as gpt-image-2

Available options: gpt-image-2

prompt · string · required

Edit/fusion instruction. For multi-image, use 'image 1 / image 2 / image 3' to reference upload order

Example:

"Place subject from image 1 into scene from image 2, using color style from image 3"

image · file[] · required

Reference images. For a single image, send the field once; for multiple images, repeat the same image field (e.g., -F image=@a.png -F image=@b.png, max 16) — upload order maps to image 1 / image 2 / ... in the prompt. multipart file upload: each under 50MB, formats: png/jpg/webp; compress to within 1.5MB in practice

mask · file

Mask image (optional, only applies to first image). Requirements:

• Same size as original
• PNG format, under 4MB
• Must have alpha channel (alpha=0 = inpaint area, opaque = preserve)

size · string · default: auto

Output size (same as text-to-image). Preset or constraint-satisfying custom size

Example:

"1536x1024"

quality · enum<string> · default: auto

Quality tier

Available options: auto, low, medium, high

output_format · enum<string> · default: png

Output format

Available options: png, jpeg, webp

output_compression · integer

Output compression (0–100), only effective for jpeg/webp

Required range: 0 <= x <= 100

background · enum<string> · default: auto

Background mode. auto or opaque. Not supported: transparent

Available options: auto, opaque

Response

200

application/json

Image generated successfully

created · integer

Example:

1776832476

data · object[]

Generation results (this model returns 1 image per call)

Show child attributes

usage · object

Token usage for this call

Show child attributes