Skip to content

Seedream

Generate and edit images with Seedream: parameters, responses, and caveats.

ItemValue
Base URLhttps://api.hop-base.com/v1
Generate (incl. reference edits)POST /v1/images/generations
Edit (multipart-compatible entry)POST /v1/images/edits
Key groupSeedream 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

ModelModel IDSize shorthandsOfficial price
Seedream 5.5seedream-5-51K / 1.5K / 2K$0.02from/ image
Seedream 5.0 Proseedream-5-0-pro1K / 1.5K / 2K$0.0225from/ image
Seedream 5.0 Liteseedream-5-0-lite2K / 3K / 4K$0.035/ image
Seedream 4.5seedream-4-52K / 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.

ParameterRequiredType and limitsDefaultDescription
modelRequiredString, see the table above—Use the ID returned by GET /v1/models for your key
promptRequiredString, non-empty after trimming—Content, composition, style, or edit instruction; optional with layer_decomposition
sizeOptionalA model size shorthand, or WIDTHxHEIGHT—auto only with layer_decomposition; pixel ranges below
nOptionalMust be 11Any other value (incl. null) returns 400; for several images use sequential_image_generation
response_formatOptionalOnly url / b64_jsonurlurl returns a signed link; b64_json returns base64 in data[].b64_json
output_formatOptionalPer model, see below—Output image format
optimize_prompt_optionsOptionalObject; mode values per model—Prompt optimization mode
imageOptionalURL / Data URL, string or string array—References; enables image-to-image / editing
layer_decompositionOptionalBoolean, seedream-5-0-pro onlyfalsetrue splits one input image into a base image plus layers, see Layer decomposition
backgroundOptionalopaque / transparent, seedream-5-5 / seedream-5-0-pro onlyopaquetransparent needs exactly one input image with an alpha channel, see Transparent background
watermarkOptionalBooleanfalsetrue adds a watermark (the official default is true)
sequential_image_generationOptionalauto / disabled, seedream-5-0-lite / seedream-4-5 onlydisabledauto returns a set of images, see Group generation
sequential_image_generation_optionsOptionalObject; max_images is an integer from 1 to 15—Upper limit for the group; reference images plus max_images ≤ 15
streamOptionalBoolean, seedream-5-0-lite / seedream-4-5 onlyfalsetrue returns SSE, see Streaming

Per-model limits:

Model IDsize total pixelsMax referencesoutput_formatoptimize_prompt_options.mode
seedream-5-5921,600–4,624,22010png / jpegstandard
seedream-5-0-pro921,600–4,624,22010png / jpegstandard / fast
seedream-5-0-lite3,686,400–16,777,21614png / jpegstandard
seedream-4-53,686,400–16,777,21614jpegstandard

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.

ParameterRequiredType and limitsDefaultDescription
image / image[]RequiredFile or URL string, repeatable—Each upload ≤ 30 MB
model, promptRequiredSame as Generate——
size, n, response_format, output_formatOptionalSame as Generate——
background, watermark, stream, sequential_image_generationOptionalSame as Generate—Booleans are the strings true / false in multipart
sequential_image_generation_options[max_images]OptionalSame max_images as Generate—max_images also works
optimize_prompt_options[mode]OptionalSame mode as Generate—optimize_prompt_mode also works
layer_decompositionOptionalSame as Generate; multipart sends the string truefalseRequires 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.

FieldTypeDescription
createdintegerUnix seconds
modelstringThe requested model ID
data[].urlstringSigned image link, valid for 24 hours
data[].b64_jsonstringBase64 image data, only with response_format: b64_json
data[].errorobjectGroup generation only: this image failed (code, message) and is not billed
data[].sizestringActual output WIDTHxHEIGHT
usageobjectMay be present, with generated_images and similar
usage.costnumberThe charge for this request in CNY (the same charge as usage.cost_usd), up to 6 decimal places. Present on every billed sync success
usage.cost_usdnumberThe USD amount actually deducted from your balance, up to 8 decimal places, the same amount as this request's usage record
usage.currencystringThe currency of usage.cost, always CNY
{
  "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.

Download results right away.

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[].error with code and message and 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: true to receive images one by one. A non-streaming group cannot use response_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.

Eventdata
image_generation.partial_succeededOne image is ready: image_index, url (or b64_json), size
image_generation.partial_failedOne image failed: image_index, error.code, error.message; not billed
image_generation.completedAll 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:

ParameterWith layer_decomposition: true
modelseedream-5-0-pro only; other models return 400
imageExactly one image. A Data URL must be PNG or JPEG
promptOptional. 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)
sizeOnly 1K / 1.5K / 2K / auto, default auto; WIDTHxHEIGHT is rejected
output_formatApplies 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.

Set a long client timeout.

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
  }
}
FieldDescription
data[].z_index0 is the base image; layers count up from 1, higher numbers on top
data[].urlSigned link, valid for 24 hours
data[].sizeActual pixel size of this image. A layer image is usually not the same size as its box on the base image
data[].output_formatThe base image follows your output_format; layers are png
data[].bounding_box.absoluteLayers only: [left, top, right, bottom] in base-image pixels
data[].bounding_box.normalizedLayers only: the same box, normalized to 0–999
data[].name, data[].descriptionLayers only: what the layer contains
usage.generated_imagesBase 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

  • n must 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-async is ignored and the request still returns synchronously.
  • Results come as url by default; set response_format: b64_json for base64 (a non-streaming group needs stream: true for that).
  • size does not accept auto (except with layer decomposition), and Lite and 4.5 output at least 2K.
  • seedream-4-5 outputs JPEG only.
  • seedream-5-5 accepts only standard for optimize_prompt_options.mode (fast returns 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.

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.

ErrorFix
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel sizeUse 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 sizeUse 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 16777216Bring the total pixels into the range
size aspect ratio must be between 1:16 and 16:1Adjust 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_jsonUse url or b64_json
model seedream-4-5 only supports output_format jpegPass jpeg or omit it
model seedream-5-5 only supports optimize_prompt_options.mode standardPass standard or omit it; fast needs seedream-5-0-pro
at most 10 reference images are supportedSend 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_decompositionLayer decomposition needs seedream-5-0-pro
layer_decomposition requires exactly one imageSend exactly one image
layer_decomposition only accepts png or jpeg imagesConvert the input image to PNG or JPEG
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or auto with layer_decompositionUse a size tier, or omit size
layer_decomposition must be a booleanPass true or false
model seedream-5-0-lite does not support backgroundbackground needs seedream-5-5 or seedream-5-0-pro
background transparent requires exactly one image with an alpha channelSend exactly one image with transparency, such as a PNG
background transparent outputs png; output_format jpeg is not allowedDrop output_format or use png
model seedream-5-0-pro does not support sequential_image_generationGroup generation needs seedream-5-0-lite or seedream-4-5
the number of reference images plus max_images must not exceed 15Lower max_images or send fewer references
response_format b64_json with sequential_image_generation auto requires stream=trueAdd stream: true, or use url
model seedream-5-0-pro does not support streamStreaming needs seedream-5-0-lite or seedream-4-5
model seedream-5-0-lite does not support toolsRemove tools

Billing

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