bytedance-seedream — Claude Code skill: what it does, install
bytedance-seedream is a Claude Code skill for image generation and editing through Ark. It handles reference images, grouped results, and streamed output.
MIT 136 installs ★ 252 updated 2026-07-14
npx skills add calesthio/generative-media-skills --skill bytedance-seedream -a claude-codeWhat bytedance-seedream does
bytedance-seedream sends Seedream image requests through the first-party Volcengine Ark service for China or BytePlus ModelArk for global deployments. It covers text-to-image work, instruction-based edits, reference inputs, multi-image fusion, grouped results, and streamed groups.
The deployment and model ID must match: China uses doubao-... IDs, while BytePlus uses seedream-... IDs. A request needs ARK_API_KEY, the matching API host, and a model ID supported by that host. Seedream 5.0 Lite supports grouped output and SSE; China 5.0 Pro does not. Image URLs expire after 24 hours, and watermark defaults to true.
An AP or EU endpoint is not a data-residency guarantee because BytePlus may serve an AP request from EU or an EU request from AP. A China token must stay on the China host, and a BytePlus token must stay on a BytePlus host.
What it helps with
- generate an image from a text prompt
- edit an image using instructions and references
- combine several images into one result
- return related images as a streamed group
- match Seedream models to their API region
Example prompts for the agent
- Use
bytedance-seedreamto generate a JPEG image from this description. - Use
bytedance-seedreamto edit the image with these reference images and grouped output. - Configure a Seedream request through BytePlus ModelArk and validate the model and region pairing.
How to install bytedance-seedream
1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill bytedance-seedream -a claude-code2Manually: put the files in place
~/.claude/skills/bytedance-seedream/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/bytedance-seedream/
1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill bytedance-seedream -a codex2Manually: put the files in place
.agents/skills/bytedance-seedream/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill bytedance-seedream -a cursor2Manually: put the files in place
.cursor/skills/bytedance-seedream/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install calesthio/generative-media-skills skills/providers/image-generation/bytedance-seedream2Manually: put the files in place
.github/skills/bytedance-seedream/SKILL.md1Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill bytedance-seedream -a gemini-cli2Platform CLI
gemini skills install https://github.com/calesthio/generative-media-skills --path skills/providers/image-generation/bytedance-seedreamManually: put the files in place
.devin/skills/bytedance-seedream/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add calesthio/generative-media-skills --skill bytedance-seedream -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about bytedance-seedream
How do I install bytedance-seedream in Claude Code?
Run npx skills add calesthio/generative-media-skills --skill bytedance-seedream -a claude-code, then use the skill file at ~/.claude/skills/bytedance-seedream/SKILL.md.
What does bytedance-seedream do?
It connects an application to Seedream through Volcengine Ark or BytePlus ModelArk. The skill covers text generation, image editing, reference inputs, image fusion, grouped results, and SSE streaming.
What does bytedance-seedream require?
It requires an ARK_API_KEY, an official Volcengine Ark or BytePlus ModelArk API, the matching host, and a model ID supported by that host. The token and endpoint must belong to the same deployment region.
Source text
SKILL.md · MIT
---
name: bytedance-seedream
description: Build and operate production image generation and natural-language image editing with ByteDance Seedream through first-party Volcengine Ark (China) or BytePlus ModelArk (global), including model and region selection, multi-reference and grouped outputs, streaming, secure artifact handling, retries, cost controls, prompting, safety, and rights review.
---
# 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.
| Deployment | API base | Current image model IDs documented on 2026-07-09 | Important boundary |
|---|---|---|---|
| Volcengine Ark, China | `https://ark.cn-beijing.volces.com/api/v3` | `doubao-seedream-5-0-pro-260628`, `doubao-seedream-5-0-260128` (also documented as alias `doubao-seedream-5-0-lite-260128`), `doubao-seedream-4-5-251128`, `doubao-seedream-4-0-250828` | China host and `doubao-...` IDs only |
| BytePlus ModelArk, Asia Pacific | `https://ark.ap-southeast.bytepluses.com/api/v3` | `seedream-5-0-260128` (also documented as alias `seedream-5-0-lite-260128`), `seedream-4-5-251128`, `seedream-4-0-250828` | Global host and non-`doubao` IDs only |
| BytePlus ModelArk, Europe | `https://ark.eu-west.bytepluses.com/api/v3` | Seedream 5.0 Lite is documented for EU; confirm the live catalog before deploying any other version | The availability page prohibits restricted models, including Seedream 4.0, in the EU/EU market |
All three use:
```text
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
| Capability | China 5.0 Pro | 5.0 Lite | 4.5 | 4.0 |
|---|---:|---:|---:|---:|
| Text generation and reference/edit input | Yes | Yes | Yes | Yes |
| Max reference images | 10 | 14 | 14 | 10 conservative; generic API says 14 |
| Grouped output (`sequential_image_generation`) | No | Yes | Yes | Yes |
| SSE streaming (`stream`) | No | Yes | Yes | Yes |
| `web_search` tool | No | Yes | No | No |
| Output format control | PNG/JPEG | PNG/JPEG | JPEG only | JPEG only |
| Resolution labels | 1K/2K | 2K/3K/4K | 2K/4K | 1K/2K/4K |
| Prompt optimization | `standard`; not `fast` | `standard`; not `fast` | `standard`; not `fast` | `standard` or `fast` |
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
| Model | Default | Explicit-pixel area | Aspect ratio |
|---|---:|---:|---:|
| China 5.0 Pro | `1024x1024` | 921,600 through 4,624,220 pixels | `[1/16, 16]` |
| 5.0 Lite | `2048x2048` | 3,686,400 through 16,777,216 pixels | `[1/16, 16]` |
| 4.5 | `2048x2048` | 3,686,400 through 16,777,216 pixels | `[1/16, 16]` |
| 4.0 | `2048x2048` | 921,600 through 16,777,216 pixels | `[1/16, 16]` |
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:
```json
{
"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:
```json
{"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:
```text
[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.
### 5. Retry narrowly
Retry network failures, 429 throttles, and transient 500 errors with capped exponential backoff, jitter, and `Retry-After` when present. Bound total attempts and concurrency. Do not retry:
- authentication, account, balance, service-not-open, or model-access failures;
- invalid/missing parameters or bad images;
- content safety, copyright, or privacy rejections;
- an ambiguous timeout automatically if duplicate billing/output is unacceptable.
Ark documents account/model/endpoint-specific IPM, RPM, TPM, burst, quota, and overload errors. BytePlus's current Seedream tutorial lists 500 images/minute per current global model, but account and endpoint controls may be lower. Measure real headers/errors and configure admission control below the proven limit.
### 6. Acquire artifacts safely
For `url` responses, download immediately because links last 24 hours. The artifact URL is a separate untrusted fetch:
- require HTTPS and reject credentials/fragments and unexpected redirects;
- never attach the Ark `Authorization` header to the artifact request;
- enforce a streaming byte cap before buffering;
- allowlist image content types, verify magic bytes, decode dimensions, and rescan;
- write to a temporary file, fsync where required, then atomically promote;
- hash the final bytes and store dimensions, MIME, model, prompt hash, source hashes, review state, and provider usage.
For `b64_json`, use strict base64 decoding and apply the same decoded-byte, magic, dimension, and scanning checks.
### 7. Evaluate before release
Use a fixed regression set with text-to-image, single edit, multi-reference identity consistency, typography, prohibited content, extreme aspect ratio, group count, partial failure, throttling, timeout, and corrupt download cases. Score prompt adherence, edit locality, reference consistency, visual defects, OCR accuracy, safety, latency, and cost. Compare candidate and incumbent models blindly where possible.
## Example: strict non-streaming generation
This complete Python standard-library example is **not executed by this skill**. It uses BytePlus AP and 5.0 Lite, requests base64 to avoid an expiring asset URL, validates the API base, caps decoded size, checks PNG/JPEG magic, and writes durable metadata. Set `ARK_API_KEY`; optionally set `ARK_API_BASE` and `SEEDREAM_MODEL` to a compatible documented pair.
```python
import base64
import binascii
import hashlib
import json
import os
import pathlib
import tempfile
import time
import urllib.error
import urllib.request
ALLOWED = {
"https://ark.cn-beijing.volces.com/api/v3": {
"doubao-seedream-5-0-pro-260628", "doubao-seedream-5-0-260128",
"doubao-seedream-5-0-lite-260128", "doubao-seedream-4-5-251128",
"doubao-seedream-4-0-250828",
},
"https://ark.ap-southeast.bytepluses.com/api/v3": {
"seedream-5-0-260128", "seedream-5-0-lite-260128",
"seedream-4-5-251128", "seedream-4-0-250828",
},
"https://ark.eu-west.bytepluses.com/api/v3": {
"seedream-5-0-260128", "seedream-5-0-lite-260128",
},
}
MAX_IMAGE_BYTES = 25 * 1024 * 1024
MAX_JSON_BYTES = ((MAX_IMAGE_BYTES + 2) // 3) * 4 + 1024 * 1024
def atomic_write(path, data):
path.parent.mkdir(parents=True, exist_ok=True)
handle, temporary = tempfile.mkstemp(dir=path.parent, prefix=".seedream-")
try:
with os.fdopen(handle, "wb") as output:
output.write(data)
output.flush()
os.fsync(output.fileno())
os.replace(temporary, path)
except Exception:
try:
os.unlink(temporary)
except FileNotFoundError:
pass
raise
api_base = os.getenv(
"ARK_API_BASE", "https://ark.ap-southeast.bytepluses.com/api/v3"
).rstrip("/")
api_key = os.environ.get("ARK_API_KEY", "")
model = os.getenv("SEEDREAM_MODEL", "seedream-5-0-260128")
configured_endpoint = os.getenv("SEEDREAM_ALLOWED_ENDPOINT_ID")
configured_endpoint_base = os.getenv("SEEDREAM_ALLOWED_ENDPOINT_API_BASE")
configured_endpoint_model = os.getenv("SEEDREAM_ALLOWED_ENDPOINT_MODEL")
allowed_models = ALLOWED.get(api_base, set())
bound_endpoint = (
model == configured_endpoint
and api_base == configured_endpoint_base
and configured_endpoint_model in allowed_models
)
if api_base not in ALLOWED or (model not in allowed_models and not bound_endpoint):
raise SystemExit("Refusing an undocumented host/model namespace pairing")
payload = {
"model": model,
"prompt": (
"Square editorial product photograph for a coffee brand. A matte black "
"ceramic cup on pale limestone, soft window light from camera left, subtle "
"steam, generous negative space, realistic materials. No logos or text."
),
"size": "2K",
"response_format": "b64_json",
"output_format": "png",
"watermark": True,
}
body = json.dumps(payload, separators=(",", ":")).encode("utf-8")
request = urllib.request.Request(
api_base + "/images/generations",
data=body,
method="POST",
headers={
"Authorization": "Bearer " + api_key,
"Content-Type": "application/json",
"Accept": "application/json",
},
)
print({
"model": payload["model"], "size": payload["size"],
"request_sha256": hashlib.sha256(body).hexdigest(),
"watermark": payload["watermark"],
})
if os.environ.get("SEND_SEEDREAM_REQUEST") != "1":
raise SystemExit("Dry run only; set SEND_SEEDREAM_REQUEST=1 after approving the paid call")
if not api_key:
raise SystemExit("Set ARK_API_KEY before the paid call")
try:
with urllib.request.urlopen(request, timeout=180) as response:
raw = response.read(MAX_JSON_BYTES + 1)
except urllib.error.HTTPError as exc:
# Do not print request headers or secrets.
detail = exc.read(64 * 1024).decode("utf-8", "replace")
raise SystemExit(f"Ark HTTP {exc.code}: {detail}") from exc
if len(raw) > MAX_JSON_BYTES:
raise SystemExit("JSON response exceeded configured base64 envelope cap")
try:
document = json.loads(raw)
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
raise SystemExit("Response was not valid bounded JSON") from exc
if document.get("error"):
raise SystemExit(f"Ark error: {document['error']}")
successful = [item for item in document.get("data", []) if item.get("b64_json")]
failed = [item.get("error") for item in document.get("data", []) if item.get("error")]
if len(successful) != 1 or failed:
raise SystemExit(f"Expected one image; successes={len(successful)} failures={failed}")
encoded = successful[0]["b64_json"]
if len(encoded) > ((MAX_IMAGE_BYTES + 2) // 3) * 4 + 8:
raise SystemExit("Encoded image exceeds the configured cap")
try:
image = base64.b64decode(encoded, validate=True)
except (binascii.Error, ValueError) as exc:
raise SystemExit("Image was not strict base64") from exc
if len(image) > MAX_IMAGE_BYTES:
raise SystemExit("Decoded image exceeds the configured cap")
if image.startswith(b"\x89PNG\r\n\x1a\n"):
suffix = ".png"
elif image.startswith(b"\xff\xd8\xff"):
suffix = ".jpg"
else:
raise SystemExit("Unexpected image signature")
out = pathlib.Path("seedream-output" + suffix)
atomic_write(out, image)
metadata = {
"created_unix": int(time.time()),
"model": document.get("model", model),
"request_sha256": hashlib.sha256(body).hexdigest(),
"artifact_sha256": hashlib.sha256(image).hexdigest(),
"declared_size": successful[0].get("size"),
"usage": document.get("usage"),
"watermark_requested": payload["watermark"],
}
atomic_write(
out.with_suffix(out.suffix + ".json"),
json.dumps(metadata, indent=2, ensure_ascii=False).encode("utf-8"),
)
print(out.resolve())
```
Production code should additionally decode pixels with a maintained image library, enforce width/height/area, scan content, use atomic writes, redact logs, and integrate the retry policy above.
## Example: multiple references, grouped output, and safe URL acquisition
This complete example is **not executed by this skill**. It requires two HTTPS reference URLs fetchable by BytePlus and an administratively maintained comma-separated `SEEDREAM_ASSET_HOSTS` allowlist derived from the provider's current artifact domains. The model may return fewer than three images because grouped mode is `auto`; the program records item-level failures and safely downloads successful URLs without forwarding the API token.
```python
import hashlib
import ipaddress
import json
import os
import pathlib
import socket
import tempfile
import urllib.error
import urllib.parse
import urllib.request
API_BASE = "https://ark.ap-southeast.bytepluses.com/api/v3"
API_KEY = os.environ.get("ARK_API_KEY", "")
REF_1 = os.environ.get("SEEDREAM_REFERENCE_1", "https://example.invalid/reference-1")
REF_2 = os.environ.get("SEEDREAM_REFERENCE_2", "https://example.invalid/reference-2")
MAX_DOWNLOAD = 25 * 1024 * 1024
MAX_API_JSON = 8 * 1024 * 1024
ASSET_HOSTS = {
host.strip().lower()
for host in os.environ.get("SEEDREAM_ASSET_HOSTS", "").split(",")
if host.strip()
}
if not ASSET_HOSTS:
raise SystemExit("Set SEEDREAM_ASSET_HOSTS to approved provider artifact hostnames")
class NoRedirect(urllib.request.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
def validate_artifact_url(url):
parsed = urllib.parse.urlsplit(url)
if (
parsed.scheme != "https" or parsed.hostname not in ASSET_HOSTS
or parsed.username or parsed.password or parsed.fragment
):
raise ValueError("Artifact URL is outside the approved HTTPS allowlist")
addresses = {
info[4][0] for info in socket.getaddrinfo(parsed.hostname, parsed.port or 443)
}
if not addresses or any(not ipaddress.ip_address(value).is_global for value in addresses):
raise ValueError("Artifact host did not resolve exclusively to public addresses")
def atomic_write(path, data):
path.parent.mkdir(parents=True, exist_ok=True)
handle, temporary = tempfile.mkstemp(dir=path.parent, prefix=".seedream-meta-")
try:
with os.fdopen(handle, "wb") as output:
output.write(data)
output.flush()
os.fsync(output.fileno())
os.replace(temporary, path)
except Exception:
try:
os.unlink(temporary)
except FileNotFoundError:
pass
raise
for ref in (REF_1, REF_2):
parsed = urllib.parse.urlsplit(ref)
if parsed.scheme != "https" or parsed.username or parsed.password:
raise SystemExit("References must be credential-free HTTPS URLs")
payload = {
"model": "seedream-5-0-260128",
"prompt": (
"Create exactly three coordinated campaign images. Preserve the product "
"shape and label from image 1. Use only the blue-and-amber palette and soft "
"paper texture from image 2. Frame 1: square hero. Frame 2: vertical detail. "
"Frame 3: wide environmental scene. Keep all label spelling unchanged."
),
"image": [REF_1, REF_2],
"size": "2K",
"sequential_image_generation": "auto",
"sequential_image_generation_options": {"max_images": 3},
"response_format": "url",
"output_format": "jpeg",
"watermark": True,
}
request = urllib.request.Request(
API_BASE + "/images/generations",
data=json.dumps(payload).encode("utf-8"),
method="POST",
headers={
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json",
"Accept": "application/json",
},
)
print({
"model": payload["model"], "references": len(payload["image"]),
"max_images": payload["sequential_image_generation_options"]["max_images"],
"request_sha256": hashlib.sha256(json.dumps(payload, separators=(",", ":")).encode()).hexdigest(),
})
if os.environ.get("SEND_SEEDREAM_REQUEST") != "1":
raise SystemExit("Dry run only; set SEND_SEEDREAM_REQUEST=1 after approving the paid call")
if not API_KEY or "example.invalid" in {urllib.parse.urlsplit(REF_1).hostname, urllib.parse.urlsplit(REF_2).hostname}:
raise SystemExit("Set ARK_API_KEY and both SEEDREAM_REFERENCE environment variables")
try:
with urllib.request.urlopen(request, timeout=240) as response:
response_bytes = response.read(MAX_API_JSON + 1)
except urllib.error.HTTPError as exc:
raise SystemExit(f"Ark HTTP {exc.code}") from exc
if len(response_bytes) > MAX_API_JSON:
raise SystemExit("Grouped API response exceeded configured JSON cap")
try:
document = json.loads(response_bytes)
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
raise SystemExit("Grouped API response was not valid bounded JSON") from exc
def safe_download(url: str, destination: pathlib.Path) -> dict:
opener = urllib.request.build_opener(NoRedirect())
current = url
response = None
for _ in range(6):
validate_artifact_url(current)
# Deliberately no Authorization header here or on any redirect hop.
req = urllib.request.Request(current, headers={"Accept": "image/png,image/jpeg"})
try:
response = opener.open(req, timeout=90)
break
except urllib.error.HTTPError as exc:
if exc.code not in {301, 302, 303, 307, 308}:
raise
location = exc.headers.get("Location")
exc.close()
if not location:
raise ValueError("Artifact redirect omitted Location")
current = urllib.parse.urljoin(current, location)
else:
raise ValueError("Too many artifact redirects")
hasher = hashlib.sha256()
total = 0
prefix = b""
destination.parent.mkdir(parents=True, exist_ok=True)
with response:
content_type = response.headers.get_content_type()
if content_type not in {"image/png", "image/jpeg"}:
raise ValueError(f"Unexpected Content-Type: {content_type}")
declared = response.headers.get("Content-Length")
if declared and int(declared) > MAX_DOWNLOAD:
raise ValueError("Artifact exceeds byte cap")
fd, temporary = tempfile.mkstemp(dir=destination.parent, prefix=".seedream-")
try:
with os.fdopen(fd, "wb") as output:
while True:
chunk = response.read(64 * 1024)
if not chunk:
break
total += len(chunk)
if total > MAX_DOWNLOAD:
raise ValueError("Artifact exceeded byte cap while streaming")
if len(prefix) < 12:
prefix += chunk[: 12 - len(prefix)]
hasher.update(chunk)
output.write(chunk)
output.flush()
os.fsync(output.fileno())
is_png = prefix.startswith(b"\x89PNG\r\n\x1a\n")
is_jpeg = prefix.startswith(b"\xff\xd8\xff")
if not (is_png or is_jpeg):
raise ValueError("Unexpected artifact signature")
os.replace(temporary, destination)
except Exception:
try:
os.unlink(temporary)
except FileNotFoundError:
pass
raise
return {"bytes": total, "sha256": hasher.hexdigest(), "content_type": content_type}
if document.get("error"):
raise SystemExit(f"Ark error: {document['error']}")
manifest = {"model": document.get("model"), "usage": document.get("usage"), "items": []}
success_index = 0
for index, item in enumerate(document.get("data", [])):
if item.get("error"):
manifest["items"].append({"index": index, "error": item["error"]})
continue
if not item.get("url"):
manifest["items"].append({"index": index, "error": "missing url"})
continue
success_index += 1
path = pathlib.Path("seedream-set") / f"image-{success_index:02d}.jpg"
audit = safe_download(item["url"], path)
manifest["items"].append({"index": index, "path": str(path), **audit})
atomic_write(
pathlib.Path("seedream-set/manifest.json"),
json.dumps(manifest, indent=2, ensure_ascii=False).encode("utf-8"),
)
if success_index == 0:
raise SystemExit("No successful images")
print(f"Saved {success_index} image(s); review count, labels, and visual consistency")
```
## Example: request-scoped SSE
This curl example is **not executed by this skill**. It demonstrates the wire shape, not production parsing. Use a real SSE parser in production, preserve event order, handle partial failures, and wait for `image_generation.completed`.
```bash
: "${ARK_API_KEY:?set ARK_API_KEY}"
: "${SEND_SEEDREAM_REQUEST:?set SEND_SEEDREAM_REQUEST=1 after approving the paid call}"
[ "${SEND_SEEDREAM_REQUEST}" = "1" ] || { echo 'Refusing paid call without SEND_SEEDREAM_REQUEST=1' >&2; exit 2; }
curl --fail-with-body --no-buffer \
--connect-timeout 10 --max-time 300 \
'https://ark.ap-southeast.bytepluses.com/api/v3/images/generations' \
-H "Authorization: Bearer ${ARK_API_KEY}" \
-H 'Content-Type: application/json' \
-H 'Accept: text/event-stream' \
--data-binary @- <<'JSON'
{
"model": "seedream-5-0-260128",
"prompt": "Create a three-frame horizontal storyboard of a paper airplane crossing a quiet library: establishing shot, close tracking shot, final landing. Consistent airplane and lighting in every frame.",
"size": "2K",
"sequential_image_generation": "auto",
"sequential_image_generation_options": {"max_images": 3},
"response_format": "url",
"stream": true,
"watermark": true
}
JSON
```
## Err...
© calesthio · MIT · calesthio/generative-media-skills