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'

import requests

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

files = { "image.items": ("example-file", open("example-file", "rb")) }
payload = {
    "model": "gpt-image-2-vip",
    "prompt": "Place the person from image1 into the scene of image2, in the style of image3",
    "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-vip');
form.append('prompt', 'Place the person from image1 into the scene of image2, in the style of image3');
form.append('image', '<string>');
form.append('image.items', '{
  "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-vip\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace the person from image1 into the scene of image2, in the style of image3\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--",
  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-vip\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace the person from image1 into the scene of image2, in the style of image3\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--")

	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-vip\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace the person from image1 into the scene of image2, in the style of image3\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--")
  .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-vip\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nPlace the person from image1 into the scene of image2, in the style of image3\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--"

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

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

This endpoint returns a base64 string (b64_json) by default, which can be several MB, so 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: when you want base64 or need 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.
• response_format: omitting it returns base64 (raw, no prefix, verified July 2026); pass "url" for an image URL. Businesses that depend on URL output should switch their token to the image2_OSS group for deterministic URL output with no base64 fallback.

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
        },
        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
        },
        files=[
            ("image", ("ref1.png", f1, "image/png")),
            ("image", ("ref2.png", f2, "image/png")),
            ("image", ("ref3.png", f3, "image/png"))
        ],
        timeout=300
    ).json()

# Verified July 2026: b64_json is raw base64 (no data: prefix); earlier versions
# included the prefix, so a defensive check is safest
import base64
b64 = response["data"][0]["b64_json"]
if b64.startswith("data:"):
    b64 = b64.split(",", 1)[1]
with open("edited.png", "wb") as f:
    f.write(base64.b64decode(b64))

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 "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 "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(
  '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');
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)

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: returns base64 by default (data[0].b64_json, raw base64 with no prefix, verified July 2026). For an image URL, pass response_format: "url" explicitly; businesses that depend on URL output should switch their token to the image2_OSS group for deterministic URL output with no base64 fallback. data[0] returns either url or b64_json — never both.

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 (pass response_format: "url" explicitly; use the image2_OSS group if you depend on URLs):

{
  "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
  }
}

Verified July 2026: the b64_json field is raw base64 without the data: prefix — decode it or prepend the prefix yourself before rendering. Earlier versions did include the prefix, so always check startsWith('data:') first to handle both shapes.

Related Resources

Model Overview (full size table)

Complete 30-size table, pricing, technical specs

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

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. Returns base64 by default (data[0].b64_json); to get a url, switch to the image2_OSS group with response_format=url. data[0] returns either url or b64_json, never both.

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