Edit Image

Edits an existing image based on a prompt and optional mask. Compatible with the OpenAI Images Edits API (multipart/form-data). Only OpenAI-compatible upstream providers serve this endpoint; Anthropic and Gemini providers are skipped automatically. Streaming (Server-Sent Events) is supported only for `gpt-image-*` models when `stream=true` is set. No image editing models are currently online — check `GET /v1/models` for current availability before relying on this endpoint.

Authorization

ApiKeyAuth

AuthorizationBearer <token>

Your Yolo Router API key. Format: Authorization: Bearer sk-...

In: header

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

model*string

Model ID (required). No image editing models are currently enabled — any value here will fail with model_not_found until one is re-enabled; check GET /v1/models for current availability before submitting a request. Image editing requires an OpenAI-compatible upstream provider — common model families are gpt-image-1 and dall-e-2, referenced below for their differing parameter support.

prompt*string

Text description of the desired edit.

image*|array<>

The image(s) to edit. dall-e-2 accepts a single square PNG under 4MB. gpt-image-1 accepts a single image or up to 16 images (PNG/JPEG/WebP) — pass multiple files by repeating the image[] form field (same field name with array suffix).

mask?file

Optional PNG mask whose fully transparent areas (alpha = 0) indicate where the image should be edited. Must match the dimensions of image.

Formatbinary

n?integer

Number of images to generate. The router uses this value for per-image billing.

Default1

size?string

Output image size. Allowed values depend on the model — e.g. 256x256, 512x512, 1024x1024 for dall-e-2; 1024x1024, 1536x1024, 1024x1536 for gpt-image-1.

quality?string

Image quality preset. Routing/billing read this field; values follow the upstream model (standard/hd for legacy models, low/medium/high for gpt-image-1).

response_format?string

Format of the returned image (url or b64_json). gpt-image-1 always returns b64_json regardless of this field.

Value in"url" | "b64_json"

stream?boolean

If true, the response is streamed as Server-Sent Events. Supported only for gpt-image-* models; setting true for unsupported models returns 400.

Defaultfalse

background?string

Background mode for the generated image. gpt-image-1 only.

Default"auto"

Value in"transparent" | "opaque" | "auto"

input_fidelity?string

Controls how closely the edit preserves the input image's details. gpt-image-1 only.

Default"low"

Value in"low" | "high"

moderation?string

Content-moderation strictness applied by the upstream model. gpt-image-1 only.

Default"auto"

Value in"auto" | "low"

output_compression?integer

Compression level (0–100) for webp/jpeg outputs. gpt-image-1 only.

Default100

Range0 <= value <= 100

output_format?string

Encoding for the returned image bytes. gpt-image-1 only.

Default"png"

Value in"png" | "jpeg" | "webp"

partial_images?integer

Number of image_edit.partial_image SSE frames to emit before the final image. Effective only when stream=true on gpt-image-* models.

Default0

Range0 <= value <= 3

user?string

Optional stable identifier representing the end user, forwarded to the upstream for abuse monitoring.

Response Body

`application/json`

curl -X POST "https://api.yolorouter.com/v1/images/edits" \  -F model="<image-model-id>" \  -F prompt="Replace the sky with a dramatic sunset" \  -F image="string"

{
  "created": 0,
  "data": [
    {
      "url": "string",
      "b64_json": "string",
      "revised_prompt": "string"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0,
    "input_tokens_details": {
      "text_tokens": 0,
      "image_tokens": 0
    },
    "output_tokens_details": {
      "text_tokens": 0,
      "image_tokens": 0
    }
  },
  "background": "string",
  "output_format": "string",
  "quality": "string",
  "size": "string"
}

Empty

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "type": "insufficient_quota",
    "code": "insufficient_quota",
    "message": "Quota exceeded"
  }
}

Empty

{
  "error": {
    "type": "string",
    "code": "string",
    "message": "string"
  }
}

Empty

Authorization

Request Body

Response Body

200application/json

400

401application/json

403application/json

500

502application/json

504

`application/json`

`application/json`

`application/json`