Skip to main content
POST
Image editing: edit one reference image
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 single reference image. To generate from text only, use the Text-to-Image API.
⚠️ Multi-image fusion is temporarily unavailable; only 1 reference image per request is supportedSend a single image file field. A second reference image currently does not take effect:
  • image + image2: returns 200, but only the first image is used; the second is ignored and the request is still billed
  • Repeated image or repeated image[]: returns 400 File must be attached in a form field with a name starting with 'image'
The OpenAI SDK’s multi-image form client.images.edit(image=[f1, f2]) does not work either. We will update this page once multi-image fusion is restored.
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)

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
Explicitly saying “keep everything else the same” is the most effective technique with this model and preserves as much of the original as possible.

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; only 1 is supported for now. png / jpg / webp

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