calesthio/generative-media-skills/bytedance-seedream

ByteDance Seedream

Use this skill when an application calls Seedream directly through the first-party Ark image-generation API. It covers text-to-image, reference-guided generation, natural-language editing, multi-image fusion, grouped outputs, and streamed grouped outputs. It does not cover Seedance video generation, third-party gateways, consumer apps, model training, or UI automation.

All volatile facts below were checked against first-party documentation on 2026-07-09. Recheck the linked model catalog, availability, pricing, and retirement pages before a production launch.

Evidence labels

• Documented means a current ByteDance Seed, Volcengine, or BytePlus page states the behavior.
• Provider claim means a first-party product or research page makes a qualitative performance claim; treat it as marketing until tested on the application's corpus.
• Operational recommendation means a production practice inferred from the documented contract, not a provider guarantee.
• Unknown means the first-party pages reviewed do not establish the behavior. Feature-detect or ask support instead of inventing a contract.

Choose the commercial surface first

Model IDs and hosts are not interchangeable.

All three use:

POST {API_BASE}/images/generations
Authorization: Bearer {ARK_API_KEY}
Content-Type: application/json

Do not send a China token to a BytePlus host or a BytePlus token to the China host. Use an exact host allowlist, never log the key, and inject it at runtime from a secret manager.

Documented region caveat: BytePlus says an AP request normally prefers AP but may be served from EU, and an EU request may be served from AP when needed. Endpoint selection is therefore not a data-residency guarantee. Obtain a contractual answer if residency is a requirement.

Select a model by contract, not name alone

The 5.0 Pro row applies to the China model documented above; BytePlus's current global image API does not document a global 5.0 Pro ID. Do not synthesize one.

First-party 4.0 conflict: the current generic image API describes 2–14 reference inputs, while the Seedream 4.0 model-specific card describes 2–10 for multi-image-to-single and multi-image-to-set workflows. Default 4.0 production validation to 10. Use 11–14 only after an authorized live canary confirms the exact endpoint contract; record the response and retrieval date.

Use 5.0 Lite when grouped output, SSE, or optional real-time web search is required. Use China 5.0 Pro when its documented higher-end single-image contract is required and grouped/streamed output is not. Keep 4.5 or 4.0 only for a measured compatibility, quality, or cost reason and maintain a migration test.

Seedream 5.0 Lite's first-party release page describes multimodal reasoning, world knowledge, and optional real-time search. These are provider claims; evaluate factuality and visual quality with representative prompts.

Request contract

Core fields

• model is required and may be a documented model ID or a configured endpoint ID.
• prompt is required. The guide recommends no more than about 300 Chinese characters or 600 English words; this is a recommendation, not a documented hard server limit.
• image is optional and accepts one URL/data URL or an array. A data URL must be data:image/<lowercase-format>;base64,<payload>.
• Input formats: JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, or HEIF. Each dimension must be greater than 14 px, aspect ratio must be within [1/16, 16], file size at most 30 MB, and total image area at most 36 MP.
• size accepts a model-supported resolution label or explicit WIDTHxHEIGHT string. Validate against the selected model before sending.
• response_format is url or b64_json; default is url. Returned URLs expire after 24 hours.
• watermark defaults to true and adds a visible Chinese “AI generated” mark. false removes that visible mark; it does not waive disclosure, provenance, or legal obligations.
• output_format is png or jpeg only on current 5.0 models; it defaults to JPEG. Do not send it to 4.5/4.0 expecting conversion.

The current canonical 4.0–5.0 API pages do not document seed or guidance_scale for these models. BytePlus documents those controls only for legacy 3.0 models and explicitly marks guidance unsupported on the current family. Do not send them unless the exact endpoint contract you control explicitly documents them. Similar output is not deterministic output.

Size constraints

Prefer a documented label plus an aspect/use description in the prompt, or choose a documented recommended size. Common documented examples include 5.0 Lite 2K square 2048x2048, landscape 2848x1600, portrait 1600x2848; 5.0 Lite 4K square 4096x4096; and Pro 1K square 1024x1024 or 2K square 2048x2048. Do not assume the same label maps to the same pixel dimensions on every model.

Natural-language edits and references

There is no separate mask/inpaint route in the current unified API. Supply one or more image references and describe the edit in prompt:

1. Identify references by ordinal: “In image 1… use the lighting from image 2.”
2. State the target operation: add, remove, replace, recolor, relight, restyle, or compose.
3. State invariants explicitly: “Keep pose, face proportions, camera, background, and all text unchanged.”
4. For a hard-to-identify local region, annotate the source image with an arrow, box, or doodle and refer to that mark. This technique is documented in the prompt guide.
5. For fusion, assign a single role to each reference rather than asking the model to infer roles.

Reference URLs must be fetchable by the service. Prefer short-lived, least-privilege presigned URLs. Data URLs avoid public hosting but still transmit the image to the provider and can make request bodies large.

Grouped output

On 5.0 Lite, 4.5, or 4.0:

{
  "sequential_image_generation": "auto",
  "sequential_image_generation_options": {"max_images": 4}
}

max_images is 1–15 and defaults to 15. The input-reference count plus generated-image count must not exceed 15. auto lets the model decide whether and how many images to create; it does not promise the requested maximum. Name the exact set in the prompt—such as “Create exactly four storyboard frames; frame 1…, frame 2…”—then validate the actual count. Do not send these fields to China 5.0 Pro.

Optional web search

Only 5.0 Lite currently documents:

{"tools": [{"type": "web_search"}]}

The model decides whether to use it; usage.tool_usage.web_search reports use. Search adds latency and external-content risk. Treat searched facts and visual details as untrusted, review attribution and rights, and do not promise that search will occur.

Interpret responses defensively

For non-streaming requests, expect top-level model, created, data, usage, and possibly error. Each data member may be either a successful image (url or b64_json, size, and where supported output_format) or an item-level error. A 200 response can therefore still contain partial failure.

Validate:

1. Top-level status and error.
2. Every data item independently.
3. The actual successful count versus the requested deliverable.
4. Declared size/format versus decoded bytes.
5. usage.generated_images, output tokens, and tool usage for cost and observability.

The documentation says only successful generated images are billed. Do not infer zero cost from a client timeout: without a documented idempotency key, a timed-out request may have completed server-side.

When stream: true, parse server-sent events until the final completion event:

• image_generation.partial_succeeded: contains image_index (zero-based) plus url or b64_json and size.
• image_generation.partial_failed: contains image_index and an error.
• image_generation.completed: final usage/tools summary.
• top-level error: request failure.

The stream guide says a content-filter failure can be followed by later images, while an internal 500 stops subsequent generation. Do not treat the first partial event as completion.

Production workflow

1. Establish a policy envelope

Before calling the API, record:

• deployment surface, account, endpoint region, exact model/endpoint ID, and launch date;
• allowed input classifications and whether personal data, faces, trademarks, or confidential material are permitted;
• maximum references, output count, dimensions, bytes, latency, retries, and spend per job;
• visible watermark/disclosure policy and a durable provenance policy;
• reviewer and approval criteria for public, commercial, or high-impact use.

2. Normalize and validate input

• Decode local inputs and inspect their real type; do not trust filenames or client MIME alone.
• Reject malformed, oversized, decompression-bomb, extreme-ratio, and unsupported inputs before upload.
• Strip unnecessary EXIF/location metadata unless it is intentionally preserved.
• Hash each source, store its license/consent record, and assign a stable reference number.
• Keep reference order stable from prompt through audit record.

3. Build a testable prompt

Use natural sentences rather than a keyword pile:

[deliverable/use]. [subject and action]. [environment].
[camera/composition]. [lighting/color/style].
[exact text in double quotes]. [reference roles]. [edit invariants].
[numbered outputs if a set].

For typography, put required copy in double quotes, specify placement and hierarchy, then run OCR and human proofing. Generation is not a typesetting guarantee.

4. Submit with a job ledger

Create a client job ID and persist the request hash, redacted parameters, model, host, start time, attempt number, and state. The image API is synchronous or request-scoped SSE; the current docs do not document an async image job, polling API, webhook, or idempotency key. Do not import Seedance video task semantics.