Skip to content
HopBase Docs
Sign in

Create image

OpenAI Images-compatible text-to-image: GPT Image, Gemini Banana and Seedream; Seedream and Gemini also take reference images here.

POST/v1/images/generations

Generates images from a prompt. GPT Image and Gemini return data[].b64_json; Seedream returns data[].url (valid for 24 hours). Seedream and the two Gemini groups also do image-to-image on this endpoint via image / images.

Parameters and limits differ by model: select a model below and the parameter table switches with it. The numbers come from the specs exported by the plugins' validation code (the same source as /spec/models/<model>.json). When GPT Image generation takes longer than about 40 seconds, the server sends 200 first and writes whitespace keep-alives, so a later failure is still a 200. Decide success by whether the response body contains error, and set the client read timeout to at least 300 seconds.

Kling and Midjourney are also submitted on this endpoint, but always asynchronously (202 + id; poll with Get video task). Select "Kling" or "Midjourney" in the model picker to see them. For Grok Imagine, see Grok Imagine image generation.

  • GPT Image does not support the official streaming field partial_images; omit it. stream: true returns HopBase Images SSE, not per-image preview events.
  • output_compression, moderation, user and response_format are passed through only in synchronous text-to-image JSON and synchronous multipart edits; JSON edits and async tasks do not keep these fields. GPT Image async keeps only model, prompt, n, size, quality, background, output_format, input_fidelity and the images / mask used for editing.
  • Gemini billing: "Gemini (all models, incl. image)" is billed a flat price per image (same for 1K / 2K / 4K); "Gemini Official Direct" is billed by tokens (output tokens × price).
  • The Chat Completions to Images bridge keeps only the first 6 reference images; to use 14, call this endpoint directly.

Headers

Authorization:requiredstring

Bearer sk-…: an API key created in the console under API keys; its group must include the requested model

Prefer:optionalstring

respond-async: GPT Image / Gemini immediately return 202 Accepted with task_id and status_url; then poll GET /v1/images/tasks?task_id=…. Recommended for large 2K / 4K images. Seedream ignores this header and returns synchronously as usual

Valuesrespond-async

Body parametersJSON

ModelOpen in image request builder Model docs
Group: GPT Image (all models). Read results from data[].b64_json. Up to 16 reference images.
model:required"gpt-image-2"

First confirm that GET /v1/models for the current key includes this ID

prompt:requiredstring

Generation or editing instruction; empty returns 400 prompt must not be empty. The gateway sets no length limit; the official cap applies

LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length1–32000 chars

size:optional"auto" or string

E.g. 1024x1024, 2048x2048, 3840x2160. Invalid sizes return 400 before generation and are not billed; 1K / 2K / 4K are not accepted

Limitsauto or WxH: sides multiples of 16, each side ≤ 3840, long-to-short ratio ≤ 3:1, total pixels 655360–8294400

quality:optionalstring

Higher tiers produce more output tokens and cost more: at 1024x1024, measured output is about 200 tokens for low, 1,760 for high, 3,120 for xhigh and 7,020 for max

Valuesautolowmediumhigh

LimitsNot validated by the gateway, forwarded as-is; higher tiers produce more output tokens

n:optionalinteger

Some groups support only 1; larger values return 400. Values ≤ 0 are treated as 1

Range1–10Default1

background:optionalstring

transparent requires png or webp; transparent backgrounds on 2.0 are a preview capability

Valuesautoopaquetransparent

output_format:optionalstring

Sets the format of the decoded b64_json

Valuespngjpegwebp

output_compression:optionalinteger

jpeg / webp only; kept only in synchronous generations JSON and multipart edits

Range0–100Default100

moderation:optionalstring

Does not turn off content safety checks

Valuesautolow

user:optionalstring

End-user identifier string; not a HopBase account ID, and it does not change billing attribution

response_format:optionalstring

Always returned as b64_json whatever you pass; you cannot get a download link via url, so omit it

stream:optionalboolean

true switches to HopBase Images SSE (keepalives are sent meanwhile; only the last data: event is the Images JSON, ending with [DONE]), not OpenAI's native per-image preview events. Keep it false in SDKs

Limitstrue returns HopBase Images SSE; keep false in SDKsDefaultfalse

input_fidelity:optionalstring

Compatibility field; GPT Image 2 processes reference images at high fidelity by default, so omit it

Valueslowhigh

  • transparent requires png or webp
  • output_compression applies only to jpeg / webp

Returns

200Synchronous success

202Accepted asynchronously: GPT Image / Gemini with Prefer: respond-async; always for Kling and Midjourney

created:optionalinteger

Unix seconds

data:requiredarray of object

One entry per image

usage:optionalobject

May be returned

Errors

400Invalid parameters (rejected before generation, not billed); content safety block safety_rejected
401Missing, invalid or expired API key (missing_api_key / invalid_api_key / api_key_expired)
402Balance, or key / member / department quota, exhausted (insufficient_quota)
404The model is not in this key's group (model_not_found), or the path does not belong to the group (route_not_found)
413Request body over 60 MB (request_too_large)
429Account or key concurrency cap reached (user_concurrency_limit / apikey_concurrency_limit), with Retry-After
GPT Image error messages
# size: follow the size rules above
size must be WIDTHxHEIGHT or auto
size side length exceeds 3840px (4096x2048)
size width and height must be multiples of 16 (1000x1000)
size aspect ratio must not exceed 3:1 (3840x1024)
size total pixel count must be at least 655360 (512x512=262144)
size total pixel count must not exceed 8294400 (3840x3840=14745600)

# empty prompt
prompt must not be empty

# edits JSON: put references in "image" as strings or {"url": ...}; "images" is not read
/v1/images/edits requires at least one image
image object is missing the url field
image must be a data URL or an http(s) URL

# remote references: a public URL that returns image/*, at most 25 MiB
image download returned HTTP 404
image is too large
image Content-Type is not image/*: text/html
reference image URL must not point to an internal address
image is too large, please compress it to under 4MB and retry

# content safety (error.code: safety_rejected)
Your request was rejected by the safety system.

# HTTP 413
Request body exceeds the size limit (60 MB)
Gemini error messages
# Gemini (all models, incl. image)
prompt must not be empty
n must be between 1 and 10 for model gemini-3-pro-image
n=3 is too large for 4K output on model gemini-3-pro-image; at most 2 images per request at this size (response size limit); lower n or send separate requests
model gemini-3.1-flash-image does not support tier 4K; supported: 1K, 2K
model gemini-3-pro-image: size "big" is not valid; expected WIDTHxHEIGHT (any aspect ratio, mapped to the nearest official tier) or 1K/2K/4K
aspect_ratio "7:3" is not supported for model gemini-3-pro-image; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_size "4K" is not supported for model gemini-3.1-flash-image; supported: 1K, 2K
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
mask is not supported for Gemini image models; remove mask and describe the region to edit in the prompt
too many reference images: at most 14 are supported for this model, got 15

# Gemini Official Direct
missing prompt
Gemini image generation does not support stream=true; send a non-streaming request
n must be at most 10
n=6 is too large for 2K output on model gemini-3.1-flash-image; at most 5 images per request at this size (response size limit); lower n or send separate requests
Images generations only accepts a JSON request body: ...
size 4K is not supported for model gemini-3.1-flash-image; supported tiers: 1K, 2K
size "banana" is not valid for model gemini-3-pro-image; use auto, WIDTHxHEIGHT (e.g. 1024x1024, mapped to the nearest supported aspect ratio and capped at the model's largest tier), or one of: 1K, 2K, 4K
image_config.aspect_ratio "7:3" is not supported; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_config.image_size "4K" is not supported for model gemini-3.1-flash-image; allowed values: 1K, 2K
mask is not supported for model gemini-3-pro-image; remove mask and describe the region to edit in the prompt
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
reference image 1: reference image exceeds the 20MB limit
reference image 1: reference image URL must not point to an internal address
reference image 1: reference image download returned HTTP 404
reference image 1: reference file is not a supported image type
Seedream error messages
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size   # e.g. "size": "auto"
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216
size aspect ratio must be between 1:16 and 16:1
missing prompt
response_format only supports url
only a single output is supported (n=1)
model seedream-4-5 only supports output_format jpeg
optimize_prompt_options must be an object
image must be a URL/data URL string or an array of strings
every item in the image array must be a URL or data URL string
image must not be empty
at most 10 reference images are supported
reference image 1 is invalid: data URL must be base64-encoded
reference image 1 is invalid: unsupported image format image/svg+xml
reference image 1 is invalid: a single image must not exceed 30 MB
image edits require at least one image reference            # /v1/images/edits without an image
seedream does not accept a traditional mask; ...            # any "mask" on /v1/images/edits, even null

Related