Common Interface

The GPT Image common interface supports image generation and editing: omit image to generate an image, or provide image to edit it according to prompt.

Endpoint

Item	Value
Endpoint	`POST https://api.tokenhub.belivestudios.com/v1/images/generations`
Authentication	`Authorization: Bearer sk-your-key`
Content-Type	`application/json`

Generate an image

Omit the image parameter to generate an image:

{
  "model": "gpt-image-2",
  "prompt": "An orange cat on a futuristic rooftop, cinematic light, photorealistic",
  "size": "2048x2048",
  "quality": "high",
  "n": 1,
  "response_format": "url"
}

Edit an image

Add an image array to edit an image. Each item can be an image URL or a Base64 data URL:

{
  "model": "gpt-image-2",
  "prompt": "Keep the subject and composition; replace the background with Shanghai at night",
  "size": "2048x2048",
  "quality": "high",
  "n": 1,
  "response_format": "url",
  "input_fidelity": "high",
  "image": [
    "https://example.com/source.png"
  ]
}

curl example

curl https://api.tokenhub.belivestudios.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2",
  "prompt": "Keep the subject and composition; replace the background with Shanghai at night",
  "size": "2048x2048",
  "quality": "high",
  "n": 1,
  "response_format": "url",
  "input_fidelity": "high",
  "image": [
    "https://example.com/source.png"
  ]
}'

Request parameters

Parameter	Type	Required	Description
`model`	string	yes	GPT Image model ID; use a model available in the console.
`prompt`	string	yes	Image generation or editing instruction.
`image`	array	no	Reference image array. Supports image URLs or Base64 data URLs; providing it edits an image, while omitting it generates an image.
`input_fidelity`	`high` \| `low`	no	Controls fidelity to the input image when `image` is provided.
`size`	string	no	Output size, such as `1024x1024`, `1536x1024`, or `2048x2048`.
`quality`	`low` \| `medium` \| `high` \| `auto`	no	Image quality.
`n`	integer	no	Number of images, from `1` to `10`.
`response_format`	`url` \| `b64_json`	no	Select URL or Base64 output; send it only when the current endpoint supports it.
`background`	`transparent` \| `opaque` \| `auto`	no	Image background mode.
`output_format`	`png` \| `jpeg` \| `webp`	no	Output image format.
`output_compression`	integer	no	JPEG or WebP compression level from `0` to `100`.
`moderation`	`low` \| `auto`	no	Content moderation level.
`stream`	boolean	no	Whether to stream the response.
`user`	string	no	End-user identifier.

Response

Image generation and reference-image editing use the same response structure. In URL response mode, the generated image URL is in data[0].url.

{
  "created": 1787888579,
  "data": [
    {
      "b64_json": "",
      "revised_prompt": "",
      "url": "https://cdn.aiznt.com/relay-temp-images/20260828/b13c70b8-5e24-4936-a54f-d158aadf980a.jpg"
    }
  ]
}

Field	Type	Description
`created`	integer	Unix timestamp, in seconds, when the response was created
`data`	array	List of generated image results
`data[].url`	string	Temporary URL for the generated image
`data[].b64_json`	string	Base64 image data; normally an empty string in URL response mode
`data[].revised_prompt`	string	Server-revised prompt; normally an empty string when none is provided

In Base64 response mode, read the image data from data[].b64_json. Each result normally contains only one usable image-data field, so follow the actual response.

Temporary image URL

Download and store the image promptly after receiving the response. Do not use the temporary URL as permanent storage.