Skip to content

GPT Image

Generate and edit images with GPT Image: parameters, responses, and caveats.

ItemValue
Base URLhttps://api.hop-base.com/v1
Generate imagesPOST /v1/images/generations
Edit imagesPOST /v1/images/edits
Query async tasksGET /v1/images/tasks?task_id=…
Key groupGPT Image (all models); gpt-image-2.5-flare and gpt-image-2.5-sunburst also work with GPT Official Direct (Azure)

Requests are synchronous by default and return Base64 images; add Prefer: respond-async to run an async task. Keys from chat-only groups such as Codex Plus and Codex Pro get 404 for gpt-image-*. The GPT Official Direct (Azure) group returns images synchronously as Base64.

Available models

ModelModel IDquality tiersOfficial price
GPT Image 2.6 Flaregpt-image-2.6-flarelow / medium / high / xhigh / max$5 / $30/ 1M tokens
GPT Image 2.6 Sunburstgpt-image-2.6-sunburstlow / medium / high / xhigh / max$5 / $30/ 1M tokens
GPT Image 2.5 Flaregpt-image-2.5-flarelow / medium / high / xhigh / max$5 / $30/ 1M tokens
GPT Image 2.5 Sunburstgpt-image-2.5-sunburstlow / medium / high / xhigh / max$5 / $30/ 1M tokens
GPT Image 2gpt-image-2low / medium / high$5 / $30/ 1M tokens

Which to pick: Flare is the everyday default; Sunburst has higher fidelity and is slower than Flare at the same settings; gpt-image-2 is general-purpose, and its ID is gpt-image-2, not gpt-image-2.0. Reference timings for one 1024x1024 image: about 14 seconds at low on either 2.5 model; at high, Flare takes about 19 seconds and Sunburst about 37.

GPT Image 2.6 (released 2026-11-04) costs the same as 2.5 and adds the complexity parameter plus SVG and animated GIF output. Flare is the speed-focused 2.6 model and Sunburst the quality-focused one. Reference timings for one 1024x1024 image: Flare about 14 seconds at low, 20 at high, 29 at xhigh, and 46 at max; Sunburst about 29 seconds at low, 66 at high, and 90 at xhigh.

Request parameters

Generate

POST /v1/images/generations with a JSON body.

ParameterRequiredType and limitsDefaultNotes
modelRequiredstring—One of the IDs above
promptRequiredstring, ≤ 32,000 characters—Must be non-empty after trimming
sizeOptionalauto or WIDTHxHEIGHT—Rules below the table
qualityOptionalauto / low / medium / high—2.5 and 2.6 add xhigh / max
nOptionalinteger, 1–101Some groups accept only 1
backgroundOptionalauto / opaque / transparent—Transparent needs png / webp
output_formatOptionalpng / jpeg / webp; 2.6 also svg / gifpngFormat of the decoded image
output_compressionOptionalinteger, 0–100100jpeg / webp only
moderationOptionalauto / low—Does not turn off safety checks
userOptionalstring—End-user identifier
streamOptionalbooleanfalsetrue switches to Images SSE
response_formatOptionalstring—Omit it
input_fidelityOptionallow / high—Compatibility field; omit it
complexityOptionallow / medium / highhigh2.6 only; planning before rendering
frame_countOptionalinteger, 2–1692.6 gif only; number of frames
frame_duration_msOptionalinteger, 20–2,0002002.6 gif only; milliseconds per frame

For size, WIDTHxHEIGHT sides must be multiples of 16, each side ≤ 3840, aspect ratio ≤ 3:1, and total pixels 655,360–8,294,400. The 1K / 2K / 4K shorthands are not accepted; an invalid size returns 400 before generation and is not billed.

Higher quality tiers emit more output tokens and cost more. GPT Image always returns b64_json whatever response_format says; user is not a HopBase account ID and does not change who is billed.

GPT Image 2.6 only. complexity sets how much the model plans before rendering; it has no separate fee, and any other value returns 400. output_format: "svg" returns an SVG and needs n = 1. output_format: "gif" returns an animated GIF; size is then the size of one frame, and all frames are tiled into one sheet no larger than 3840 per side, so use auto or a small frame such as 512x512 (large frames fail, and the total-pixel minimum does not apply to GIF frames). The result still arrives as b64_json; decode it and save it as .svg or .gif. Images from 2.6 carry OpenAI C2PA content credentials, which any C2PA verifier can check.

Edit

POST /v1/images/edits accepts every parameter above, plus references and a mask. Prefer multipart/form-data for local files; JSON with URL / Data URL references also works.

ParameterRequiredType and limitsDefaultNotes
imageRequired1–16 images—Multipart: image or repeated image[]
maskOptionalPNG with an alpha channel—Transparent pixels mark the edit area
markupOptionalTransparent PNG overlay—2.6 only; annotations to follow; not with mask

JSON image can be a URL / Data URL string, a string array, or {"url": …} objects. images is not read, and bare base64 or file_id is not accepted.

Markup-guided edits (GPT Image 2.6 only). Draw circles, arrows, or notes on a transparent PNG the same size as the first input image and send it as markup: a multipart file part, or in JSON a URL or Data URL. The model applies the edits the annotations describe, for example a red circle labelled "add a green leaf here". markup cannot be combined with mask; the gateway keeps its alpha channel and scales it to the first image.

A remote URL must be ≤ 25 MiB with an image/* Content-Type, and must not point to an internal address; it may be compressed to 4 MiB before forwarding. The whole request body is capped at 60 MB; larger bodies return 413.

Async

Add the HTTP header Prefer: respond-async to a generation or edit request; the body stays the same. It is a header, not a JSON parameter.

Async tasks keep only model, prompt, n, size, quality, background, output_format, input_fidelity, complexity, frame_count, frame_duration_ms, and edit images / mask / markup; other fields are dropped.

Response

Sync

FieldTypeNotes
createdintegerUnix seconds
data[].b64_jsonstringBase64 image; decode and save in the output_format format
usage.input_tokensintegerInput tokens (may be returned)
usage.output_tokensintegerOutput tokens (may be returned)
usage.total_tokensintegerTotal (may be returned)
usage.costnumberThe charge for this request in CNY (the same charge as usage.cost_usd), up to 6 decimal places. Present on every billed sync success
usage.cost_usdnumberThe USD amount actually deducted from your balance, up to 8 decimal places, the same amount as this request's usage record
usage.currencystringThe currency of usage.cost, always CNY
errorobjectOn failure: message, type, code
{
  "created": 1760000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1760,
    "total_tokens": 1802,
    "cost": 0.3264,
    "cost_usd": 0.048,
    "currency": "CNY"
  }
}

A successful sync response also carries this request's actual charge: usage.cost, usage.cost_usd, and usage.currency in the body, with the same values in the response headers X-HopBase-Cost, X-HopBase-Cost-USD, and X-HopBase-Currency. If the server has already sent the 200 headers to keep a long generation alive (about 40 seconds or more), the headers carry no charge; reconcile against usage.cost_usd (USD, matching your usage record) or usage.cost (CNY) in the body. Failures that are not charged carry none of them. See Charges.

Generations over 40 seconds: the status stays 200 - check the error field.

After about 40 seconds, the server returns HTTP 200 and keeps writing whitespace at the start of the body to hold the connection; the full JSON follows later. From then on the status stays 200 even if generation fails, so check the body for error and set the read timeout to at least 300 seconds.

Streaming (stream: true)

The response switches to Images SSE: while waiting, the stream sends keepalive comment lines starting with a colon, and the last data: event holds the complete Images JSON, followed by [DONE]. These are not OpenAI's native progressive-image events.

: hopbase-keepalive

data: {"created":1760000000,"data":[{"b64_json":"iVBORw0KGgoAAA..."}]}

data: [DONE]

Async tasks

Submitting returns 202 Accepted right away; the Location response header points to the same query URL:

{
  "object": "image.task",
  "task_id": "your-task-id",
  "status": "pending",
  "status_url": "/v1/images/tasks?task_id=your-task-id"
}

Query only with GET /v1/images/tasks?task_id=…; putting the task ID in the path is not supported. pending, processing, and retrying mean in progress; completed and failed are terminal.

FieldTypeNotes
task_idstringTask ID
statusstringTask status
result_contentstringWhen completed: Markdown, one line per image
errorstringOnly when failed: English reason, no code
usage.costnumberThe charge for this task in CNY (the same charge as usage.cost_usd)
usage.cost_usdnumberThe USD amount actually deducted from your balance for this task, the same as its usage record
usage.currencystringThe currency of usage.cost, always CNY
{
  "task_id": "your-task-id",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "usage": {
    "cost": 1.36,
    "cost_usd": 0.2,
    "currency": "CNY"
  }
}

result_content holds relative paths; prepend https://api.hop-base.com to download. usage appears once the task is completed or failed, and only the key that created the task sees it.

Examples

Generate

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A shiba inu under a cherry tree, Japanese watercolor",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png"
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > result.png

The curl example needs jq installed.

SVG, animated GIF, and markup edits (2.6)

# SVG (n must be 1)
curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "A flat line icon of a paper plane",
    "output_format": "svg",
    "complexity": "low"
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > icon.svg

# Animated GIF: size is the size of one frame
curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "A shiba inu wagging its tail, pixel art",
    "size": "512x512",
    "output_format": "gif",
    "frame_count": 9,
    "frame_duration_ms": 200
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > shiba.gif
# Markup-guided edit: markup.png is a transparent overlay with the annotations
curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -F "model=gpt-image-2.6-flare" \
  -F "prompt=Follow the annotations in the markup" \
  -F "image=@plant.png" \
  -F "markup=@markup.png" \
  -F "output_format=png" \
  | jq -r '.data[0].b64_json' | base64 --decode > edited.png

Edit (multiple references + mask)

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Fill the masked area with a vase styled like the second image" \
  -F "image[]=@scene.png" \
  -F "image[]=@style.png" \
  -F "mask=@mask.png" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "output_format=png"

For JSON, replace the files with URLs: "image": ["https://example.com/scene.png", "https://example.com/style.png"] and "mask": "https://example.com/mask.png".

Async

# 1. Submit and receive 202 + task_id
curl -i https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cinematic futuristic city at night",
    "size": "2048x2048"
  }'

# 2. Poll with the task_id from the first response
curl "https://api.hop-base.com/v1/images/tasks?task_id=your-task-id" \
  -H "Authorization: Bearer sk-your-key"

Caveats

  • For 2K / 4K images, prefer async so long requests are not cut off by CDN timeouts.
  • Set the client read timeout for sync requests to at least 300 seconds.
  • size accepts only auto or WIDTHxHEIGHT; tier shorthands return 400.
  • xhigh / max exist only on the 2.5 and 2.6 models.
  • complexity, markup, SVG / GIF output, frame_count, and frame_duration_ms exist only on the two 2.6 models.
  • For GIF output, use size: "auto" or a small frame size such as 512x512; large frame sizes fail.
  • background: "transparent" requires png or webp; transparency on gpt-image-2 is a preview capability.
  • The official streaming field partial_images (0–3) is not supported; omit it.
  • With official SDKs, keep stream at its default false.
  • The gateway resizes the mask to the first reference, and pixel-perfect preservation outside it is not guaranteed.
  • The result_content URL opens without a key, so do not share it publicly and download it to your own storage soon.

Common errors

Invalid parameters return 400 before generation and are not billed. Content-safety rejections also return 400 and are not billed, with error.code set to safety_rejected.

ErrorFix
size must be WIDTHxHEIGHT or auto and other size errorsFollow the size rules above
prompt must not be emptySend a non-empty prompt
n must be 1 for this model in the current groupSplit into separate requests
/v1/images/edits requires at least one imagePut references in image, not images
image download returned HTTP 404Use a public URL the server can fetch
Your request was rejected by the safety system.Rephrase the prompt or change the reference
Request body exceeds the size limit (60 MB) (413)Compress the images, or send URLs
HTTP 200 with error in the bodyFailed after keepalive started; act on error.message

Billing

Billed by token; higher quality emits more output tokens. Measured at 1024x1024: about 200 at low, 1,760 at high, 3,120 at xhigh, and 7,020 at max. GPT Image 2.6 emits more at the lower tiers, about 820 at low and 1,450 at medium, so 2.6 low / medium images cost more than on 2.5; high and above are the same. For async tasks, the actual charge is usage.cost_usd in the query result (in USD; usage.cost is the same charge in CNY), and a failed task usually shows 0. For sync requests, the charge is usage.cost_usd / usage.cost in the response itself.

Prices are on the model cards above and in the signed-in model catalog.

Next steps