Edit image
Image-to-image / image editing: GPT Image (supports mask), Seedream, and Gemini in the "Gemini Value (AI Studio / Vertex)" group.
/v1/images/editsGenerates from reference images or edits locally. multipart/form-data is recommended (local files; reference image field image / image[], repeatable); JSON is also accepted (reference images as HTTP(S) URLs or Data URLs). Field names are the same in both. The example on the right uses JSON; for multipart see the Image generation guide.
JSON edits and async tasks do not keep output_compression, moderation, user or response_format. The "Gemini Official Direct (Enterprise)" group has no such endpoint; pass reference images to Create image instead.
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
Multipart files (image / image[]), or in JSON an HTTP(S) URL / Data URL string or array of strings. images is not read; raw base64 and file_id are not accepted; images may be compressed before forwarding
Limits1–16 images (official cap); remote URLs ≤ 26214400 bytes each and must return image/*. Only image is read, not images
Transparent areas mark what to edit; the gateway scales the mask to the size of the first reference image. Pixels outside the mask are not guaranteed to stay identical
LimitsPNG with an alpha channel; transparent areas mark what to edit
- 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
Multipart files (image / image[]), or in JSON an HTTP(S) URL / Data URL string or array of strings. images is not read; raw base64 and file_id are not accepted; images may be compressed before forwarding
Limits1–16 images (official cap); remote URLs ≤ 26214400 bytes each and must return image/*. Only image is read, not images
Transparent areas mark what to edit; the gateway scales the mask to the size of the first reference image. Pixels outside the mask are not guaranteed to stay identical
LimitsPNG with an alpha channel; transparent areas mark what to edit
- 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
Multipart files (image / image[]), or in JSON an HTTP(S) URL / Data URL string or array of strings. images is not read; raw base64 and file_id are not accepted; images may be compressed before forwarding
Limits1–16 images (official cap); remote URLs ≤ 26214400 bytes each and must return image/*. Only image is read, not images
Transparent areas mark what to edit; the gateway scales the mask to the size of the first reference image. Pixels outside the mask are not guaranteed to stay identical
LimitsPNG with an alpha channel; transparent areas mark what to edit
- 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
Multipart files (image / image[]), or in JSON an HTTP(S) URL / Data URL string or array of strings. images is not read; raw base64 and file_id are not accepted; images may be compressed before forwarding
Limits1–16 images (official cap); remote URLs ≤ 26214400 bytes each and must return image/*. Only image is read, not images
Transparent areas mark what to edit; the gateway scales the mask to the size of the first reference image. Pixels outside the mask are not guaranteed to stay identical
LimitsPNG with an alpha channel; transparent areas mark what to edit
GPT Image 2.6 only: a transparent PNG overlay with drawn circles, arrows, or notes, the same size as the first input image; the model edits as annotated. Cannot be combined with mask
- transparent requires png or webp
- output_compression applies only to jpeg / webp
- n must be 1 when output_format=svg
- markup cannot be combined with mask
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
Multipart files (image / image[]), or in JSON an HTTP(S) URL / Data URL string or array of strings. images is not read; raw base64 and file_id are not accepted; images may be compressed before forwarding
Limits1–16 images (official cap); remote URLs ≤ 26214400 bytes each and must return image/*. Only image is read, not images
Transparent areas mark what to edit; the gateway scales the mask to the size of the first reference image. Pixels outside the mask are not guaranteed to stay identical
LimitsPNG with an alpha channel; transparent areas mark what to edit
GPT Image 2.6 only: a transparent PNG overlay with drawn circles, arrows, or notes, the same size as the first input image; the model edits as annotated. Cannot be combined with mask
- transparent requires png or webp
- output_compression applies only to jpeg / webp
- n must be 1 when output_format=svg
- markup cannot be combined with mask
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
Not supported: /v1/images/edits with mask returns 400 (null too)
- 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
Not supported: /v1/images/edits with mask returns 400 (null too)
- 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
Not supported: /v1/images/edits with mask returns 400 (null too)
- 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
Not supported: /v1/images/edits with mask returns 400 (null too)
- A non-streaming group cannot use b64_json (stream=true required)
Returns
200Synchronous success
202With Prefer: respond-async
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
missing_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-After