GPT-Image-2.5 · Image-to-image

curl --request POST \
  --url https://api.gravitex.ai/v1/images/edits \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>'

import requests

url = "https://api.gravitex.ai/v1/images/edits"

headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'}
};

fetch('https://api.gravitex.ai/v1/images/edits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gravitex.ai/v1/images/edits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gravitex.ai/v1/images/edits"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gravitex.ai/v1/images/edits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'

response = http.request(request)
puts response.read_body

POST

images

edits

GPT-Image-2.5 · Image-to-image

curl --request POST \
  --url https://api.gravitex.ai/v1/images/edits \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>'

import requests

url = "https://api.gravitex.ai/v1/images/edits"

headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'}
};

fetch('https://api.gravitex.ai/v1/images/edits', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gravitex.ai/v1/images/edits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gravitex.ai/v1/images/edits"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gravitex.ai/v1/images/edits")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'

response = http.request(request)
puts response.read_body

Introduction

GPT-Image-2.5 Flare and Sunburst edit reference images from text instructions. Use POST /v1/images/edits for background replacement, recoloring, restyling, inpainting, and multiple references. Describe what should change and what should remain in prompt. Provide JSON image references or multipart uploads. Use either mask or a transparent markup overlay for local edits, never both. Choose Flare for quick iteration and Sunburst when detail and editing precision matter most.

Choose a model

Model ID	Best suited for
`gpt-image-2.5-flare`	Fast iteration and interactive generation
`gpt-image-2.5-sunburst`	Detailed visual work, complex layouts, and precise edits

Both models use the endpoints, parameters, and response structure documented here. Examples use Flare; switch to Sunburst by replacing model. Set other fields for your workload.

Authentication

string

required

Bearer $GRAVITEX_API_KEY

string

required

application/json / multipart/form-data

Request parameters

Parameter	Type	Description
`model`	string	Required: gpt-image-2.5-flare or gpt-image-2.5-sunburst
`prompt`	string	Required description or edit instruction; up to 32,000 characters
`quality`	string	auto / low / medium / high / xhigh / max; default auto
`size`	string	auto or WxH with dimensions divisible by 16; model size and pixel budgets apply
`n`	integer	1–10; default 1
`background`	string	auto / opaque / transparent; use png or webp for transparent raster output
`output_format`	string	png / jpeg / webp; default png
`output_compression`	integer	0–100, default 100; JPEG / WebP only
`moderation`	string	auto / low; default auto
`safety_identifier`	string	Stable hashed end-user identifier, up to 128 characters; replaces user
`stream`	boolean	Default false. When true, read SSE events instead of parsing a single JSON response
`partial_images`	integer	Raster streaming only: 0–3, default 0. Requested preview count; fewer previews may arrive
`images` / `image[]`	array / file	Required for JSON: at least one reference via `images: [{"image_url": "HTTPS URL or base64 data URI"}]`. Use image[] files for multipart
`markup`	object / file	Optional transparent PNG overlay for the first reference image; mutually exclusive with mask
`mask`	object / file	Optional PNG mask with the same dimensions as the first reference and an alpha channel. Fully transparent areas indicate the edit region. Applies to the first image only; incompatible with markup

images / markup / mask

For JSON, use images: [{"image_url": "https://..."}] or base64 data URIs. For multipart, upload files as image[]. According to the platform integration note, the gateway converts JSON edits to multipart and does not support OpenAI file_id references. Use a transparent PNG markup layer matching the first input image after orientation. Include transparent pixels. JSON uses markup.image_url; multipart uploads a markup file. Cannot be combined with mask. Use mask to identify the edit region, or markup, never both. JSON accepts image_url; multipart accepts a file.

Request examples

Examples read the platform token from GRAVITEX_API_KEY in your terminal environment. For uploads, curl -F generates Content-Type and boundary automatically; do not manually set a bare multipart/form-data header.

Use accessible HTTPS URLs or base64 data URIs. The multipart example downloads the official image first. Platform integration guidance does not support OpenAI file_id references; historical 2.6 status codes are not a guarantee for 2.5.

JSON

curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ]
}'

multipart/form-data

curl --fail --location "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp" -o kitchen.webp

curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change the vase to blue. Keep everything else unchanged." \
  -F "image[]=@kitchen.webp"

Markup-guided editing

curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ],
  "markup": {
    "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/markup-vase-overlay-gpt-image-2-6.png"
  }
}'

user is deprecated and retained for compatibility. Use safety_identifier; a non-empty value takes precedence, otherwise the API falls back to user.

Mask-guided inpainting

curl https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Add a pink flamingo float in the masked pool area. Keep the rest of the room unchanged.",
  "images": [
    {
      "image_url": "https://cdn.openai.com/API/docs/images/sunlit_lounge.png"
    }
  ],
  "mask": {
    "image_url": "https://cdn.openai.com/API/docs/images/mask.png"
  },
  "quality": "medium"
}'

Streaming

curl --no-buffer https://api.gravitex.ai/v1/images/edits \
  -H "Authorization: Bearer $GRAVITEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare",
  "prompt": "Change the vase to blue. Keep everything else unchanged.",
  "quality": "medium",
  "size": "1024x1024",
  "stream": true,
  "partial_images": 1,
  "images": [
    {
      "image_url": "https://developers.openai.com/images/platform/guides/image-prompting/kitchen.webp"
    }
  ]
}'

Limits and notes

The default size is auto. Explicit WxH dimensions must be multiples of 16, with aspect ratios between 1:3 and 3:1. The image-2 guide specifies a maximum edge of 3840px and 655,360–8,294,400 pixels; the 2.5 reference also requires model-specific edge and pixel limits. Confirm the actual 2.6 budget, especially for GIF, rather than assuming older limits. The official Images API accepts 1–16 JSON edit references in PNG, JPEG, or WebP, each under 50MB. A mask is a PNG with an alpha channel matching the first reference. Transparent areas guide editing; masks do not guarantee a pixel-exact hard boundary. Lack of gateway validation does not remove upstream limits. This page includes explicitly documented GPT-Image-2.5 workflows. It does not assume the 2.6-specific complexity, GIF, or SVG guidance applies to 2.5. A field in a shared API schema does not guarantee support on every model or channel.

Response example

This is a schematic non-streaming response. Image data and token counts are illustrative, not an actual generation. Decode b64_json to the selected file format; do not save the Base64 text directly as an image.

{
  "created": 1794268800,
  "data": [
    {
      "b64_json": "<BASE64_IMAGE_DATA>"
    }
  ],
  "usage": {
    "input_tokens": 100,
    "output_tokens": 824,
    "total_tokens": 924
  }
}

With stream=true, read SSE events for previews and the final image. Do not parse the entire response as one JSON object.

Response and billing

Non-streaming examples return image bytes as b64_json. Do not request response_format=url expecting a hosted image URL. Equal token rates do not imply equal cost per image; use actual usage. Returns data[].b64_json and usage. Decode Base64 before saving images. The following are OpenAI standard rates, not a GravitexAI quote. Cached rates are official reference rates. For GPT Image 2 / 2.5, the guide limits cached input discounts to the Responses image tool; they do not apply to direct Images API calls, including edits. Platform billing follows the console.

Type	USD / 1M tokens
Text input	$5.00
Cached text input	$1.25
Image input	$8.00
Cached image input	$2.00
Image output	$30.00

API documentation

Chat & text

Safety & audio

Image Series

Video Series

Completions & Embeddings

Interface module

GPT-Image-2.5 · Image-to-image

Introduction

Choose a model

Authentication

Request parameters

images / markup / mask

Request examples

JSON

multipart/form-data

Markup-guided editing

Mask-guided inpainting

Streaming

Limits and notes

Response example

Response and billing

Official references

​Introduction

​Choose a model

​Authentication

​Request parameters

​images / markup / mask

​Request examples

​JSON

​multipart/form-data

​Markup-guided editing

​Mask-guided inpainting

​Streaming

​Limits and notes

​Response example

​Response and billing

​Official references

Introduction

Choose a model

Authentication

Request parameters

images / markup / mask

Request examples

JSON

multipart/form-data

Markup-guided editing

Mask-guided inpainting

Streaming

Limits and notes

Response example

Response and billing

Official references