Edit images
Endpoint
POST
/v1/images/editsOpenAI Images API compatible. Upload the source image as multipart/form-data with an edit instruction. It takes about as long as generation; set the client timeout to 300 seconds.
Request
content-type is multipart/form-data; authenticate with Authorization: Bearer sk-moyiapi-xxxxxx.
Parameters
| Form field | Type | Required | Notes |
|---|---|---|---|
model |
string | Yes | gpt-image-2 |
image |
file | Yes | The source image |
prompt |
string | Yes | The edit instruction |
mask |
file | No | Mask image; transparent areas mark the editable region. Same size as the source image |
n |
integer | No | Number of images, default 1 |
size |
string | No | Output size as WIDTHxHEIGHT, for example 1024x1024, or auto |
quality |
string | No | low, medium, high, or auto |
background |
string | No | transparent, opaque, or auto |
input_fidelity |
string | No | How closely the source image's details are preserved, high or low |
output_format |
string | No | png (default), jpeg, or webp |
output_compression |
integer | No | 0 to 100, applies to jpeg and webp only |
stream |
boolean | No | Set to true for SSE streaming. The event format depends on the upstream channel: usually the same as Generate images (image.generation.chunk … image.generation.result, ending with [DONE]); it can also be OpenAI-native events ending with event: image_generation.completed, whose b64_json carries the result |
partial_images |
integer | No | 0 to 3 |
user |
string | No | Your own end-user identifier, passed through unchanged |
Other fields pass through in the OpenAI Images API format.
Response
{
"created": 1752345600,
"data": [{"b64_json": "iVBORw0KGgo..."}],
"size": "1024x1024",
"quality": "…",
"output_format": "png",
"background": "…",
"moderation": "…",
"usage": {"…": "…"}
}
| Field | Notes |
|---|---|
data[].b64_json |
The Base64-encoded result image |
size / quality / output_format / background / moderation |
The output settings that were applied |
usage |
Usage for this request |
created and data[].b64_json are always returned; whether size, quality, output_format, background, moderation, and usage appear depends on the upstream channel that served the call, so treat them as optional. In our tests, background set to transparent did not produce an alpha channel on the edits endpoint.
Examples
curl https://api.moyiapi.com/v1/images/edits \
-H "Authorization: Bearer sk-moyiapi-xxxxxx" \
-F model="gpt-image-2" \
-F image="@photo.png" \
-F prompt="Replace the background with a starry sky"
Errors
| HTTP status | error.type |
When it happens |
|---|---|---|
| 401 | missing_auth_credential / invalid_api_key / invalid_bearer_token |
Authentication failed; see Authentication |