---
title: "POST /v1/images/edits"
method: POST
path: "/v1/images/edits"
---

# POST /v1/images/edits

`POST /v1/images/edits`

## Request body

- EditsRequest
  - `images` object[], required — Input image references to edit. For GPT Image models, you can provide up to 16 images. Each object should provide either `file_id` or `image_url`.
    - `file_id` string — The File API ID of an uploaded image.
    - `image_url` string, uri — A fully qualified URL or base64-encoded data URL.
  - `prompt` string, required — Text prompt describing the desired edit. GPT Image models support up to 32,000 characters; `dall-e-2` supports up to 1,000 characters.
  - `mask` object — Optional mask image reference. Provide exactly one of `file_id` or `image_url`.
    - `file_id` string — The File API ID of an uploaded mask image.
    - `image_url` string, uri — A fully qualified URL or base64-encoded data URL.
  - `background` 'transparent' | 'opaque' | 'auto' — Sets the transparency of the output image background. Applies only to GPT Image models. Choose `transparent`, `opaque`, or `auto` (default). Transparent backgrounds require `png` or `webp` output format.
  - `input_fidelity` 'high' | 'low' — Controls how closely the output preserves details from the input image. Choose `high` or `low`; defaults to `low`. Applies only to GPT Image models.
  - `model` 'gpt-image-1.5' | 'gpt-image-1' | 'gpt-image-2', required — The model to use for image editing.
  - `moderation` 'low' | 'auto' — Moderation level for GPT Image models. Choose `low` or `auto`.
  - `n` integer — Number of images to generate, default 1. Available range `1-10`.
  - `output_compression` integer — Compression level for generated images (0-100). Applies only to GPT Image models with `output_format` set to `webp` or `jpeg`; defaults to 100.
  - `output_format` 'png' | 'jpeg' | 'webp' — Return format for generated images. Applies only to GPT Image models. Choose `png` (default), `jpeg`, or `webp`.
  - `partial_images` integer — Number of partial images to return in the streaming response, from `0` to `3`; defaults to 0. Available only when `stream` is `true`.
  - `quality` string — Image quality. `auto` (default) automatically selects the best quality for the model. GPT Image models support `high`, `medium`, and `low`; `dall-e-2` only supports `standard`.
  - `response_format` 'url' | 'b64_json' — Return data format. Only `dall-e-2` supports `url` or `b64_json`; URLs are valid for 60 minutes. GPT Image models always return `b64_json`.
  - `size` string — Image size. GPT Image models support `1024x1024`, `1536x1024`, `1024x1536`, and `auto` (default); `dall-e-2` supports `256x256`, `512x512`, `1024x1024`.
  - `stream` boolean — Whether to stream edit progress. When enabled, use `partial_images` to receive partial image events.
  - `user` string — A unique identifier representing your end-user, which can help OpenAI monitor and detect abuse.

## Response `200`

Request successful, returns Base64 format image generation results

- object
  - `created` integer, required — Generation timestamp (seconds)
  - `data` object[], required — Image generation result list
    - `b64_json` string, required — Base64 encoded string of generated image
  - `usage` object, required — Token usage (must return for Base64 format)
    - `input_tokens` integer, required — Input token count
    - `input_tokens_details` object, required
      - `image_tokens` integer, required — Image token count
      - `text_tokens` integer, required — Text token count
    - `output_tokens` integer, required — Output token count
    - `total_tokens` integer, required — Total token count

## Other responses

- `400` — Parameter error
- `401` — Authorization failed

---

[API](https://skmtc.net/ttapi/apis/flowmusic-api-docs.md) · [All operations](https://skmtc.net/ttapi/apis/flowmusic-api-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ttapi/flowmusic-api-docs/versions/f27f8a59dbd0/schema)