Skip to content
API Reference

GPT Image (Edits)

Edit, extend, or combine existing images with the GPT Image family. The same endpoint serves every supported GPT Image model, with the same parameters as text-to-image generation plus the image and mask inputs.

POST https://llm.siraya.ai/v1/images/edits

Supported Models

Model ID Description
gpt-image-2 Image editing with the GPT Image 2 model.
gpt-image-2.5-flare Speed-optimized GPT Image 2.5 editing.
gpt-image-2.5-sunburst Quality-optimized GPT Image 2.5 editing. Slower than Flare, with higher output quality.

For text-to-image generation with these models, see GPT Image.

Authorization string Required
Your API Key (e.g., `Bearer `).

Body

model string Required
The ID of the model to use (e.g. gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst).
prompt string Required
Instructions for the edit or transformation.
image_urls array Required
A list of input image URLs or base64 data URLs — up to 16 images per request.
mask_url string
A mask URL or base64 data URL marking the region to edit. Must be a PNG with an alpha channel (RGBA) and the same dimensions as the input image. Fully transparent pixels mark the region to edit; a mask without an alpha channel is rejected.
n integer Default: 1
The number of images to generate (1-10).
size string Default: auto
The dimensions of the edited image. Any WIDTHxHEIGHT value is accepted as long as both sides are multiples of 16, the aspect ratio is between 1:3 and 3:1, and the size does not exceed 3840x2160. Use auto to let the model pick.
quality string Default: auto
The quality of the edited image. Possible values: low, medium, high, auto — plus xhigh and max on the GPT Image 2.5 models.
background string Default: auto
The background type for the edited image. Possible values: transparent, opaque, auto. A transparent background requires output_format: png.
output_format string Default: png
The encoding of the returned image. Possible values: png, jpeg.
output_compression integer Default: 100
The compression level for the output image (0-100). Only valid with output_format: jpeg.
moderation string Default: auto
The content moderation level. Possible values: low, auto. 
curl https://llm.siraya.ai/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  --data-raw '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Replace the background with a sunset beach and keep the subject unchanged",
    "image_urls": [
        "https://example.com/your-image-1.png"
    ],
    "n": 1,
    "size": "1536x1024",
    "quality": "high",
    "output_format": "png"
}'

import requests

url = "https://llm.siraya.ai/v1/images/edits"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API_KEY>"
}
data = {
    "model": "gpt-image-2.5-flare",
    "prompt": "Replace the background with a sunset beach and keep the subject unchanged",
    "image_urls": [
        "https://example.com/your-image-1.png"
    ],
    "n": 1,
    "size": "1536x1024",
    "quality": "high",
    "output_format": "png"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Example Response

{
    "created": 1774716098,
    "data": [
        {
            "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zUAAAAg3..."
        }
    ]
}

Image Inputs

The edits endpoint takes images as references, not file uploads — they travel in the JSON body, in image_urls (and mask_url for a mask). Every entry accepts either form:

Form Value When to use
Public URL https://example.com/photo.png The image is already hosted; the router fetches it.
Base64 data URL data:image/png;base64,<BASE64> The image is a local file.

A data URL is the MIME type plus the base64-encoded bytes — e.g. data:image/png;base64,iVBORw0KGgoAAAANSUhEU... or data:image/jpeg;base64,/9j/4AAQSkZJRg.... Raw base64 without the data: prefix is not accepted.

Sending a local file as base64

import base64
import requests

def to_data_url(path, mime="image/png"):
    with open(path, "rb") as f:
        return f"data:{mime};base64," + base64.b64encode(f.read()).decode()

response = requests.post(
    "https://llm.siraya.ai/v1/images/edits",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer <API_KEY>"
    },
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "Replace the background with a sunset beach and keep the subject unchanged",
        "image_urls": [to_data_url("base_image.png")],
        "mask_url": to_data_url("mask.png"),
        "size": "1536x1024",
        "quality": "high"
    },
)

print(response.json())

Base64 grows the payload by roughly a third, so prefer URLs for large images or when sending many inputs at once.

Masks must be RGBA PNGs (with an alpha channel) of the same dimensions as the image they apply to. Transparent pixels mark the area to edit.

Visit the Models Directory to see all supported image-to-image models.