Sociaro

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.

Slugbytedance/seedream-5-5
Kindimage
Vendorbytedance
EndpointPOST /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

FieldTypeRequiredDefaultValuesWhat it does
promptstringyes*—textWhat to generate. Optional in layer-decomposition mode, where the model finds the elements itself; required otherwise.
imagestring or string[]no—public https urls, or inline data:image/;base64,…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.
sizestringno2K (auto when decomposing)1K · 1.5K · 2K, or WxH in pixelsTwo 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_decompositionbooleannofalsetrue · falseTakes 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_optionsobjectno—max_images: 2-100 · text_recognition: true · falseOnly 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.
backgroundstringnoautoauto · 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_formatstringnopngpng · jpegIn decomposition mode this governs the base image only — layers are always png.
optimize_prompt_optionsobjectno—mode: standard`{"mode": "standard"}` — the only mode this model offers.
response_formatstringnourlurlThe async route is url-only; `b64_json` is refused, because buffering full images would sink the relay.
watermarkbooleannothe vendor's (on)true · falseBytePlus defaults this ON, and this route forwards your body as sent — send `false` for an image without the mark.
safety_identifierstringno—1–64 charactersA 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.