Image Editing API Reference

gpt-image-2-vip image editing API reference and interactive playground — upload reference images + instructions for single-image edits or multi-image fusion. Use size to lock output dimensions.

POST /v1/images/edits

Image editing: edit or fuse reference images with locked output size

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-vip \
  --form 'prompt=Place the person from image1 into the scene of image2, in the style of image3' \
  --form 'image=<string>' \
  --form image.items='@example-file'

200

{
  "data": [
    {
      "b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "created": 1778037127,
  "usage": {
    "input_tokens": 98,
    "output_tokens": 1185,
    "total_tokens": 1283
  }
}

The interactive Playground on the right supports direct local image upload. Enter your API Key in the Authorization field (format: Bearer sk-xxx), pick the image, set prompt / model / size, then click send.

Scope: This page is for editing or fusing one or more reference images. The request uses multipart/form-data. For pure text-to-image, see the Text-to-Image endpoint.

Difference vs gpt-image-2-all: identical call structure, just one extra size field. If you don’t need to lock dimensions and want fastest output, use gpt-image-2-all.

🖥️ Browser Playground limitation (default b64_json mode)

This endpoint defaults to response_format: "b64_json", so the response carries a multi-MB base64 string and the browser Playground may show 请求时发生错误: unable to complete request — the request actually succeeded; the browser just can’t render such a long base64 string.

Recommended workflow:

• Just want to view the image in the Playground? Pass "response_format": "url" explicitly — the response is a single R2 link and renders fine.
• Want base64 or want to upload very large reference images? Copy the code sample below and run it locally.

📎 Multi-image fusion order matters

The image field accepts multiple reference images. The order is the basis for “image1 / image2 / image3” references in your prompt. Reference them explicitly in the prompt, e.g.:

Place the person from image1 into the scene of image2, in the painting style of image3

Recommended ≤ 10MB per image, formats png / jpg / webp. Overly large images may hit gateway limits.

🎯 Shape-preserving edits: When you pass size=auto (or omit size), the output inherits the aspect ratio of whichever reference image the prompt names as the edit target — not necessarily the first one in multi-image scenarios.

For example, with the prompt “modify image2, change image2’s outfit and hat to match image1”, if image2 is 1:1, the output is 1:1 (even if image1 is a landscape 16:9).

Useful for outfit swaps, adding accessories, retouching, and other shape-preserving edits. If the prompt doesn’t pick a target, the model decides on its own; pass an explicit 30-bucket size only when you need to change the aspect ratio.

⚠️ Key parameter notes

• size: for editing, prefer auto (or omit the field) — the model preserves the aspect ratio of whichever reference image the prompt names as the target of the edit, not necessarily the first one in multi-image scenarios. For example, with the prompt “modify image2, change image2’s outfit to match image1”, the output ratio matches image2; if the prompt doesn’t disambiguate, the model decides on its own. To force a different dimension, pick one of the 30 supported sizes; use lowercase ASCII x, e.g., 2048x1360, 3840x2160. Full table: overview page.
• quality: ❌ rejected — do not pass.
• n: ❌ rejected — single image per call.

Code Examples

Python

Single-image edit:

import requests

API_KEY = "sk-your-api-key"

with open("photo.png", "rb") as f:
    response = requests.post(
        "https://api.apiyi.com/v1/images/edits",
        headers={"Authorization": f"Bearer {API_KEY}"},
        data={
            "model": "gpt-image-2-vip",
            "prompt": "Replace the background with a sunset beach",
            "size": "2048x1360",          # 3:2 2K Recommended
            "response_format": "url"
        },
        files=[
            ("image", ("photo.png", f, "image/png"))
        ],
        timeout=300  # conservative; absorbs upload + long-tail
    ).json()

print(response["data"][0]["url"])

Multi-image fusion:

import requests

with open("ref1.png", "rb") as f1, \
     open("ref2.png", "rb") as f2, \
     open("ref3.png", "rb") as f3:
    response = requests.post(
        "https://api.apiyi.com/v1/images/edits",
        headers={"Authorization": "Bearer sk-your-api-key"},
        data={
            "model": "gpt-image-2-vip",
            "prompt": "Place the person from image1 into the scene of image2, in the style of image3",
            "size": "2048x2048",          # 1:1 2K Recommended
            "response_format": "b64_json"
        },
        files=[
            ("image", ("ref1.png", f1, "image/png")),
            ("image", ("ref2.png", f2, "image/png")),
            ("image", ("ref3.png", f3, "image/png"))
        ],
        timeout=300
    ).json()

# b64_json already prefixed — use directly as <img src>
data_url = response["data"][0]["b64_json"]

cURL

Single-image edit:

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2-vip" \
  -F "prompt=Replace the background with a sunset beach" \
  -F "size=2048x1360" \
  -F "response_format=url" \
  -F "image=@./photo.png"

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-vip" \
  -F "prompt=Place the person from image1 into the scene of image2, in the style of image3" \
  -F "size=2048x2048" \
  -F "response_format=b64_json" \
  -F "image=@./ref1.png" \
  -F "image=@./ref2.png" \
  -F "image=@./ref3.png"

Node.js (native fetch + FormData)

import fs from 'node:fs';

const form = new FormData();
form.append('model', 'gpt-image-2-vip');
form.append('prompt', 'Replace the background with outer space');
form.append('size', '2048x1360');
form.append('response_format', 'url');
form.append(
  'image',
  new Blob([fs.readFileSync('./photo.png')]),
  'photo.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();
console.log(data.data[0].url);

Browser JavaScript (File objects)

// <input type="file" id="fileInput" multiple>
const files = document.getElementById('fileInput').files;
const form = new FormData();
form.append('model', 'gpt-image-2-vip');
form.append('prompt', 'Fuse these images into a single poster');
form.append('size', '2048x2048');
form.append('response_format', 'url');
for (const f of files) form.append('image', f);

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();
document.getElementById('result').src = data[0].url;

Parameters

Field	Type	Required	Description
model	text	Yes	Fixed at gpt-image-2-vip
prompt	text	Yes	Natural-language edit/fusion description
image	file	Yes	Reference image; can be repeated (array field)
size	text	No	Output size: auto (default — follows whichever reference image the prompt names as the edit target, not necessarily the first one) or one of the 30 sizes; format WIDTHxHEIGHT (lowercase x)
response_format	text	No	b64_json (default) or url

Multi-turn iteration: feed the previous output back as the next call’s image with a new edit instruction to refine progressively. Each round can specify its own size.

Response Format

Same as the text-to-image endpoint: data[0] returns either url or b64_json — never both (depends on response_format). This endpoint defaults to b64_json.

b64_json mode (default):

{
  "data": [
    {
      "b64_json": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "created": 1778037127,
  "usage": {
    "input_tokens": 98,
    "output_tokens": 1185,
    "total_tokens": 1283
  }
}

url mode (requires explicit "response_format": "url"):

{
  "data": [
    {
      "url": "https://r2cdn.copilotbase.com/r2cdn2/0e82148a-bec0-4b42-bbca-117c6b42581b.png"
    }
  ],
  "created": 1778037331,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 2074,
    "total_tokens": 2104
  }
}

The b64_json field already includes the data:image/png;base64, prefix. Use it directly. Do not prepend the prefix again.

Related Resources

Model Overview (full size table)

Complete 30-size table, pricing, technical specs

Chat API

Chat Completions format with online URL inputs

Text-to-Image API

/v1/images/generations compatible endpoint

Sister model gpt-image-2-all

Same call format when you don’t need locked size — faster output

Authorizations

Authorization · string · header · required

API Key from the API易 Console

Body

multipart/form-data

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

Model name, fixed to gpt-image-2-vip

Available options: gpt-image-2-vip

prompt · string · required

Edit/fusion instruction. For multi-image flows, reference upload order as image1/image2/image3

Example:

"Place the person from image1 into the scene of image2, in the style of image3"

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) — upload order maps to image1 / image2 / ... in the prompt. Recommended ≤ 10MB each, formats png / jpg / webp.

size · enum<string>

Output size. For editing, prefer auto (or omit the field) — the model preserves the aspect ratio of whichever reference image the prompt names as the target of the edit (not necessarily the first one in multi-image scenarios). For example, with the prompt "modify image2, change image2's outfit to match image1", the output ratio matches image2. If the prompt doesn't disambiguate, the model decides on its own. To force a different dimension, pick one of the 30 supported sizes; format: WIDTHxHEIGHT with lowercase ASCII x, e.g., 2048x1360, 3840x2160. Flat $0.03/image across all tiers.

Available options: auto, 1280x1280, 848x1280, 1280x848, 960x1280, 1280x960, 1024x1280, 1280x1024, 720x1280, 1280x720, 1280x544, 2048x2048, 1360x2048, 2048x1360, 1536x2048, 2048x1536, 1632x2048, 2048x1632, 1152x2048, 2048x1152, 2048x864, 2880x2880, 2336x3520, 3520x2336, 2480x3312, 3312x2480, 2560x3216, 3216x2560, 2160x3840, 3840x2160, 3840x1632

Example:

"2048x1360"

response_format · enum<string> · default: b64_json

Response format. b64_json returns a base64 string already prefixed with a data URL header (default); url returns an R2 CDN link

Available options: b64_json, url

Response

200

application/json

Image successfully generated. Defaults to base64 in data[0].b64_json — url is not returned in the same response.

Image editing response. data[0] returns either url or b64_json, never both (depends on response_format; this endpoint defaults to b64_json).

data · object[]

Result array (this model returns 1 image per call)

Show child attributes

created · integer

Unix timestamp (seconds)

usage · object

Token usage statistics

Show child attributes