Skip to main content
POST
Image editing: edit a reference image or fuse several
The interactive Playground on the right accepts local file uploads. Enter your API Key in Authorization (format: Bearer sk-xxx), choose an image file, fill in prompt and model, and send.
🔴 This endpoint requires multipart/form-data file uploadSending JSON to /v1/images/edits always returns 400:
This matters especially if you are integrating from xAI or the upstream vendor’s documentation: that doc describes a JSON body with a public image URL ({"image": {"type": "image_url", "url": "..."}}), and that form does not work through the APIYI gateway. Follow this page instead.The upside: file upload means no image hosting required — just send the local file, which is simpler than preparing a public URL.The file field must be named image or image[]; images / image_file return 415. prompt is required — omitting it returns 400.
When to use this page: editing one reference image, or fusing several. For prompt-only generation, use the Text-to-Image endpoint.
⚠️ Output dimensions follow the input image and cannot be changedresolution and aspect_ratio are accepted here without error but have no effect — the edited output always matches the input reference image’s dimensions (1280x720 in gives 1280x720 out; 1024x1024 in gives 1024x1024 out).To change the output size, crop or resize the reference image before uploading.
Fusion order is meaningful: image[] accepts 1-3 reference images, and the upload order is what “image 1 / image 2 / image 3” refers to in the prompt. State it explicitly, e.g. “put the subject from image 1 into the scene from image 2, keeping image 2’s art style”.

Code Examples

Python (OpenAI SDK, single image)

Python (raw requests, single image)

Python (multi-image fusion, 1-3 files)

cURL

Node.js (native fetch + FormData)

Browser JavaScript

Parameter Reference

This family does not support mask inpainting. To limit the scope of a change, describe it precisely in the prompt — for example “change only the scarf to red, keep everything else exactly the same”. The model follows such constraints closely.

Editing Behaviour and Prompt Style

The editing endpoint preserves the input image’s art style, composition, palette and subject identity, changing only what the prompt specifies. For stable results:
Explicitly saying “keep everything else unchanged” is the single most effective technique with this model. For fusion, always refer to “image 1 / image 2” matching the image[] upload order.

Response Format

Response field pitfalls
  • Each data[] entry contains either url or b64_json depending on response_format — never both.
  • revised_prompt is not returned — do not assume it exists.
  • b64_json is raw base64 with no data:image/...;base64, prefix — decode it directly.
  • created is always 0 and cannot be used as a timestamp.
  • Output dimensions are determined by the input image, so do not predict width/height from request parameters.
usage cannot be used for reconciliation: prompt_tokens is always 1000 x n, a placeholder. Editing costs the same as text-to-image at a flat rate per image; use the APIYI Console billing records for actual charges.

Authorizations

Authorization
string
header
required

API Key created in the APIYI Console

Body

multipart/form-data
model
enum<string>
default:grok-imagine-image
required

Model ID

Available options:
grok-imagine-image,
grok-imagine-image-quality
prompt
string
required

Editing instruction. State what to change and explicitly ask for everything else to stay put, e.g. Change the scarf color to bright RED. Keep everything else exactly the same.

Example:

"Change the scarf color to bright RED. Keep everything else exactly the same."

image
file
required

Reference image file. For multi-image fusion repeat the image[] field (1-3 files); upload order is what "image 1 / image 2 / image 3" refers to in the prompt. Accepted formats: png / jpg / webp.

n
integer
default:1

Number of output images, 1-10. Independent of the number of reference images

Required range: 1 <= x <= 10
Example:

1

response_format
enum<string>
default:url

Response format. url returns a direct link; b64_json returns raw base64 (no data: prefix)

Available options:
url,
b64_json
Example:

"url"

Response

Image generated successfully

created
integer

Creation timestamp. Always 0 for this model — do not use it for timing

Example:

0

data
object[]

Array of image results, length equals the requested n

usage
object

Placeholder values — do not use for billing reconciliation. prompt_tokens is always 1000 x n