Documentation

Edit image

POST/v1/images/edits

Edits or extends images with a prompt. Accepts the OpenAI SDK multipart upload or a JSON body with image URLs.

Start

Help

Python Setup

Node.js Setup

PHP Setup

API Reference

Request

Content-Type

multipart/form-data or application/json

model

required — an image model id that lists POST /v1/images/edits in the catalog

image / image[]

required (multipart) — up to 16 files, 32MB each

images

required (JSON) — array of { image_url }; or a single image string

mask

optional (multipart) — one file, not billed as an input image

prompt

required by most models

optional — 1 to 10, defaults to 1

…

size, quality, background and other OpenAI-compatible fields are forwarded unchanged

cURL example

terminal

curl https://apily.pro/v1/images/edits \
  -H "Authorization: Bearer apily_your-api-key" \
  -F model=gpt-image-1 \
  -F image=@photo.png \
  -F prompt="Add a red hat"

Error responses

Symptom	Cause	Fix
`400 Missing required parameter: image`	No `image`/`image[]` file part (multipart) or no `images`/`image` field (JSON).	Attach at least one input image.
`400 Missing required parameter: model`	No model field.	Add a `model` field with a catalog id.
`400 Invalid value for n`	`n` is not a whole number from 1 to 10.	Send `n` between 1 and 10, or omit it (defaults to 1).
`401 Missing API key`	No auth header was sent.	Apily accepts `Authorization: Bearer …` and `x-api-key: …`.
`401 Invalid API key`	Key copied with stray spaces, truncated, or revoked.	Copy the key whole from the API page in your Apily account, the `apily_` prefix included.
`403 Email not verified`	Your Apily account's email address isn't verified yet.	Verify your email from the banner in the Apily app, then retry.
`404 Model not found`	The model ID isn't in the Apily catalog.	Copy the exact ID from `GET /v1/models` or the Models page in your account.
`503 Model temporarily unavailable`	The model exists, but no upstream provider is reachable right now.	Retry in a moment — it usually recovers within a minute. Switch models if it keeps happening.
`402 Insufficient balance`	Your token balance can't cover the request's estimated cost.	Top up your balance on the Billing page in your Apily account.
`429 Too many requests`	Your account sent more than 600 `/v1/*` requests in a minute — all of your API keys share one budget. The body is `{ error: { message, type: "rate_limit_error", code: "rate_limit_exceeded" }, retryAfterSeconds }`.	Wait the `Retry-After` header (or `retryAfterSeconds`) before retrying, and lower request concurrency.
`502 Upstream error`	The upstream provider returned an unexpected error.	Retry the request; try a different model if it persists.

Image models are billed per image. Per-image models charge the model price × the number of images returned (n, 1–10). Token-priced models charge the prompt text, each input image and the generated image(s) by the real usage the provider returns. Before the call a conservative upper bound is reserved (up to 10,000 output tokens per requested image), so a request can get 402 even when the final cost would fit your balance; the unused part of the reserve is returned right after the response.