Image Editing API Reference

Image editing: edit reference images (1–5)

curl --request POST \
  --url https://api.apiyi.com/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form model=MAI-Image-2.6-Flash \
  --form 'prompt=Change the teapot to a deep cobalt blue glaze, keep everything else identical' \
  --form 'image=@example-file;type=image/png'

import requests

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

files = { "image": ("example-file", open("example-file", "rb"), "image/png") }
payload = {
    "model": "MAI-Image-2.6-Flash",
    "prompt": "Change the teapot to a deep cobalt blue glaze, keep everything else identical"
}
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const form = new FormData();
form.append('model', 'MAI-Image-2.6-Flash');
form.append('prompt', 'Change the teapot to a deep cobalt blue glaze, keep everything else identical');
form.append('image', '<string>');

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\nMAI-Image-2.6-Flash\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the teapot to a deep cobalt blue glaze, keep everything else identical\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: image/png\r\n\r\n<string>\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\nMAI-Image-2.6-Flash\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the teapot to a deep cobalt blue glaze, keep everything else identical\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: image/png\r\n\r\n<string>\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\nMAI-Image-2.6-Flash\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the teapot to a deep cobalt blue glaze, keep everything else identical\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: image/png\r\n\r\n<string>\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\nMAI-Image-2.6-Flash\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the teapot to a deep cobalt blue glaze, keep everything else identical\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: image/png\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "created": 1791000788,
  "data": [
    {
      "b64_json": "<string>"
    }
  ],
  "usage": {
    "prompt_tokens": 1000,
    "total_tokens": 1000
  }
}

POST

images

edits

Image editing: edit reference images (1–5)

curl --request POST \
  --url https://api.apiyi.com/v1/images/edits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form model=MAI-Image-2.6-Flash \
  --form 'prompt=Change the teapot to a deep cobalt blue glaze, keep everything else identical' \
  --form 'image=@example-file;type=image/png'

import requests

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

files = { "image": ("example-file", open("example-file", "rb"), "image/png") }
payload = {
    "model": "MAI-Image-2.6-Flash",
    "prompt": "Change the teapot to a deep cobalt blue glaze, keep everything else identical"
}
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const form = new FormData();
form.append('model', 'MAI-Image-2.6-Flash');
form.append('prompt', 'Change the teapot to a deep cobalt blue glaze, keep everything else identical');
form.append('image', '<string>');

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\nMAI-Image-2.6-Flash\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the teapot to a deep cobalt blue glaze, keep everything else identical\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: image/png\r\n\r\n<string>\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\nMAI-Image-2.6-Flash\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the teapot to a deep cobalt blue glaze, keep everything else identical\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: image/png\r\n\r\n<string>\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\nMAI-Image-2.6-Flash\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the teapot to a deep cobalt blue glaze, keep everything else identical\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: image/png\r\n\r\n<string>\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\nMAI-Image-2.6-Flash\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"prompt\"\r\n\r\nChange the teapot to a deep cobalt blue glaze, keep everything else identical\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"image\"; filename=\"example-file\"\r\nContent-Type: image/png\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "created": 1791000788,
  "data": [
    {
      "b64_json": "<string>"
    }
  ],
  "usage": {
    "prompt_tokens": 1000,
    "total_tokens": 1000
  }
}

The interactive Playground on the right supports uploading local images. Enter your API key under Authorization (format: Bearer sk-xxx), pick one or more image files, fill in prompt and model, and send.

🔴 This endpoint only accepts multipart/form-data file uploadsSending JSON to /v1/images/edits (with image as a URL, data URI, or raw base64) returns 400:

request Content-Type isn't multipart/form-data

Image URLs are not supported as input. If you only have a URL, download it on your server first, then upload the file. File upload needs no image hosting; just send the local file.

Use case: this page is for editing with reference images, covering single-image edits and fusing 1–5 images. To generate from text only, use the Text-to-Image API.

🖼️ 1–5 reference images supported (since 2026-10-07)

How: repeat the image[] field, one image per field. With the OpenAI SDK, pass a list: client.images.edit(image=[f1, f2, ...]). Repeating image also works
Order: images are numbered in upload order (image 1, image 2, …), so the prompt can say “put the fox from image 2 into image 1”
Price: billed per request; 1 image or 5 images costs the same
Formats: JPEG, PNG, WebP; GIF and other formats return 400
More than 5 images returns 400 at most 5 reference images are accepted for <model>

Do not use numbered field names such as image + image2: the request returns 200 but only the first image is used; the second is dropped. image1 + image2 returns 500 image is required. For several images, always repeat image[].

Same forbidden parameters as text-to-image: do not send response_format, seed, or negative_prompt (400). The response is always data[0].b64_json (PNG).

Code Examples

Python (OpenAI SDK · single image)

from openai import OpenAI
import base64

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

# images.edit uses a multipart file upload under the hood; do not pass response_format
resp = client.images.edit(
    model="MAI-Image-2.6-Flash",
    image=open("teaset.jpg", "rb"),
    prompt="Change the teapot to a deep cobalt blue glaze, keep everything else identical"
)

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

Python (OpenAI SDK · multi-image fusion)

from openai import OpenAI
import base64

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

# Pass a list of 1-5 files; the SDK uploads each one as an image[] field
# Images are numbered in upload order (image 1, image 2, ...); same price as a single image
resp = client.images.edit(
    model="MAI-Image-2.6-Flash",
    image=[open("teaset.jpg", "rb"), open("fox.jpg", "rb")],
    prompt="Put the fox from image 2 (keeping every detail of its look) into the scene of image 1, sitting next to the tea set; keep everything else in image 1 unchanged"
)

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

Python (requests · single image)

import base64
import os
import requests

# Pass the file via files=; requests sets multipart/form-data and the boundary for you
# Do not use json=, and do not set Content-Type by hand
with open("teaset.jpg", "rb") as fp:
    response = requests.post(
        "https://api.apiyi.com/v1/images/edits",
        headers={"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"},
        data={
            "model": "MAI-Image-2.6",
            "prompt": "Change the teapot to a deep cobalt blue glaze, keep everything else exactly the same"
        },
        files={"image": ("teaset.jpg", fp, "image/jpeg")},
        timeout=180
    )
response.raise_for_status()

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

For several images, pass files as a list of tuples with one image[] per image (a dict cannot hold repeated keys):

files = [
    ("image[]", ("teaset.jpg", open("teaset.jpg", "rb"), "image/jpeg")),
    ("image[]", ("fox.jpg", open("fox.jpg", "rb"), "image/jpeg")),
]

cURL

# Single-image edit: -F means multipart/form-data, @ uploads a local file
curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=MAI-Image-2.6-Flash" \
  -F "prompt=Change the teapot to a deep cobalt blue glaze, keep everything else identical" \
  -F "[email protected]" \
  | python3 -c "import sys,json,base64; open('edited.png','wb').write(base64.b64decode(json.load(sys.stdin)['data'][0]['b64_json']))"

# Edit and change the canvas to 1536×1024 (a different aspect ratio recomposes the image)
curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=MAI-Image-2.6" \
  -F "prompt=Turn this tea set into a lifestyle scene on a wooden table, natural light, photorealistic" \
  -F "width=1536" \
  -F "height=1024" \
  -F "[email protected]"

# Multi-image fusion: repeat the image[] field, 1-5 images, numbered in upload order
curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=MAI-Image-2.6-Flash" \
  -F "prompt=Put the fox from image 2 (keeping every detail of its look) into the scene of image 1, sitting next to the tea set; keep everything else in image 1 unchanged" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  | python3 -c "import sys,json,base64; open('fused.png','wb').write(base64.b64decode(json.load(sys.stdin)['data'][0]['b64_json']))"

Node.js (fetch + FormData)

import fs from 'node:fs';

const form = new FormData();
form.append('model', 'MAI-Image-2.6-Flash');
form.append('prompt', 'Replace the background with a snowy pine forest at night, keep the person unchanged');
form.append('image', new Blob([fs.readFileSync('./photo.jpg')]), 'photo.jpg');
// Multi-image fusion: call form.append('image[]', ...) once per image instead, up to 5

const resp = await fetch('https://api.apiyi.com/v1/images/edits', {
    method: 'POST',
    // Do not set Content-Type by hand; FormData adds the boundary
    headers: { 'Authorization': `Bearer ${process.env.APIYI_API_KEY}` },
    body: form,
    signal: AbortSignal.timeout(120000)
});

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

Parameter Reference

Parameter	Type	Required	Default	Description
`model`	string	✅	—	`MAI-Image-2.6` ($0.12/image) or `MAI-Image-2.6-Flash` ($0.06/image), case-sensitive
`prompt`	string	✅	—	Edit instruction. State what to change and that everything else stays the same
`image` / `image[]`	file	✅	—	Reference image files, 1–5. Use `image` for one image; for several, repeat the `image[]` field, numbered image 1…N in upload order. JPEG / PNG / WebP; the count does not change the price
`width` / `height`	integer	❌	Follows the original’s ratio	Output size, same rules as text-to-image; a different aspect ratio recomposes the image
`n`	integer	❌	`1`	Number of images. Works on this endpoint, billed per image
~~`mask`~~	—	—	—	Not supported; returns 400 `<model> does not support mask edits`
~~`response_format`~~ / ~~`seed`~~ / ~~`negative_prompt`~~	—	—	—	Return 400

Output size when you omit it: the output follows the original’s aspect ratio snapped to multiples of 16, e.g. a 1344×756 input gives 1360×768; with several images, image 1 sets the aspect ratio. For local edits that should keep the composition, do not send width / height.

Editing Results and Prompting

The editing endpoint keeps the original’s composition, colors, and details and only changes what the prompt asks for:

MAI-Image-2.6-Flash editing example: teapot recolored from cream to cobalt blue, everything else unchanged

Prompt	Result
✅ `Change the teapot to a deep cobalt blue glaze, keep everything else exactly the same`	Only the teapot changes color; labels and other objects stay pixel-identical
✅ `Turn this photo into a watercolor painting, keep the composition`	Style is repainted, composition kept
⚠️ `Make it look better`	Too vague; the scope of changes is unpredictable

Explicitly saying “keep everything else the same” is the most effective technique with this model and preserves as much of the original as possible.

Multi-Image Fusion

Image 1 serves as the base, and objects from the other reference images are placed into it as the prompt describes. The example below sends 5 images in one request (tea set + fox + rubber duck + alarm clock + cactus), with a prompt asking to place the fox from image 2, the yellow rubber duck from image 3, the red vintage alarm clock from image 4 and the potted cactus from image 5 onto the tea table in image 1, keeping each object’s look and leaving the rest of image 1 unchanged:

Prompt	Result
✅ `Put the fox from image 2 into the scene of image 1, keep everything else in image 1 unchanged`	Refer to images as image N in upload order; the most reliable phrasing
✅ Name the object in each image: `the yellow rubber duck from image 3, the red alarm clock from image 4`	With many images, naming each object keeps any from being left out
⚠️ `Combine these images into one`	No base image or subject named, so the composition is unpredictable

Response Format

{
  "created": 1791000788,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..."
    }
  ],
  "usage": {
    "prompt_tokens": 1000,
    "total_tokens": 1000,
    "input_tokens": 1000,
    "output_tokens": 0
  }
}

Response fields

b64_json is plain base64 without a data: prefix and decodes to a PNG.
With n > 1 the data array has several items; don’t read only data[0].
No url and no revised_prompt are returned.

Do not reconcile billing with usage: it holds placeholders (prompt_tokens is always 1000 × the image count). Editing costs the same as text-to-image, billed per image, and the number of reference images does not change the price; the APIYI console bill is authoritative.

Authorizations

Authorization

string

header

required

API key from the APIYI console

Body

multipart/form-data

model

enum<string>

default:MAI-Image-2.6-Flash

required

Model ID (case-sensitive)

Available options:

MAI-Image-2.6-Flash,

MAI-Image-2.6

prompt

string

required

Edit instruction. State what to change and that everything else stays the same

Example:

"Change the teapot to a deep cobalt blue glaze, keep everything else identical"

image

file[]

required

Reference image files, 1–5, numbered image 1…N in upload order. png / jpg / webp. In code, repeat the image[] field for several images

Required array length: 1 - 5 elements

width

integer

Optional output width. Same rules as text-to-image: each side ≥ 768, width × height ≤ 2,359,296, sent together with height

Required range: x >= 768

height

integer

Optional output height, same rules as width

Required range: x >= 768

integer

default:1

Number of images. Works on this endpoint, billed per image

Required range: x >= 1

Example:

1

Response

Image generated

created

integer

Creation timestamp

Example:

1791000788

data

object[]

Image results; length equals n

Show child attributes

usage

object

Placeholder values, not for billing reconciliation. prompt_tokens is always 1000 × images

Show child attributes

Basics

Basic API

Image API (Official)

Video API (Official)

Multimodal Understanding API

Text Generation

Audio API (Official)

Retrieval & Safety

Code Examples

Python (OpenAI SDK · single image)

Python (OpenAI SDK · multi-image fusion)

Python (requests · single image)

cURL

Node.js (fetch + FormData)

Parameter Reference

Editing Results and Prompting

Multi-Image Fusion

Response Format

Authorizations

Body

Response

​Code Examples

​Python (OpenAI SDK · single image)

​Python (OpenAI SDK · multi-image fusion)

​Python (requests · single image)

​cURL

​Node.js (fetch + FormData)

​Parameter Reference

​Editing Results and Prompting

​Multi-Image Fusion

​Response Format

Authorizations

Body

Response

Code Examples

Python (OpenAI SDK · single image)

Python (OpenAI SDK · multi-image fusion)

Python (requests · single image)

cURL

Node.js (fetch + FormData)

Parameter Reference

Editing Results and Prompting

Multi-Image Fusion

Response Format