Skip to main content
POST
Image editing: edit a reference image or fuse two images
The interactive Playground on the right supports uploading local images. Enter your API key under Authorization (format: Bearer sk-xxx), pick an image file, 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:
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 a reference image or fusing two images. To generate from text only, use the Text-to-Image API.
⚠️ For two images the field names are image + image2, not image[]With two reference images, name the first field image and the second image2. Repeating image[], repeating image, or adding a mask field all return 400 File must be attached in a form field with a name starting with 'image'.That means the OpenAI SDK’s multi-image form client.images.edit(image=[f1, f2]) does not work (it sends image[]). Single-image edits with the SDK work fine.
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)

Python (requests · single image)

Python (two-image fusion · image + image2)

cURL

Node.js (fetch + FormData)

Parameter Reference

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. 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
For two-image fusion, refer to image / image2 as “image 1 / image 2” in the prompt. In our tests identity fidelity for people is only moderate (facial features may drift), so validate on a small batch first if portrait consistency matters.

Response Format

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; 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 file (the first one, "image 1" in the prompt). png / jpg / webp

image2
file

Optional second reference image ("image 2" in the prompt), for two-image fusion

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
n
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

usage
object

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