Seedream
Generate and edit images with Seedream: parameters, responses, and caveats.
| Item | Value |
|---|---|
| Base URL | https://api.hop-base.com/v1 |
| Generate (incl. reference edits) | POST /v1/images/generations |
| Edit (multipart-compatible entry) | POST /v1/images/edits |
| Key group | Seedream Image Generation |
Seedream returns results synchronously (Lite and 4.5 can also stream them). n is fixed at 1, so a request returns one image unless you use group generation or layer decomposition. Image URLs are valid for 24 hours.
Available models
| Model | Model ID | Size shorthands | Official price |
|---|---|---|---|
| Seedream 5.5 | seedream-5-5 | 1K / 1.5K / 2K | $0.02from/ image |
| Seedream 5.0 Pro | seedream-5-0-pro | 1K / 1.5K / 2K | $0.0225from/ image |
| Seedream 5.0 Lite | seedream-5-0-lite | 2K / 3K / 4K | $0.035/ image |
| Seedream 4.5 | seedream-4-5 | 2K / 4K | $0.04/ image |
Choosing a model: only 5.5 and 5.0 Pro can output 1K, and on both 1.5K costs the same as 1K with better quality, so prefer 1.5K; Lite and 4.5 output at least 2K.
Request parameters
Generate
POST /v1/images/generations with a JSON body. Adding image turns it into a single-image edit, multi-image composition, or local edit.
| Parameter | Required | Type and limits | Default | Description |
|---|---|---|---|---|
model | Required | String, see the table above | — | Use the ID returned by GET /v1/models for your key |
prompt | Required | String, non-empty after trimming | — | Content, composition, style, or edit instruction; optional with layer_decomposition |
size | Optional | A model size shorthand, or WIDTHxHEIGHT | — | auto only with layer_decomposition; pixel ranges below |
n | Optional | Must be 1 | 1 | Any other value (incl. null) returns 400; for several images use sequential_image_generation |
response_format | Optional | Only url / b64_json | url | url returns a signed link; b64_json returns base64 in data[].b64_json |
output_format | Optional | Per model, see below | — | Output image format |
optimize_prompt_options | Optional | Object; mode values per model | — | Prompt optimization mode |
image | Optional | URL / Data URL, string or string array | — | References; enables image-to-image / editing |
layer_decomposition | Optional | Boolean, seedream-5-0-pro only | false | true splits one input image into a base image plus layers, see Layer decomposition |
background | Optional | opaque / transparent, seedream-5-5 / seedream-5-0-pro only | opaque | transparent needs exactly one input image with an alpha channel, see Transparent background |
watermark | Optional | Boolean | false | true adds a watermark (the official default is true) |
sequential_image_generation | Optional | auto / disabled, seedream-5-0-lite / seedream-4-5 only | disabled | auto returns a set of images, see Group generation |
sequential_image_generation_options | Optional | Object; max_images is an integer from 1 to 15 | — | Upper limit for the group; reference images plus max_images ≤ 15 |
stream | Optional | Boolean, seedream-5-0-lite / seedream-4-5 only | false | true returns SSE, see Streaming |
Per-model limits:
| Model ID | size total pixels | Max references | output_format | optimize_prompt_options.mode |
|---|---|---|---|---|
seedream-5-5 | 921,600–4,624,220 | 10 | png / jpeg | standard |
seedream-5-0-pro | 921,600–4,624,220 | 10 | png / jpeg | standard / fast |
seedream-5-0-lite | 3,686,400–16,777,216 | 14 | png / jpeg | standard |
seedream-4-5 | 3,686,400–16,777,216 | 14 | jpeg | standard |
A WIDTHxHEIGHT aspect ratio must be within 1:16–16:1. An invalid size returns 400 before generation and is not billed.
Each image item is an http(s) URL or a base64 Data URL; each Data URL must be ≤ 30 MB. Supported formats: JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF. URLs are not downloaded or size-checked at submission and must be public addresses the server can reach.
Local edits do not use a mask: draw the annotation on a reference image and describe its coordinates, bounding box, arrow, or painted region in the prompt.
Edit
POST /v1/images/edits is a compatibility entry for existing OpenAI Images editing code. Prefer multipart/form-data; the same JSON as generations also works. At least one reference image is required.
| Parameter | Required | Type and limits | Default | Description |
|---|---|---|---|---|
image / image[] | Required | File or URL string, repeatable | — | Each upload ≤ 30 MB |
model, prompt | Required | Same as Generate | — | — |
size, n, response_format, output_format | Optional | Same as Generate | — | — |
background, watermark, stream, sequential_image_generation | Optional | Same as Generate | — | Booleans are the strings true / false in multipart |
sequential_image_generation_options[max_images] | Optional | Same max_images as Generate | — | max_images also works |
optimize_prompt_options[mode] | Optional | Same mode as Generate | — | optimize_prompt_mode also works |
layer_decomposition | Optional | Same as Generate; multipart sends the string true | false | Requires exactly one image |
Any mask field returns 400, even null. Multipart fields not listed above are ignored.
Response
A sync response in the standard OpenAI Images JSON; images are in data[].url, or in data[].b64_json with response_format: b64_json. With stream: true you get SSE instead, see Streaming.
| Field | Type | Description |
|---|---|---|
created | integer | Unix seconds |
model | string | The requested model ID |
data[].url | string | Signed image link, valid for 24 hours |
data[].b64_json | string | Base64 image data, only with response_format: b64_json |
data[].error | object | Group generation only: this image failed (code, message) and is not billed |
data[].size | string | Actual output WIDTHxHEIGHT |
usage | object | May be present, with generated_images and similar |
usage.cost | number | The charge for this request in CNY (the same charge as usage.cost_usd), up to 6 decimal places. Present on every billed sync success |
usage.cost_usd | number | The USD amount actually deducted from your balance, up to 8 decimal places, the same amount as this request's usage record |
usage.currency | string | The currency of usage.cost, always CNY |
{
"model": "seedream-5-0-pro",
"created": 1760000000,
"data": [
{
"url": "https://…/result.jpeg?X-Signature=…",
"size": "2048x2048"
}
],
"usage": {
"generated_images": 1,
"output_tokens": 16384,
"total_tokens": 16384,
"cost": 1.53,
"cost_usd": 0.225,
"currency": "CNY"
}
}A successful sync response also carries this request's actual charge: usage.cost, usage.cost_usd, and usage.currency in the body, with the same values in the response headers X-HopBase-Cost, X-HopBase-Cost-USD, and X-HopBase-Currency. If the server has already sent the 200 headers to keep a long generation alive (about 40 seconds or more), the headers carry no charge; reconcile against usage.cost_usd (USD, matching your usage record) or usage.cost (CNY) in the body. Failures that are not charged carry none of them, and neither do streaming responses (check the usage record). See Charges.
The returned URL is a signed link valid for 24 hours. After it expires it cannot be retrieved again; you can only regenerate, which is billed again, so download it as soon as you receive it.
Examples
Text to image
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-pro",
"prompt": "A futuristic city street at neon night, cinematic framing",
"size": "2048x2048",
"response_format": "url"
}'Edit with references
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-pro",
"prompt": "Move the cup in the first image to the right; keep the rest",
"image": ["https://example.com/source.png"],
"size": "2K",
"output_format": "png",
"response_format": "url"
}'Group generation
seedream-5-0-lite and seedream-4-5 can return a set of related images in one request (n stays 1). Set "sequential_image_generation": "auto": the model decides from the prompt how many images to make, up to sequential_image_generation_options.max_images (an integer from 1 to 15; reference images plus max_images must not exceed 15). Describe the whole set in the prompt, such as "four illustrations of the same character across the seasons". In /v1/images/edits multipart, send sequential_image_generation_options[max_images] (or max_images).
- Only successful images are billed. An image that fails, usually on content moderation, comes back as
data[].errorwithcodeandmessageand is not billed; if every image fails, the request returns 400 with the reason. - A non-streaming group returns only after the whole set is done, and the server waits up to about 280 seconds. For larger sets, add
stream: trueto receive images one by one. A non-streaming group cannot useresponse_format: b64_json.
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"model": "seedream-5-0-lite",
"prompt": "Four illustrations of the same shiba inu in spring, summer, autumn and winter",
"sequential_image_generation": "auto",
"sequential_image_generation_options": { "max_images": 4 },
"size": "2K"
}'Streaming
seedream-5-0-lite and seedream-4-5 accept "stream": true, for a single image or a group; the response is SSE (text/event-stream). seedream-5-5 and seedream-5-0-pro return 400.
| Event | data |
|---|---|
image_generation.partial_succeeded | One image is ready: image_index, url (or b64_json), size |
image_generation.partial_failed | One image failed: image_index, error.code, error.message; not billed |
image_generation.completed | All done: usage.generated_images, usage.output_tokens, usage.total_tokens |
Every event's data also carries type, model, and created; the stream ends with data: [DONE]. Billing counts successful images. Streaming responses do not carry usage.cost or the X-HopBase-Cost headers; check the request in the console usage record.
curl -N https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "seedream-5-0-lite",
"prompt": "Four illustrations of the same shiba inu in spring, summer, autumn and winter",
"sequential_image_generation": "auto",
"sequential_image_generation_options": { "max_images": 4 },
"stream": true
}'event: image_generation.partial_succeeded
data: {"type":"image_generation.partial_succeeded","model":"seedream-5-0-lite","created":1792723998,"image_index":0,"url":"https://…","size":"2048x2048"}
event: image_generation.completed
data: {"type":"image_generation.completed","model":"seedream-5-0-lite","created":1792723998,"usage":{"generated_images":1,"output_tokens":16384,"total_tokens":16384}}
data: [DONE]Transparent background
seedream-5-5 and seedream-5-0-pro accept background: opaque / transparent, default opaque. transparent works for image-to-image only: send exactly one input image with an alpha channel, such as a PNG (JPEG and BMP Data URLs return 400). The output is a PNG with transparency, so output_format: jpeg returns 400. Other models return 400 for background.
curl https://api.hop-base.com/v1/images/edits \
-H "Authorization: Bearer sk-your-key" \
-F "model=seedream-5-0-pro" \
-F "prompt=Keep the product and make the background transparent" \
-F "image=@product.png" \
-F "background=transparent" \
-F "output_format=png"Layer decomposition
seedream-5-0-pro can split one image into a base image plus up to 16 transparent layers (subjects, text, background, decorations), so you can edit or move each layer and put the picture back together. Send "layer_decomposition": true as a JSON boolean to POST /v1/images/generations, or the field layer_decomposition=true to POST /v1/images/edits (multipart or JSON).
With it turned on, these rules change:
| Parameter | With layer_decomposition: true |
|---|---|
model | seedream-5-0-pro only; other models return 400 |
image | Exactly one image. A Data URL must be PNG or JPEG |
prompt | Optional. Omit it and the model finds subjects, text, background, and decorations on its own; or say what to split out, or target a region with <bbox>x1 y1 x2 y2</bbox> (coordinates normalized to 0–999) |
size | Only 1K / 1.5K / 2K / auto, default auto; WIDTHxHEIGHT is rejected |
output_format | Applies to the base image only; layers are always PNG with transparency |
With auto, an input between about 1280x720 and 2048x2048 keeps its size; a smaller input comes out at 1K and a larger one at 2K. Official limits for the input image: total pixels from 512x512 to 6000x6000, aspect ratio from 1:16 to 16:1, and up to 30 MB.
Layer decomposition is synchronous and slow: about 1.5 minutes at 1K. Set your client timeout to at least 5 minutes, and do not resend while the first request is still running; it may still finish and be billed.
curl https://api.hop-base.com/v1/images/generations \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
--max-time 300 \
-d '{
"model": "seedream-5-0-pro",
"image": "https://example.com/poster.png",
"layer_decomposition": true,
"size": "1K"
}'data[] holds the base image first, then the layers:
{
"model": "seedream-5-0-pro",
"created": 1792722728,
"data": [
{
"url": "https://…/base.jpeg?X-Signature=…",
"size": "880x1088",
"output_format": "jpeg",
"z_index": 0
},
{
"url": "https://…/layer-1.png?X-Signature=…",
"size": "959x354",
"output_format": "png",
"z_index": 1,
"bounding_box": {
"absolute": [156, 751, 784, 983],
"normalized": [177, 690, 890, 903]
},
"name": "Wooden stump stage",
"description": "A wooden stump stage at the bottom of the scene"
}
],
"usage": {
"generated_images": 2
}
}| Field | Description |
|---|---|
data[].z_index | 0 is the base image; layers count up from 1, higher numbers on top |
data[].url | Signed link, valid for 24 hours |
data[].size | Actual pixel size of this image. A layer image is usually not the same size as its box on the base image |
data[].output_format | The base image follows your output_format; layers are png |
data[].bounding_box.absolute | Layers only: [left, top, right, bottom] in base-image pixels |
data[].bounding_box.normalized | Layers only: the same box, normalized to 0–999 |
data[].name, data[].description | Layers only: what the layer contains |
usage.generated_images | Base image plus layers, the number of images billed |
To recompose, use the base image as the canvas and place layers in ascending z_index: scale each layer to its box, (right - left) x (bottom - top), and paste it at (left, top) with its alpha channel. For example, with Pillow:
import io
import urllib.request
from PIL import Image
def fetch(url):
return Image.open(io.BytesIO(urllib.request.urlopen(url).read())).convert("RGBA")
items = sorted(resp["data"], key=lambda d: d["z_index"]) # resp is the parsed response JSON
canvas = fetch(items[0]["url"])
for item in items[1:]:
left, top, right, bottom = item["bounding_box"]["absolute"]
layer = fetch(item["url"]).resize((right - left, bottom - top))
canvas.alpha_composite(layer, (left, top))
canvas.save("recomposed.png")Notes
nmust be 1: a request returns one image, except group generation (sequential_image_generation: auto, Lite and 4.5) and layer decomposition (5.0 Pro).- Sync only:
Prefer: respond-asyncis ignored and the request still returns synchronously. - Results come as
urlby default; setresponse_format: b64_jsonfor base64 (a non-streaming group needsstream: truefor that). sizedoes not acceptauto(except with layer decomposition), and Lite and 4.5 output at least 2K.seedream-4-5outputs JPEG only.seedream-5-5accepts onlystandardforoptimize_prompt_options.mode(fastreturns 400) and does not support layer decomposition, group generation, or streaming.- Traditional masks are not supported; for local edits, use an annotated reference plus a prompt description.
- Plural
images,quality, and similar fields have no effect and are ignored. tools(web search) is not supported yet; passing it returns 400.seedream-5-0-liteis the lightweight Seedream 5.0 model, publicly named Seedream 5.0 Lite; do not treat it as Pro.- Data URLs must be base64-encoded, and the MIME type must match the image.
- Official specification: each input image can be up to 30 MB / 36 MP.
Common errors
Invalid parameters return 400 before generation and are not billed. Content-safety rejections also return 400 without charge, with the reason in error.message.
| Error | Fix |
|---|---|
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size | Use a size shorthand of that model or a valid WIDTHxHEIGHT |
model seedream-5-5 only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size | Use 1K, 1.5K, 2K or a valid WIDTHxHEIGHT; 4K is not accepted |
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216 | Bring the total pixels into the range |
size aspect ratio must be between 1:16 and 16:1 | Adjust the aspect ratio |
only a single output is supported (n=1) | Drop n; for several images use sequential_image_generation |
response_format only supports url or b64_json | Use url or b64_json |
model seedream-4-5 only supports output_format jpeg | Pass jpeg or omit it |
model seedream-5-5 only supports optimize_prompt_options.mode standard | Pass standard or omit it; fast needs seedream-5-0-pro |
at most 10 reference images are supported | Send fewer references |
seedream does not accept a traditional mask; ... | Drop mask and use an annotated reference |
model seedream-5-0-lite does not support layer_decomposition | Layer decomposition needs seedream-5-0-pro |
layer_decomposition requires exactly one image | Send exactly one image |
layer_decomposition only accepts png or jpeg images | Convert the input image to PNG or JPEG |
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition | Use a size tier, or omit size |
layer_decomposition must be a boolean | Pass true or false |
model seedream-5-0-lite does not support background | background needs seedream-5-5 or seedream-5-0-pro |
background transparent requires exactly one image with an alpha channel | Send exactly one image with transparency, such as a PNG |
background transparent outputs png; output_format jpeg is not allowed | Drop output_format or use png |
model seedream-5-0-pro does not support sequential_image_generation | Group generation needs seedream-5-0-lite or seedream-4-5 |
the number of reference images plus max_images must not exceed 15 | Lower max_images or send fewer references |
response_format b64_json with sequential_image_generation auto requires stream=true | Add stream: true, or use url |
model seedream-5-0-pro does not support stream | Streaming needs seedream-5-0-lite or seedream-4-5 |
model seedream-5-0-lite does not support tools | Remove tools |
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-5 only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size # e.g. "size": "4K"
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
model seedream-5-0-lite only supports optimize_prompt_options.mode standard
model seedream-5-5 only supports optimize_prompt_options.mode standard # fast: seedream-5-0-pro only
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
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 # no image, or two or more
layer_decomposition only accepts png or jpeg images # a Data URL in another format
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decomposition
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
model seedream-5-0-pro does not support sequential_image_generation # group and streaming: seedream-5-0-lite / seedream-4-5 only
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
watermark must be a boolean
model seedream-5-0-lite does not support tools # web search is not supported yetBilling
Billed per successfully generated image (in a group, failed images are not billed), and 5.5 and 5.0 Pro also charge for each reference image; failed generations and safety rejections are not billed. 5.5 and 5.0 Pro are priced by output pixel tier, and 1K and 1.5K cost the same. The actual charge for each request is usage.cost_usd (USD) and usage.cost (CNY) in the response. With layer decomposition, every output image, the base image and each layer, is billed by its own pixel tier at the layer-decomposition rate, which is half the regular 5.0 Pro price per image; the input image is charged as a reference image as usual. usage.generated_images is the number of output images billed. Streaming responses carry no charge fields; check the usage record.
See each model card and the signed-in model catalog for unit prices.
Next steps
- Image generation overview
- GPT Image, Gemini images, Grok images, Kling images
- API reference: Create image, Edit image
- When something fails, check Troubleshooting