Image editing

POST /v1/images/edits takes one or more reference images plus a prompt and returns a new image, to change or combine pictures you already have. The request is multipart/form-data; the response matches image generation: base64 in data[].b64_json, plus usage and cost.

curl 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 and change nothing else" \
  -F "image=@product-shot.png"

An edit needs a route listing image in both capabilities.input and capabilities.output; filter by both in the model catalog.

Reference

Field	Notes
`model`	Required. A canonical model ID, since `@alias/...` returns `400 alias_not_supported`.
`prompt`	Required
`image`	Required. 1 to 16 PNG, JPEG, or WebP files. Repeat the field, or use `image[]`.
`mask`	PNG with alpha. Transparent areas mark where the first image is edited.
`n`	1 to 10
`output_compression`	0 to 100
`size`, `quality`, `background`, `input_fidelity`, `output_format`, `moderation`, `response_format`, `user`	Forwarded to the vendor, which sets the accepted values
`vendor`	Pin the execution vendor
`customer`	Customer UUID to scope the key, budget, and usage to

Error	Cause
`400 image_required`	No `image` file
`400 image_empty`	An uploaded file is empty
`400 too_many_images`	More than 16 images
`400 image_too_large`	A file over 50 MB
`400 uploads_too_large`	Images and mask over 100 MB combined
`400 image_input_unsupported`	The route can’t take and produce images
`400 stream_unsupported`	`stream=true`
`400 invalid_customer`	`customer` isn’t a UUID

Reference images bill as image-input tokens at pricing.input_image_per_million, the prompt at the text rate, and the output at the image-output rate. usage.input_tokens_details splits image_tokens from text_tokens.

Next steps

Image generation

Generate images from a text prompt

Video generation

Video from text and media inputs