Create image
OpenAI Images-compatible text-to-image: GPT Image, Gemini Banana and Seedream; Seedream and Gemini also take reference images here.
/v1/images/generationsGenerates images from a prompt. GPT Image and Gemini return data[].b64_json; Seedream returns data[].url by default (valid for 24 hours) and can also use response_format: b64_json. 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: truereturns HopBase Images SSE, not per-image preview events. output_compression,moderation,userandresponse_formatare 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 onlymodel,prompt,n,size,quality,background,output_format,input_fidelityand the images / mask used for editing.- Gemini billing: "Gemini Value (AI Studio / Vertex)" is billed per image at the official per-size price × the group discount (1K / 2K / 4K priced separately); "Gemini Official Direct (Enterprise)" 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.
Charged non-streaming responses return the actual charge for this request: the X-HopBase-Cost / X-HopBase-Cost-USD / X-HopBase-Currency headers, plus cost / cost_usd / currency in the top-level usage object of the body (existing usage fields are kept). cost_usd is the USD amount actually deducted from your balance; cost is the same charge in CNY, and currency is always CNY. Streaming (SSE) responses do not carry it; check Usage in the console. Uncharged responses, such as errors, carry neither. See Account API · Charges.
Headers
Bearer sk-…: an API key created in the console under API keys; its group must include the requested model
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
data[].b64_json. Up to 16 reference images.First confirm that GET /v1/models for the current key includes this ID
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
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
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
Some groups support only 1; larger values return 400. Values ≤ 0 are treated as 1
Range1–10Default1
transparent requires png or webp; transparent backgrounds on 2.0 are a preview capability
Valuesautoopaquetransparent
Sets the format of the decoded b64_json
Valuespngjpegwebp
jpeg / webp only; kept only in synchronous generations JSON and multipart edits
Range0–100Default100
Does not turn off content safety checks
Valuesautolow
End-user identifier string; not a HopBase account ID, and it does not change billing attribution
Always returned as b64_json whatever you pass; you cannot get a download link via url, so omit it
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
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
First confirm that GET /v1/models for the current key includes this ID
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
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
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
Valuesautolowmediumhighxhighmax
LimitsNot validated by the gateway, forwarded as-is; higher tiers produce more output tokens
Some groups support only 1; larger values return 400. Values ≤ 0 are treated as 1
Range1–10Default1
transparent requires png or webp; transparent backgrounds on 2.0 are a preview capability
Valuesautoopaquetransparent
Sets the format of the decoded b64_json
Valuespngjpegwebp
jpeg / webp only; kept only in synchronous generations JSON and multipart edits
Range0–100Default100
Does not turn off content safety checks
Valuesautolow
End-user identifier string; not a HopBase account ID, and it does not change billing attribution
Always returned as b64_json whatever you pass; you cannot get a download link via url, so omit it
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
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
First confirm that GET /v1/models for the current key includes this ID
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
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
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
Valuesautolowmediumhighxhighmax
LimitsNot validated by the gateway, forwarded as-is; higher tiers produce more output tokens
Some groups support only 1; larger values return 400. Values ≤ 0 are treated as 1
Range1–10Default1
transparent requires png or webp; transparent backgrounds on 2.0 are a preview capability
Valuesautoopaquetransparent
Sets the format of the decoded b64_json
Valuespngjpegwebp
jpeg / webp only; kept only in synchronous generations JSON and multipart edits
Range0–100Default100
Does not turn off content safety checks
Valuesautolow
End-user identifier string; not a HopBase account ID, and it does not change billing attribution
Always returned as b64_json whatever you pass; you cannot get a download link via url, so omit it
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
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
First confirm that GET /v1/models for the current key includes this ID
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
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
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
Valuesautolowmediumhighxhighmax
LimitsNot validated by the gateway, forwarded as-is; higher tiers produce more output tokens
Some groups support only 1; larger values return 400. Values ≤ 0 are treated as 1
Range1–10Default1
transparent requires png or webp; transparent backgrounds on 2.0 are a preview capability
Valuesautoopaquetransparent
Sets the format of the decoded b64_json
Valuespngjpegwebpsvggif
jpeg / webp only; kept only in synchronous generations JSON and multipart edits
Range0–100Default100
Does not turn off content safety checks
Valuesautolow
End-user identifier string; not a HopBase account ID, and it does not change billing attribution
Always returned as b64_json whatever you pass; you cannot get a download link via url, so omit it
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
Compatibility field; GPT Image 2 processes reference images at high fidelity by default, so omit it
Valueslowhigh
How much the model plans before rendering; no separate fee. Other values return 400 from the gateway
Valueslowmediumhigh
Default"high"
output_format=gif only: number of frames. For gif, size is 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 size such as 512x512
Range2–16Default9
output_format=gif only: duration of each frame (milliseconds)
Range20–2000Default200
- transparent requires png or webp
- output_compression applies only to jpeg / webp
- n must be 1 when output_format=svg
First confirm that GET /v1/models for the current key includes this ID
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
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
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
Valuesautolowmediumhighxhighmax
LimitsNot validated by the gateway, forwarded as-is; higher tiers produce more output tokens
Some groups support only 1; larger values return 400. Values ≤ 0 are treated as 1
Range1–10Default1
transparent requires png or webp; transparent backgrounds on 2.0 are a preview capability
Valuesautoopaquetransparent
Sets the format of the decoded b64_json
Valuespngjpegwebpsvggif
jpeg / webp only; kept only in synchronous generations JSON and multipart edits
Range0–100Default100
Does not turn off content safety checks
Valuesautolow
End-user identifier string; not a HopBase account ID, and it does not change billing attribution
Always returned as b64_json whatever you pass; you cannot get a download link via url, so omit it
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
Compatibility field; GPT Image 2 processes reference images at high fidelity by default, so omit it
Valueslowhigh
How much the model plans before rendering; no separate fee. Other values return 400 from the gateway
Valueslowmediumhigh
Default"high"
output_format=gif only: number of frames. For gif, size is 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 size such as 512x512
Range2–16Default9
output_format=gif only: duration of each frame (milliseconds)
Range20–2000Default200
- transparent requires png or webp
- output_compression applies only to jpeg / webp
- n must be 1 when output_format=svg
GET /v1/models for the current key is authoritative
If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt
LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars
Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed
LimitsCapped by output tier: 1K ≤ 10, 2K ≤ 5Range1–10Default1
Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size
Values1K2K
Default"1K"
Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size
Values1:12:33:23:44:34:55:49:1616:921:9
Default"1:1"
WxH is never rejected for its ratio: it maps to the closest official ratio, and the tier is derived from the long edge and silently lowered to the model's highest tier. An explicit 1K / 2K / 4K above the model's tier returns 400; if image_size is also sent, it wins
Values1K2K
Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier
In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent
Values1:12:33:23:44:34:55:49:1616:921:9
Values1K2K
Reference images, placed directly in the generations request body; if both are sent, images wins. On "Gemini Official Direct (Enterprise)" each image must be ≤ 20 MiB decoded, and there is no /v1/images/edits
Same as image; if both are sent, images wins
LimitsReference images: a string or array of strings, up to 14
Not supported: sending mask returns 400; describe the region to change in the prompt instead
transparent is not supported (returns 400)
Must not be"transparent"
Not supported; omit it or pass false
Must not betrue
- At most 5 images per request for 2K output (response size limit)
GET /v1/models for the current key is authoritative
If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt
LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars
Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed
LimitsCapped by output tier: 1K ≤ 10, 2K ≤ 5Range1–10Default1
Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size
Values1K2K
Default"1K"
Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size
Values1:12:33:23:44:34:55:49:1616:921:9
Default"1:1"
WxH is never rejected for its ratio: it maps to the closest official ratio, and the tier is derived from the long edge and silently lowered to the model's highest tier. An explicit 1K / 2K / 4K above the model's tier returns 400; if image_size is also sent, it wins
Values1K2K
Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier
In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent
Values1:12:33:23:44:34:55:49:1616:921:9
Values1K2K
Reference images, placed directly in the generations request body; if both are sent, images wins. On "Gemini Official Direct (Enterprise)" each image must be ≤ 20 MiB decoded, and there is no /v1/images/edits
Same as image; if both are sent, images wins
LimitsReference images: a string or array of strings, up to 14
Not supported: sending mask returns 400; describe the region to change in the prompt instead
transparent is not supported (returns 400)
Must not be"transparent"
Not supported; omit it or pass false
Must not betrue
- At most 5 images per request for 2K output (response size limit)
GET /v1/models for the current key is authoritative
If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt
LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars
Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed
LimitsCapped by output tier: 1K ≤ 10, 2K ≤ 5, 4K ≤ 2Range1–10Default1
Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size
Values1K2K4K
Default"1K"
Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size
Values1:12:33:23:44:34:55:49:1616:921:9
Default"1:1"
WxH is never rejected for its ratio: it maps to the closest official ratio, and the tier is derived from the long edge and silently lowered to the model's highest tier. An explicit 1K / 2K / 4K above the model's tier returns 400; if image_size is also sent, it wins
Values1K2K4K
Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier
In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent
Values1:12:33:23:44:34:55:49:1616:921:9
Values1K2K4K
Reference images, placed directly in the generations request body; if both are sent, images wins. On "Gemini Official Direct (Enterprise)" each image must be ≤ 20 MiB decoded, and there is no /v1/images/edits
Same as image; if both are sent, images wins
LimitsReference images: a string or array of strings, up to 14
Not supported: sending mask returns 400; describe the region to change in the prompt instead
transparent is not supported (returns 400)
Must not be"transparent"
Not supported; omit it or pass false
Must not betrue
- At most 5 images per request for 2K output (response size limit)
- At most 2 images per request for 4K output (response size limit)
GET /v1/models for the current key is authoritative
If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt
LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars
Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed
LimitsCapped by output tier: 1K ≤ 10, 2K ≤ 5, 4K ≤ 2Range1–10Default1
Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size
Values1K2K4K
Default"1K"
Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size
Values1:12:33:23:44:34:55:49:1616:921:9
Default"1:1"
WxH is never rejected for its ratio: it maps to the closest official ratio, and the tier is derived from the long edge and silently lowered to the model's highest tier. An explicit 1K / 2K / 4K above the model's tier returns 400; if image_size is also sent, it wins
Values1K2K4K
Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier
In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent
Values1:12:33:23:44:34:55:49:1616:921:9
Values1K2K4K
Reference images, placed directly in the generations request body; if both are sent, images wins. On "Gemini Official Direct (Enterprise)" each image must be ≤ 20 MiB decoded, and there is no /v1/images/edits
Same as image; if both are sent, images wins
LimitsReference images: a string or array of strings, up to 14
Not supported: sending mask returns 400; describe the region to change in the prompt instead
transparent is not supported (returns 400)
Must not be"transparent"
Not supported; omit it or pass false
Must not betrue
- At most 5 images per request for 2K output (response size limit)
- At most 2 images per request for 4K output (response size limit)
GET /v1/models for the current key is authoritative
If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt
LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars
Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed
LimitsCapped by output tier: 1K ≤ 10Range1–10Default1
Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size
Values1K
Default"1K"
Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size
Values1:12:33:23:44:34:55:49:1616:921:9
Default"1:1"
WxH is never rejected for its ratio: it maps to the closest official ratio, and the tier is derived from the long edge and silently lowered to the model's highest tier. An explicit 1K / 2K / 4K above the model's tier returns 400; if image_size is also sent, it wins
Values1K
Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier
In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent
Values1:12:33:23:44:34:55:49:1616:921:9
Values1K
Reference images, placed directly in the generations request body; if both are sent, images wins. On "Gemini Official Direct (Enterprise)" each image must be ≤ 20 MiB decoded, and there is no /v1/images/edits
Same as image; if both are sent, images wins
LimitsReference images: a string or array of strings, up to 14
Not supported: sending mask returns 400; describe the region to change in the prompt instead
transparent is not supported (returns 400)
Must not be"transparent"
Not supported; omit it or pass false
Must not betrue
GET /v1/models for the current key is authoritative
If the model refuses or replies with text only, returns 400 (the message quotes that text) or 502: rephrase the prompt
LimitsMust not be empty after trimming whitespace, otherwise 400 "prompt must not be empty"Length≥ 1 chars
Generated in parallel. All or nothing: if any image fails, the whole request fails and is not billed
LimitsCapped by output tier: 1K ≤ 10Range1–10Default1
Flat top-level form, equivalent to google.image_config.image_size; overrides the tier derived from size
Values1K
Default"1K"
Flat top-level form, equivalent to google.image_config.aspect_ratio; takes precedence over size
Values1:12:33:23:44:34:55:49:1616:921:9
Default"1:1"
WxH is never rejected for its ratio: it maps to the closest official ratio, and the tier is derived from the long edge and silently lowered to the model's highest tier. An explicit 1K / 2K / 4K above the model's tier returns 400; if image_size is also sent, it wins
Values1K
Limitsauto, WxH at any ratio (mapped to the closest official ratio; the tier is derived from the long edge and silently lowered to the model's highest tier), or a model tier
In SDKs it can be written as extra_body.google.image_config; all three forms are equivalent
Values1:12:33:23:44:34:55:49:1616:921:9
Values1K
Reference images, placed directly in the generations request body; if both are sent, images wins. On "Gemini Official Direct (Enterprise)" each image must be ≤ 20 MiB decoded, and there is no /v1/images/edits
Same as image; if both are sent, images wins
LimitsReference images: a string or array of strings, up to 3
Not supported: sending mask returns 400; describe the region to change in the prompt instead
transparent is not supported (returns 400)
Must not be"transparent"
Not supported; omit it or pass false
Must not betrue
Use the full ID returned by GET /v1/models for the current key
Image content, composition, style or editing instruction; for local edits you can describe coordinates, a bbox, arrows or areas drawn on the reference image
LimitsMust not be empty after trimming whitespace, otherwise 400 "missing prompt"Length≥ 1 chars
Invalid values return 400 before generation with the valid range, and are not billed
Values1K1.5K2K
LimitsShorthand 1K / 1.5K / 2K, or WxH: total pixels 921600–4624220, aspect ratio 1:16–16:1
Other values (including null) return 400
Limitsonly a single output is supported (n=1)Default1
url returns a signed link valid for 24 hours; b64_json returns data[].b64_json. A non-streaming group cannot use b64_json (needs stream: true)
Valuesurlb64_json
Default"url"
jpeg only on 4.5
Valuespngjpeg
Must be an object
Valuesstandard
Passing it triggers single- or multi-image image-to-image or editing; /v1/images/edits requires at least 1. URLs are not downloaded or size-checked at submission
LimitsReference images (passing them triggers image-to-image / editing): up to 10; Data URLs ≤ 31457280 bytes each; URLs are not downloaded at submission
seedream-5-0-pro only: true splits one PNG / JPEG input image into a base image plus up to 16 transparent PNG layers; prompt becomes optional and size accepts only 1K / 1.5K / 2K / auto (default auto). About 1.5 minutes at 1K; set your client timeout to ≥ 5 minutes. See Seedream · Layer decomposition
Must not betrue
Defaults to false here (the official default is true); pass true to add a watermark
Defaultfalse
seedream-5-5 / seedream-5-0-pro only: transparent is for image-to-image only and needs exactly one input image with an alpha channel (JPEG / BMP Data URLs return 400); the output is PNG, so output_format: jpeg is not allowed. See Seedream · Transparent background
Valuesopaquetransparent
Default"opaque"
seedream-5-0-lite / seedream-4-5 only: auto turns on group generation, and the model decides from the prompt how many images to make (up to max_images). A failed image comes back in data[].error and is not billed; if all fail, returns 400. The server waits up to about 280 seconds for a non-streaming group, so stream: true is recommended. See Seedream · Group generation
max_images is an integer from 1 to 15, and reference images plus max_images ≤ 15; in multipart write sequential_image_generation_options[max_images] or max_images
seedream-5-0-lite / seedream-4-5 only: true returns SSE, sending image_generation.partial_succeeded / image_generation.partial_failed per image, then image_generation.completed and data: [DONE]. Billed by successful images; streaming responses do not carry the charge fields. See Seedream · Streaming
LimitsNot supported: passing true returns 400 "model seedream-5-5 does not support stream"Must not betrue
Web search is not supported yet; passing it returns 400
- background transparent: exactly one input image with an alpha channel, png output
Use the full ID returned by GET /v1/models for the current key
Image content, composition, style or editing instruction; for local edits you can describe coordinates, a bbox, arrows or areas drawn on the reference image
LimitsMust be non-empty after trimming, otherwise 400 "missing prompt"; optional with layer_decomposition: trueLength≥ 1 chars
Invalid values return 400 before generation with the valid range, and are not billed
Values1K1.5K2K
LimitsShorthand 1K / 1.5K / 2K, or WxH: total pixels 921600–4624220, aspect ratio 1:16–16:1; layer decomposition accepts only 1K / 1.5K / 2K / auto (default auto)
Other values (including null) return 400
Limitsonly a single output is supported (n=1)Default1
url returns a signed link valid for 24 hours; b64_json returns data[].b64_json. A non-streaming group cannot use b64_json (needs stream: true)
Valuesurlb64_json
Default"url"
jpeg only on 4.5
Valuespngjpeg
Must be an object
Valuesstandardfast
Passing it triggers single- or multi-image image-to-image or editing; /v1/images/edits requires at least 1. URLs are not downloaded or size-checked at submission
LimitsReference images (passing them triggers image-to-image / editing): up to 10; Data URLs ≤ 31457280 bytes each; URLs are not downloaded at submission
seedream-5-0-pro only: true splits one PNG / JPEG input image into a base image plus up to 16 transparent PNG layers; prompt becomes optional and size accepts only 1K / 1.5K / 2K / auto (default auto). About 1.5 minutes at 1K; set your client timeout to ≥ 5 minutes. See Seedream · Layer decomposition
Defaultfalse
Defaults to false here (the official default is true); pass true to add a watermark
Defaultfalse
seedream-5-5 / seedream-5-0-pro only: transparent is for image-to-image only and needs exactly one input image with an alpha channel (JPEG / BMP Data URLs return 400); the output is PNG, so output_format: jpeg is not allowed. See Seedream · Transparent background
Valuesopaquetransparent
Default"opaque"
seedream-5-0-lite / seedream-4-5 only: auto turns on group generation, and the model decides from the prompt how many images to make (up to max_images). A failed image comes back in data[].error and is not billed; if all fail, returns 400. The server waits up to about 280 seconds for a non-streaming group, so stream: true is recommended. See Seedream · Group generation
max_images is an integer from 1 to 15, and reference images plus max_images ≤ 15; in multipart write sequential_image_generation_options[max_images] or max_images
seedream-5-0-lite / seedream-4-5 only: true returns SSE, sending image_generation.partial_succeeded / image_generation.partial_failed per image, then image_generation.completed and data: [DONE]. Billed by successful images; streaming responses do not carry the charge fields. See Seedream · Streaming
LimitsNot supported: passing true returns 400 "model seedream-5-0-pro does not support stream"Must not betrue
Web search is not supported yet; passing it returns 400
- Layer decomposition: prompt optional, size tiers only (default auto), exactly one PNG / JPEG input image
- background transparent: exactly one input image with an alpha channel, png output
Use the full ID returned by GET /v1/models for the current key
Image content, composition, style or editing instruction; for local edits you can describe coordinates, a bbox, arrows or areas drawn on the reference image
LimitsMust not be empty after trimming whitespace, otherwise 400 "missing prompt"Length≥ 1 chars
Invalid values return 400 before generation with the valid range, and are not billed
Values2K3K4K
LimitsShorthand 2K / 3K / 4K, or WxH: total pixels 3686400–16777216, aspect ratio 1:16–16:1
Other values (including null) return 400
Limitsonly a single output is supported (n=1)Default1
url returns a signed link valid for 24 hours; b64_json returns data[].b64_json. A non-streaming group cannot use b64_json (needs stream: true)
Valuesurlb64_json
Default"url"
jpeg only on 4.5
Valuespngjpeg
Must be an object
Valuesstandard
Passing it triggers single- or multi-image image-to-image or editing; /v1/images/edits requires at least 1. URLs are not downloaded or size-checked at submission
LimitsReference images (passing them triggers image-to-image / editing): up to 14; Data URLs ≤ 31457280 bytes each; URLs are not downloaded at submission
seedream-5-0-pro only: true splits one PNG / JPEG input image into a base image plus up to 16 transparent PNG layers; prompt becomes optional and size accepts only 1K / 1.5K / 2K / auto (default auto). About 1.5 minutes at 1K; set your client timeout to ≥ 5 minutes. See Seedream · Layer decomposition
Must not betrue
Defaults to false here (the official default is true); pass true to add a watermark
Defaultfalse
seedream-5-5 / seedream-5-0-pro only: transparent is for image-to-image only and needs exactly one input image with an alpha channel (JPEG / BMP Data URLs return 400); the output is PNG, so output_format: jpeg is not allowed. See Seedream · Transparent background
seedream-5-0-lite / seedream-4-5 only: auto turns on group generation, and the model decides from the prompt how many images to make (up to max_images). A failed image comes back in data[].error and is not billed; if all fail, returns 400. The server waits up to about 280 seconds for a non-streaming group, so stream: true is recommended. See Seedream · Group generation
Valuesautodisabled
Limitsauto group generation: the model decides from the prompt how many images to make (up to max_images)Default"disabled"
max_images is an integer from 1 to 15, and reference images plus max_images ≤ 15; in multipart write sequential_image_generation_options[max_images] or max_images
Maximum images in the group; reference images + max_images ≤ 15
Range1–15
seedream-5-0-lite / seedream-4-5 only: true returns SSE, sending image_generation.partial_succeeded / image_generation.partial_failed per image, then image_generation.completed and data: [DONE]. Billed by successful images; streaming responses do not carry the charge fields. See Seedream · Streaming
Defaultfalse
Web search is not supported yet; passing it returns 400
- A non-streaming group cannot use b64_json (stream=true required)
Use the full ID returned by GET /v1/models for the current key
Image content, composition, style or editing instruction; for local edits you can describe coordinates, a bbox, arrows or areas drawn on the reference image
LimitsMust not be empty after trimming whitespace, otherwise 400 "missing prompt"Length≥ 1 chars
Invalid values return 400 before generation with the valid range, and are not billed
Values2K4K
LimitsShorthand 2K / 4K, or WxH: total pixels 3686400–16777216, aspect ratio 1:16–16:1
Other values (including null) return 400
Limitsonly a single output is supported (n=1)Default1
url returns a signed link valid for 24 hours; b64_json returns data[].b64_json. A non-streaming group cannot use b64_json (needs stream: true)
Valuesurlb64_json
Default"url"
jpeg only on 4.5
Valuesjpeg
Must be an object
Valuesstandard
Passing it triggers single- or multi-image image-to-image or editing; /v1/images/edits requires at least 1. URLs are not downloaded or size-checked at submission
LimitsReference images (passing them triggers image-to-image / editing): up to 14; Data URLs ≤ 31457280 bytes each; URLs are not downloaded at submission
seedream-5-0-pro only: true splits one PNG / JPEG input image into a base image plus up to 16 transparent PNG layers; prompt becomes optional and size accepts only 1K / 1.5K / 2K / auto (default auto). About 1.5 minutes at 1K; set your client timeout to ≥ 5 minutes. See Seedream · Layer decomposition
Must not betrue
Defaults to false here (the official default is true); pass true to add a watermark
Defaultfalse
seedream-5-5 / seedream-5-0-pro only: transparent is for image-to-image only and needs exactly one input image with an alpha channel (JPEG / BMP Data URLs return 400); the output is PNG, so output_format: jpeg is not allowed. See Seedream · Transparent background
seedream-5-0-lite / seedream-4-5 only: auto turns on group generation, and the model decides from the prompt how many images to make (up to max_images). A failed image comes back in data[].error and is not billed; if all fail, returns 400. The server waits up to about 280 seconds for a non-streaming group, so stream: true is recommended. See Seedream · Group generation
Valuesautodisabled
Limitsauto group generation: the model decides from the prompt how many images to make (up to max_images)Default"disabled"
max_images is an integer from 1 to 15, and reference images plus max_images ≤ 15; in multipart write sequential_image_generation_options[max_images] or max_images
Maximum images in the group; reference images + max_images ≤ 15
Range1–15
seedream-5-0-lite / seedream-4-5 only: true returns SSE, sending image_generation.partial_succeeded / image_generation.partial_failed per image, then image_generation.completed and data: [DONE]. Billed by successful images; streaming responses do not carry the charge fields. See Seedream · Streaming
Defaultfalse
Web search is not supported yet; passing it returns 400
- A non-streaming group cannot use b64_json (stream=true required)
Kling image model ID; a video model ID returns 400
Valueskling-image-expandkling-image-o1kling-image-v2-1kling-image-v2-1-i2ikling-image-v2-1-multi-refkling-image-v3kling-image-v3-omni
Provide this and/or a non-empty images
Case-insensitive; OpenAI-style values such as high or standard are rejected. Tiers per model: kling-image-v3 1k / 2k; kling-image-v3-omni 1k / 2k / 4k; kling-image-o1 1k / 2k / 4k; kling-image-v2-1 1k / 2k; kling-image-v2-1-i2i 1k / 2k; kling-image-v2-1-multi-ref 1k / 2k; kling-image-expand 1k
Values1k2k4k
Default"1k"
Billed per image actually produced
Range1–9Default1
Reference images; each item has either url (public HTTP(S) address) or file_id, not both, and must not carry usage. file_id must be a Kling asset available to the current key, not a Seedance asset ID. Counts: kling-image-v3 0–1; kling-image-v3-omni 0–10; kling-image-o1 0–10; kling-image-v2-1 none accepted; kling-image-v2-1-i2i exactly 1; kling-image-v2-1-multi-ref 2–4; kling-image-expand exactly 1
Public HTTP(S) URL
Kling asset ID; use either this or url
Image expansion kling-image-expand only: all four ratios are numbers from 0 to 2, omitted means 0, and they cannot all be 0. The expanded area must not exceed 3x the original: (1+left+right) × (1+top+bottom) ≤ 3. A non-empty extra on other models returns 400
Expansion ratio
Range0–2
Expansion ratio
Range0–2
Expansion ratio
Range0–2
Expansion ratio
Range0–2
Exact match
Image description, optionally followed by -- parameters (--ar aspect ratio, --hd native 2K, --s, --c, --weird, --iw, --sref + --sw, --no, --seed, --tile, --exp). A description is required: it cannot be only -- parameters, and it cannot contain ::. The --ar ratio must not exceed 14:1, or 4:1 with --hd. --q, --niji, --repeat, --oref, --cref, --stealth, --stop, --draft and --profile return 400
Length≥ 1 chars
Reference image, 0–1 items; each item has either url (public absolute HTTP(S) address) or file_id, not both, and must not carry usage
Items≤ 1
Public absolute HTTP(S) address
Asset ID; use either this or url
Must be 4: each task always produces 4 images, billed per image returned
Default4
Omit it: a non-empty value returns 400. For 2K, write --hd in the prompt
Omit it: a non-empty object returns 400
Returns
200Synchronous success
202Accepted asynchronously: GPT Image / Gemini with Prefer: respond-async; always for Kling and Midjourney
Response headers
The charge for this request in CNY (the same charge as X-HopBase-Cost-USD), up to 6 decimal places, such as 0.0816. Sent only when the request is charged; not sent on streaming (SSE) responses. When image generation takes longer than about 40 seconds the headers have already been sent, so read usage.cost in the body instead
The USD amount actually deducted from your balance for this request, the same amount as its usage record, up to 8 decimal places, such as 0.012; sent only together with X-HopBase-Cost
The currency of X-HopBase-Cost, always CNY
Unix seconds
One entry per image
GPT Image / Gemini: Base64 image data; save it after decoding according to output_format. Gemini may return JPEG, so check mime_type. Seedream also returns this field with response_format: b64_json
Seedream: signed direct link valid for 24 hours; once expired, the only option is to regenerate
Seedream group generation: this image failed (usually content moderation) and is not billed
Error code
Failure reason
Seedream: actual output WIDTHxHEIGHT
Seedream layer decomposition: the base image follows the requested output_format; layers are always png
Seedream layer decomposition: 0 is the base image; layers start at 1 and stack in ascending order
Seedream layer decomposition (layers only): where the layer sits on the base image
[left, top, right, bottom] in base-image pixels
The same box, normalized to 0–999
Seedream layer decomposition (layers only): layer name
Seedream layer decomposition (layers only): what the layer contains
Image MIME type
Prompt as rewritten by the model (some models)
May be returned
Input tokens
Output tokens
Total
Grok Imagine: xAI's own metering in units of 1e-10 USD at the official price, not your charge; the USD amount actually deducted from your balance is cost_usd, and cost is the same charge in CNY
Added by the gateway: the charge for this request in CNY (the same charge as cost_usd), the same as the X-HopBase-Cost header; not returned when streaming
Added by the gateway: the USD amount actually deducted from your balance, the same as the X-HopBase-Cost-USD header and your usage record; not returned when streaming
Added by the gateway: the currency of cost, always CNY
Errors
safety_rejectedmissing_api_key / invalid_api_key / api_key_expired)insufficient_quota)model_not_found), or the path does not belong to the group (route_not_found)request_too_large)user_concurrency_limit / apikey_concurrency_limit), with Retry-AfterGPT 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 Value (AI Studio / Vertex)
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 (Enterprise)
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 typeSeedream 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 or b64_json
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
# layer_decomposition
model seedream-5-0-lite does not support layer_decomposition # only seedream-5-0-pro supports it
layer_decomposition must be a boolean
layer_decomposition requires exactly one image
layer_decomposition only accepts png or jpeg images
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition
# background
model seedream-5-0-lite does not support background # seedream-5-5 / seedream-5-0-pro only
model seedream-5-0-pro only supports background opaque or transparent
background transparent requires exactly one image with an alpha channel
background transparent outputs png; output_format jpeg is not allowed
background transparent requires an input image with an alpha channel, image/jpeg is not supported
# group generation and streaming (seedream-5-0-lite / seedream-4-5 only)
model seedream-5-0-pro does not support sequential_image_generation
sequential_image_generation only supports auto or disabled
sequential_image_generation_options must be an object
sequential_image_generation_options.max_images must be an integer between 1 and 15
the number of reference images plus max_images must not exceed 15
response_format b64_json with sequential_image_generation auto requires stream=true
model seedream-5-0-pro does not support stream
# other
watermark must be a boolean
model seedream-5-0-lite does not support tools # web search is not supported yet