Edit image

post

https://api.macpaw.com/ai/v1/images/edits

Create an edited or extended image from a source image and a prompt. Image editing is routed to OpenAI or Google depending on the model you choose.

Request and response format follow the OpenAI Images Create Edit API as a common contract. For Google models, see Gemini API image generation.

Required body fields: image, prompt, and model. All other fields are optional and depend on the provider and model you select via model — for example mask, size, n, response_format, quality, input_fidelity, output_format, background, edit_mode, and mask_mode. OpenAI GPT Image (gpt-image-1) and Google Gemini image models accept different subsets; see property descriptions below and provider documentation.

model uses the provider/model identifier format (e.g. openai/gpt-image-1 or google/gemini-3.1-flash-image), consistent with other AI Gateway operations.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Common contract based on the OpenAI Images Create Edit API. Only image, prompt, and model are required. All other properties are optional and vary by provider and model — see field descriptions and Gemini API image generation.

image

file

required

Source image to edit. OpenAI (gpt-image-1): PNG, WebP, or JPG, <50MB each; up to 16 images may be supported. Google Gemini image models: see Gemini API image generation. Constraints depend on the provider and model.

prompt

string

required

Text description of the desired edit. OpenAI (gpt-image-1): up to 32000 characters. Google: follow Gemini API image generation. Length limits depend on the provider and model.

mask

file

Optional mask image. OpenAI: PNG with transparent pixels marking the edit region; same dimensions as the source image. Google Gemini image models: optional mask when supported by the model; see Gemini API image generation. Whether a mask is required depends on the edit type and provider.

model

string

required

Image editing model id in provider/model format,
e.g. openai/gpt-image-1 or google/gemini-3.1-flash-image.
Required; must not be omitted. Determines which provider is used and which optional fields apply.

integer

1 to 10

Defaults to 1

Number of edited images to return. OpenAI: 1–10 (default 1). Google Gemini image models: depends on the model; see Gemini API image generation. Effective maximum depends on the provider and model.

size

string

Output dimensions when supported. OpenAI (gpt-image-1): 1024x1024, 1536x1024, 1024x1536, or auto. Google Gemini image models: use aspect_ratio and optional image_size when supported — see Gemini API image generation. Allowed values depend on the provider and model.

response_format

string

enum

Defaults to url

How generated images are returned. OpenAI: url (temporary link) or b64_json. Some GPT Image models may always return base64 regardless of this field. Google: normalized to this shape by the gateway. Support depends on the provider and model.

Allowed:

user

string

OpenAI only. Optional end-user identifier for abuse monitoring. Ignored by Google Gemini image models.

quality

string

enum

OpenAI (gpt-image-1) only. Generation quality (low, medium, or high). Ignored by Google Gemini image models.

Allowed:

input_fidelity

string

enum

OpenAI GPT Image models only. How closely the output preserves input image details.

Allowed:

output_format

string

enum

Defaults to png

OpenAI GPT Image models only. File format of the generated image.

Allowed:

background

string

enum

Defaults to auto

OpenAI GPT Image models only. Background transparency. Use transparent with output_format=png for alpha channel.

Allowed:

output_compression

integer

0 to 100

Defaults to 100

OpenAI GPT Image models only. Compression level (0–100) for JPEG and WebP output.

edit_mode

string

enum

Google only (when supported by the model). Edit operation type. See Gemini API image generation.

Allowed:

mask_mode

string

enum

Google only (when supported by the model). How the edit mask is determined when not using an uploaded mask.

Allowed:

mask_dilation

number

0 to 1

Google only (when supported by the model). Mask expansion as a fraction of image width (0–1).

Responses

200Image edited successfully

400Bad request (e.g. missing image file)

401Invalid token

402Insufficient credits

422Validation error (e.g. invalid model)

429Rate limit exceeded

500Internal server error