Image editing

POST /v1/images/edits takes one or more reference images plus a prompt and returns a new image. Use it when you already have the picture and want to change it. To generate an image from text alone, use image generation.

The request is multipart/form-data, not JSON, because it carries files. The response has the same shape as /v1/images/generations: the edited image arrives as base64 in data[0].b64_json.

curl -X POST https://api-gateway.merge.dev/v1/images/edits \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -F "model=openai/gpt-image-2" \
  -F "prompt=Recolor the mug blue; change nothing else" \
  -F "[email protected]"

The OpenAI SDK’s images.edit works against the https://api-gateway.merge.dev/v1 base URL. The /v1/openai base URL does not serve the image endpoints.

Request fields

Field	Description
`model`	Required. A model whose route accepts image input and produces images, such as `openai/gpt-image-2`
`prompt`	Required. Text description of the edit
`image`	Required. One to sixteen reference images (PNG, JPEG, or WebP). Repeat the field, or use `image[]`, for more than one
`mask`	Optional PNG with an alpha channel. Transparent areas mark where the first image is edited
`n`, `size`, `quality`, `background`, `input_fidelity`, `output_format`, `output_compression`, `moderation`, `response_format`, `user`	Optional. Forwarded to the provider unchanged, so accepted values are the provider’s
`vendor`, `customer`	Optional. Vendor pin and end-customer scope, as on the other media endpoints

Streaming partial images is not supported; stream=true fails with 400 stream_unsupported. Model aliases resolve on the chat surfaces only, so name the canonical model.

Model support and limits

An edit needs a route that lists image in both capabilities.input and capabilities.output on GET /v1/models. A text-only image model rejects an edit with 400 image_input_unsupported before any provider call. Filter by image input and image output in the model catalog for the current list.

Limit	Value	Error
Images per request	16	`400 too_many_images`
Per file	50 MB	`400 image_too_large`
Per request, images and mask combined	100 MB	`400 uploads_too_large`

Pricing

Uploaded images bill as image-input tokens at the route’s image-input rate (pricing.input_image_per_million on GET /v1/models); the prompt bills at the text-input rate and the output image at the image-output rate, as on /v1/images/generations. The response usage.input_tokens_details carries the image_tokens and text_tokens split, and cost is the server-computed USD amount for the request.

Next steps

Image generation

Generate images from a text prompt with a dedicated endpoint or inline in chat

Video generation

Generate video from text and media inputs