Edit Image

Creates an edited or extended image from one or more source images and a text prompt. The endpoint supports GPT Image models and dall-e-2.

Endpoint

Model Selection

The examples below use per-use models. To use an official model, replace the request's model value.

Examples

curl https://api.tokenhub.belivestudios.com/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-belive-studios-key" \
  -d '{
    "images": [
      {
        "image_url": "https://example.com/source-image.png"
      }
    ],
    "prompt": "Add a watercolor effect to this image",
    "model": "gpt-image-2.5-sunburst",
    "quality": "high",
    "size": "1024x1024"
  }'

{
  "created": 0,
  "background": "transparent",
  "data": [
    {
      "b64_json": "b64_json",
      "revised_prompt": "revised_prompt",
      "url": "https://example.com"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    },
    "output_tokens": 0,
    "total_tokens": 0,
    "output_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    }
  }
}

Request Parameters

Input and Model

images

Type: object[], required

Input image references to edit. GPT Image models accept up to 16 images. Each object supports:

For multipart/form-data uploads, pass one or more files using the image[] field.

prompt

Type: string, required

A text description of the desired edit, from 1 to 32,000 characters.

background

Type: "transparent" | "opaque" | "auto" | null, optional

Sets the output background. gpt-image-2.5-sunburst, gpt-image-2.5-flare, and their 2026-09-08 snapshots support opaque and transparent backgrounds. Transparent backgrounds are also available for other supported GPT Image models. Support for gpt-image-2 and gpt-image-2-2026-04-21 is in preview. When using transparent, set output_format to png or webp.

input_fidelity

Type: "high" | "low" | null, optional

Controls fidelity to the original input images.

mask

Type: object | null, optional

References a mask by URL or uploaded file ID. Provide exactly one of image_url or file_id.

model

Type: string | null, optional

The image-editing model. Platform model names are grouped as follows:

• Per-use models: gpt-image-2, gpt-image-2.5-sunburst, and gpt-image-2.5-flare
• Official models: gpt-image-2-2026-04-21, gpt-image-2.5-sunburst-2026-09-08, and gpt-image-2.5-flare-2026-09-08

Output and Streaming Controls

moderation

Type: "low" | "auto" | null, optional

Sets the moderation level for GPT Image models.

n

Type: number | null, optional

The number of edited images to generate, from 1 to 10.

output_compression

Type: number | null, optional

Compression level for jpeg or webp output, from 0 to 100.

output_format

Type: "png" | "jpeg" | "webp" | null, optional

The output image format. Supported by GPT Image models.

partial_images

Type: number | null, optional

The number of partial images to generate in a streaming response, from 0 to 3. When set to 0, the response sends only the final image in one event. The final image may arrive before all requested partial images if it is generated sooner.

quality

Type: "low" | "medium" | "high" | "xhigh" | "max" | "auto" | null, optional

Output quality for GPT Image models. Defaults to auto. All GPT Image models support low, medium, and high; gpt-image-2.5-sunburst, gpt-image-2.5-flare, and their 2026-09-08 snapshots also support xhigh and max.

size

Type: string | "auto" | null, optional

GPT Image models support the standard sizes 1024x1024, 1536x1024, and 1024x1536; models that allow automatic sizing also support auto.

gpt-image-2, gpt-image-2-2026-04-21, both GPT Image 2.5 models, and their 2026-09-08 snapshots support arbitrary WIDTHxHEIGHT resolutions, such as 1536x864. Both dimensions must be divisible by 16, the aspect ratio must be between 1:3 and 3:1, and the request must meet the model's current pixel and edge limits. Resolutions above 2560x1440 are experimental; the maximum is 3840x2160.

stream

Type: boolean | null, optional

Streams partial image results as events.

user

Type: string, optional

A unique identifier for the end user that can help monitor and detect abuse.

Response

The endpoint returns an ImagesResponse object.

data Fields

usage Fields