GPT-Image-2 Guide

Prerequisites

gpt-image-2 belongs to the Sora group. Before calling it, create a token whose group is sora.

See Create an API Token for how, and pick sora under "Token group".

Choose the group correctly

If the token group is not sora, calling gpt-image-2 will report that the model doesn't exist or that you lack permission.

How to Call

OpenAI splits image capabilities into three API families: Images API, Responses API, and Chat Completions API. TokenFlow's gpt-image-2 only supports the Images API — use it for generation.

Option 1: Images API (recommended)

The Images API has two endpoints:

• Text-to-image: POST https://tokenflow.run/v1/images/generations
• Image edit / image-to-image: POST https://tokenflow.run/v1/images/edits

Beginners can just follow the example and pass model and prompt, with n set to 1. Use the image field to upload a reference image when you need to edit.

Text-to-image: /v1/images/generations

Request example

curl --location 'https://tokenflow.run/v1/images/generations' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SORA_GROUP_TOKEN' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "An orange cat wearing an orange scarf hugging an otter, warm illustration style",
    "size": "3840x2160",
    "quality": "high",
    "output_format": "png",
    "response_format": "url",
    "n": 1
  }'

Common parameters

Parameter	Description
model	Always gpt-image-2
prompt	Image description, required
n	Number of images. Keep it at 1 (loop your own requests for multiples)
size	Output size, e.g. 1024x1024, 1536x1024, 3840x2160, or auto
quality	low / medium / high / auto
output_format	png / jpeg / webp
output_compression	Compression 0–100, only for jpeg/webp
background	opaque or transparent
response_format	url (default) or b64_json

Image edit / image-to-image: /v1/images/edits

This endpoint uploads images via multipart/form-data. image is the binary image file, and prompt describes how you want it changed.

Request example

curl --location 'https://tokenflow.run/v1/images/edits' \
  --header 'Authorization: Bearer YOUR_SORA_GROUP_TOKEN' \
  --form 'model="gpt-image-2"' \
  --form 'prompt="Keep the main subject, add a small red stamp in the top-right corner that says DEMO"' \
  --form 'image=@"/path/to/your-image.jpg"' \
  --form 'size="1024x1024"' \
  --form 'quality="high"' \
  --form 'output_format="png"' \
  --form 'response_format="url"'

Common parameters

In addition to the text-to-image parameters, image editing supports:

Parameter	Description
image	The source image to edit (binary file), required
mask	Optional mask for localized edits. Use PNG; transparent areas mark where the model should focus
input_fidelity	Set to high to keep the edit closer to the original

Without a mask, the model edits the whole image based on the prompt.

Size and Quality

Popular sizes

• 1024x1024: square
• 1536x1024: landscape
• 1024x1536: portrait
• 2048x2048: 2K square
• 2048x1152: 2K landscape
• 3840x2160: 4K landscape
• 2160x3840: 4K portrait
• auto: automatic (default)

Size constraints

• Longest side ≤ 3840 px
• Both width and height must be multiples of 16
• Aspect ratio no more than 3:1
• Total pixels no less than 655,360 and no more than 8,294,400

Quality options

low / medium / high / auto (default)

Choosing Parameters

• Simplest text-to-image: pass only model and prompt, with n set to 1.
• Sharper output: add quality: "high".
• Control the size: add size, e.g. 1024x1024 or 1536x1024.
• Get an image URL: use the default response_format: "url".
• Let your program save it: use response_format: "b64_json".
• Don't set n greater than 1; loop your own requests for multiple images.

Response

By default it returns an image download URL:

{
  "created": 1776923999,
  "data": [
    {
      "url": "https://tokenflow.run/file_download/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "revised_prompt": "..."
    }
  ]
}

url is the generated image's address — open it to download. revised_prompt is the prompt the model actually used after rewriting; seeing it is normal, not an error.

If the request includes "response_format": "b64_json", the response is Base64 image data instead:

{
  "created": 1776923999,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "..."
    }
  ]
}

In this case there's usually no url, and the client must decode b64_json into an image file. For most users the default url is easiest to save and share.

Option 2: Responses API (not supported)

Not supported

gpt-image-2 does not support generating images via /v1/responses. Do not use the image_generation tool or input / input_image to call it.

Use /v1/images/generations for text-to-image and /v1/images/edits for image editing.

Option 3: Chat Completions API (not supported)

Not supported

gpt-image-2 does not support generating images via /v1/chat/completions. Do not put messages, image_url, size, quality, or output_format into Chat Completions to generate images.

If your client only supports Chat Completions but must integrate image capabilities, switch to the OpenAI Images API. Don't treat /v1/chat/completions as a substitute for /v1/images/generations.

Using It in Cherry Studio

1. Follow Create an API Token to create a sora-group token, then copy the API key.
2. Download and install Cherry Studio.
3. Open it, click Settings in the bottom-left, go to Model Services, and click Add at the bottom to add a provider.
4. In the add dialog, enter a provider name (e.g. tokenflow-gpt-image-2), set Provider type to New API, and click OK.
5. Find the new provider on the left, paste the sora-group API key into API key, and set API address to https://tokenflow.run.
6. Click Fetch model list on the right of the model area, refresh, and add the gpt-image-2 model.
7. Click the edit button next to gpt-image-2, set Endpoint type to Image generation (OpenAI), and save.
8. Back on the home page, click + at the top and choose Painting from the app list.
9. On the painting page, pick the provider you added under Provider and select gpt-image-2 under Model. For first use, keep image size, quality, sensitivity at auto and count at 1.
10. For prompt-only generation, choose Draw mode at the top, enter a prompt, and send.
11. For image-to-image or localized edits, switch to Edit mode at the top, upload a reference image under Input image, then enter your request and send.

Tips

• Enter https://tokenflow.run as the API address — Cherry Studio appends the compatible endpoint automatically, no need to add /v1.
• If gpt-image-2 isn't in the model list, refresh under Manage first. If it still won't draw, check that Endpoint type is Image generation (OpenAI).
• When calling gpt-image-2 directly in a normal chat page, disable streaming to avoid response parsing errors. The Painting app usually needs no extra handling.

Common Issues

• Failed to fetch: usually the connection was interrupted, often related to a local proxy or network. Check your proxy and confirm Cherry Studio can reach https://tokenflow.run, then retry.
• Unexpected token '<', "<html><h"... is not valid JSON: usually the request received a Cloudflare-style HTML page that the client tried to parse as JSON. Just retry or generate again later.

Note: Long Connections and Proxy Settings

Whether you call the API directly or use gpt-image-2 in a client like Cherry Studio, image generation usually takes longer than a normal chat request — especially in edit mode or at high quality/resolution. If a local proxy, network tool, or intermediate gateway limits long connections, it may drop the connection around 60 seconds, showing up as a timeout, no response, or Failed to fetch.

If a proxy is causing the drop, add this site's domain tokenflow.run to your proxy tool's direct-connect or allowlist rules so API traffic bypasses the proxy. The setup entry differs per tool, but the key is adding a domain rule like domain:tokenflow.run.

Once allowed, these requests can wait longer and return normally. To reduce uncontrollable network interruptions, keep image requests going directly to tokenflow.run rather than through a proxy or relay that limits long connections.