Skip to main content
POST
GPT-Image-2 · Image-to-image

Introduction

GPT-Image-2 edits reference images from text instructions through POST /v1/images/edits. Use it for inpainting, restyling, and multiple references. Describe what should change and remain. Input images are always processed at high fidelity; omit input_fidelity. Use mask for regional editing.

Authentication

string
required
Bearer $GRAVITEX_API_KEY
string
required
application/json / multipart/form-data

Request parameters

images / 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 mask to identify the edit region. 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;

JSON

multipart/form-data

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

Streaming

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 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. quality supports auto / low / medium / high, default auto. Transparent backgrounds are in preview for image-2; when available, use background=transparent with PNG or WebP. This guide covers raster workflows and does not assume 2.6 complexity, GIF, SVG, or 2.5 markup support.

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.
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.

Official references