bytedance/seedream-5-5
Seedream 5.5 — BytePlus's newest image model.
Text-to-image and image-to-image with up to ten reference images, transparent output from a prompt alone, and layer decomposition that takes a finished picture apart into up to 100 images and can read back the text in each text layer.
Sizes are a parameter, not separate model ids.
Served asynchronously — submit, then poll.
| Slug | bytedance/seedream-5-5 |
| Kind | image |
| Vendor | bytedance |
| Endpoint | POST /v1/byteplus/images/async |
Charged per job from what the generator reports it rendered — your Logs show the exact figure for each one; see balance and billing.
Calling it
curl https://api.sociaro.com/v1/byteplus/images/async \
-H "Authorization: Bearer $SOCIARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bytedance/seedream-5-5",
"prompt": "a paper boat on a rain-soaked street"
}'Parameters
Seedream 5.5 — text-to-image, image-to-image, layer decomposition with text recognition
| Field | Type | Required | Default | Values | What it does |
|---|---|---|---|---|---|
prompt | string | yes* | — | text | What to generate. Optional in layer-decomposition mode, where the model finds the elements itself; required otherwise. |
image | string or string[] | no | — | public https urls, or inline data:image/ | Present -> image-to-image, up to 10 reference images. Inline images are taken on `POST /v1/byteplus/images/async` only, within its 256 KiB body cap, so a url is the safer choice. Exactly ONE png or jpeg in layer-decomposition mode; more is an error. |
size | string | no | 2K (auto when decomposing) | 1K · 1.5K · 2K, or WxH in pixels | Two ways. Recommended: send a preset and say the shape in the prompt ("16:9"); the model picks the exact size (a `1K` request has come back as 1248×832 and 1376×768). Or send exact pixels `WxH`: area 921,600 to 4,624,220 px, aspect within 1:16..16:1. In decomposition mode only the presets and `auto` are accepted. |
layer_decomposition | boolean | no | false | true · false | Takes one image apart into a base image plus layers, up to 100 images in all. The poll then returns every one of them in `data[]`. Every image is charged at its own size — a 30-image result is 30 charges, not one. |
layer_decomposition_options | object | no | — | max_images: 2-100 · text_recognition: true · false | Only with `layer_decomposition: true`. `max_images` caps the result, base image included (default 30). `text_recognition` (default false) returns, for each regular-text layer, its text, its lines with their boxes, and the style of each run. |
background | string | no | auto | auto · transparent · opaque | `transparent` returns a live alpha channel, from a prompt alone or from reference images. Not with layer decomposition (an error), and the output must be png: `output_format: jpeg` beside it is an error. |
output_format | string | no | png | png · jpeg | In decomposition mode this governs the base image only — layers are always png. |
optimize_prompt_options | object | no | — | mode: standard | `{"mode": "standard"}` — the only mode this model offers. |
response_format | string | no | url | url | The async route is url-only; `b64_json` is refused, because buffering full images would sink the relay. |
watermark | boolean | no | the vendor's (on) | true · false | BytePlus defaults this ON, and this route forwards your body as sent — send `false` for an image without the mark. |
safety_identifier | string | no | — | 1–64 characters | A fixed id for YOUR end user, one per user, which the generator uses to spot an end user who breaks its usage policy. We never send your value itself: we send a per-organisation pseudonym of your value (64 hex characters, the same for the same value on all your organisation's keys and routes), and the response reports that pseudonym back. A blank or longer value, or one that is not a string, is refused before anything is sent (`400`), on every route. |
Worked example
curl https://api.sociaro.com/v1/byteplus/images/async \
-H "Authorization: Bearer $SOCIARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bytedance/seedream-5-5",
"prompt": "a red paper boat on wet asphalt at night, neon reflections",
"size": "2816x1584"
}'
# take a finished picture apart — up to 8 images, with the text in each text layer
curl https://api.sociaro.com/v1/byteplus/images/async \
-H "Authorization: Bearer $SOCIARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bytedance/seedream-5-5",
"image": "https://your-cdn.example.com/poster.png",
"layer_decomposition": true,
"layer_decomposition_options": {"max_images": 8, "text_recognition": true}
}'Taking a picture apart
With layer_decomposition: true the poll of POST /v1/byteplus/images/async returns the vendor's
own data[] with one entry per image — the base (z_index 0) and every layer — and media_url
beside it, our link to the first entry. Up to 100 images in all; layer_decomposition_options.max_images caps that number, base
included, and defaults to 30.
With text_recognition: true, each layer holding regular text (not artistic or handwritten text,
and never the base) also carries what it says:
{ "url": "<the vendor's own link>", "z_index": 3, "name": "headline",
"bounding_box": { "absolute": [120, 80, 940, 210], "normalized": [117, 78, 918, 205] },
"text_recognition": {
"text": "SUMMER SALE\nup to 50% off",
"lines": [
{ "bounding_box": { "absolute": [120, 80, 940, 150], "normalized": [117, 78, 918, 146] },
"runs": [ { "text": "SUMMER SALE",
"style": { "similar_font_family": "unknown", "foreground_color": "#FFFFFF",
"bold": true, "italic": false, "underline": false,
"strikethrough": false, "shadow": false, "translucent": false } } ] }
] } }
To rebuild the picture: place each layer at (left, top), scale it to right-left x
bottom-top, and stack in ascending z_index. Each entry's url is the vendor's own link;
copy the images into your own storage promptly.
Two limits: exactly one png or jpeg input image, and no partial success — if a single layer fails, the whole request fails and nothing is charged.
Price
Charged per OUTPUT image, at that image's own size: $0.022 up to 2.6 MP (the 1K and 1.5K
presets), $0.0385 above (the 2K presets). Each input image adds $0.0088, from the first one.
Decomposition is charged at the same rates — the base and every layer, each at its own size, and
a small layer (under 1K) at $0.022. A decomposition with the default max_images can return 30
images, so set it to what you need.
Getting a transparent result
background: "transparent" returns a live alpha channel, from a prompt alone or with reference
images; the inputs need no alpha of their own:
{ "model": "bytedance/seedream-5-5", "prompt": "a glass perfume bottle, studio light",
"background": "transparent" }
The output is png: asking for output_format: "jpeg" beside it is an error, and so is
background together with layer_decomposition.
Shapes other than a square
This model has no aspect-ratio field, and there are two ways to ask for a shape. The recommended
one: send a preset (1K, 1.5K or 2K) and say the shape in the prompt; the model picks the
exact size, so the pixels you get can differ between requests (1K has come back as 1248×832 and
as 1376×768). The other is exact pixels: 2816x1584 gives 16:9, 1584x2816 gives 9:16. Both the
area (921,600 to 4,624,220 px) and the ratio (within 1:16 to 16:1) must hold, and the generator
names whichever one you missed. Layer decomposition takes the presets and auto only.
How a job runs
These routes are a pass-through: you send BytePlus's own body and get their own response back, with our additions beside it. Generation takes longer than a request should wait, so it goes in three moves — submit, poll, collect.
# 1. submit — the id comes back as `id`. There is NO `job_id` on THIS response
curl -sS https://api.sociaro.com/v1/byteplus/contents/generations/tasks \
-H "Authorization: Bearer $SOCIARO_API_KEY" -H "Content-Type: application/json" \
-d '{ "model": "…", "content": [ … ] }'
# -> { "id": "cgt-…" }
# 2. poll every 5-10 s
curl -sS https://api.sociaro.com/v1/byteplus/contents/generations/tasks/cgt-… \
-H "Authorization: Bearer $SOCIARO_API_KEY"
# -> { "status": "running", … }
# -> { "status": "succeeded", "content": { "video_url": "<the vendor's own link>" },
# "media_url": "https://api.sociaro.com/v1/media/<media_id>" }
# 3. collect — the opaque id IS the credential, no header needed
curl -sSL "https://api.sociaro.com/v1/media/<media_id>" -o out.mp4
Images use POST /v1/byteplus/images/async and its poll in the same shape, and the faster models
also answer synchronously at POST /v1/byteplus/images/generations — one request, the picture in
the response. A model whose render outlasts the gateway's ~2-minute ceiling is refused there by
name, telling you to use the async route.
Reading the poll
Two differences will bite a client written against the poll-style routes. The SUBMIT returns
id, not job_id — code reading job_id there gets nothing and cannot poll at all. And status
is the VENDOR'S vocabulary: running, succeeded, failed — not processing, completed,
failed. A check for completed on this route never becomes true, which reads as a job that never
finishes rather than as an error.
The POLL response does carry job_id beside the vendor's id, as a convenience, and it returns
the vendor's whole body — around twenty fields — rather than the five-field shape the other routes
use. Gate on status rather than on the poll's HTTP code.
Prefer media_url over the vendor's raw link. Both are returned: content.video_url (or
data[].url for images) is theirs, kept for compatibility and due to be removed once nobody reads
it; media_url is ours. Ours points at our host, hides the vendor's storage, and expires. A second
asset arrives on the same terms — return_last_frame gives content.last_frame_url with
last_frame_media_url beside it.
Collecting the result
media_url is a capability: the opaque id is the credential, so no Authorization header is
needed and anyone holding the link can fetch it. It expires within the hour — download rather
than store the link.
Rules the gateway adds
Your key must be granted this model — 403 otherwise — and either spelling satisfies the grant:
our catalogue id or the vendor's own native one.
Because this is a pass-through, unknown fields go to the generator rather than being refused here,
and it is the generator that decides. The exception is resolution, which we check ourselves: an
unsupported tier is silently ignored upstream, so you would ask for the higher one, be handed a
lower one, and be charged. A tier we cannot price is refused at submit, before any money is spent,
with a message naming the ones this model has.
Ranges and enums are the generator's own, so an out-of-range value comes back as its rejection, in its wording and with its numbers.