seedream-image
Generate, edit, stream, or decompose images with Seedream 5.0 via AceDataCloud. Use for text-to-image, reference-image editing, related image sets, transparent-background edits, or editable layer extraction.
Install
npx skills add https://github.com/AceDataCloud/Skills/tree/main/skills/seedream-image
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install acedatacloud-skills@llmmart
git clone https://github.com/AceDataCloud/Skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole acedatacloud/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Seedream Image
Use POST https://api.acedata.cloud/seedream/images. Authenticate with Authorization: Bearer $ACEDATACLOUD_API_TOKEN and JSON request bodies.
First-time setup
- Install the official Skill with
clawhub install @acedatacloud/seedream. Check that the ClawHub publisher is @acedatacloud. - Sign in at AceDataCloud → Applications, open General application, and check Seedream access, balance, and current pricing. Copy its API key, or select Manage Keys → Create for a separate key. Copy the key value without
Bearer; aplatform-...management token is not a service API key. - If you enable Allowed APIs restrictions, include
/seedream/imagesand/seedream/tasks. Advanced workflows below may call additional routes. - On the OpenClaw Gateway host, put
ACEDATACLOUD_API_TOKEN=your_api_key_herein~/.openclaw/.env, then restart the Gateway and start a new session. For a direct terminal test, runexport ACEDATACLOUD_API_TOKEN="your_api_key_here"in that shell. Never put the key in a prompt or commit an.envfile. - Follow the Generate or edit example below. If this workflow returns a task ID, query that same task until it finishes; do not submit the same billable request again just to check progress.
Illustrated key setup, first run, and troubleshooting · Token details
Pick the model from the requested capability
| Capability | Seedream 5.0 Pro | Seedream 5.0 Lite |
|---|---|---|
| Model ID | doubao-seedream-5-0-pro-260628 |
doubao-seedream-5-0-lite-260128 |
| Generate/edit one image | Yes | Yes |
| Reference images | Up to 10 | Up to 14 |
| Related image set | No | Yes; input + output ≤ 15 |
| Streaming / web search | No | Yes |
| Layer decomposition / transparent background | Yes | No |
| Prompt optimization | standard, fast |
standard |
| Preset sizes | 1K, 1.5K, 2K |
2K, 3K, 4K |
Seedream 4.5 and 4.0 remain available for compatibility. Do not send a parameter to a model that does not support it.
Generate or edit
curl https://api.acedata.cloud/seedream/images \
-H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-lite-260128",
"prompt": "a four-panel storyboard of a courier crossing a rainy neon city",
"size": "2K",
"sequential_image_generation": "auto",
"sequential_image_generation_options": {"max_images": 4},
"watermark": false
}'
For editing, add image as one URL/Base64 string or an array. response_format is url or b64_json; 5.0 Pro/Lite also support output_format as jpeg or png. Explicit dimensions use WIDTHxHEIGHT and must satisfy the selected model's pixel and aspect-ratio limits.
Use Lite web search only when current information matters:
{"tools": [{"type": "web_search"}]}
Transparent-background Pro edit
Use one transparent PNG input and PNG output:
{
"model": "doubao-seedream-5-0-pro-260628",
"prompt": "replace the parrot with a peacock",
"image": "https://example.com/layer.png",
"background": "transparent",
"output_format": "png",
"size": "1.5K"
}
Do not combine background with layer decomposition. transparent with JPEG is invalid.
Decompose an image into editable layers
layer_decomposition is Pro-only and requires exactly one PNG/JPEG. Omit prompt for automatic decomposition, describe desired elements in natural language, or use normalized <bbox> coordinates.
curl https://api.acedata.cloud/seedream/images \
-H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedream-5-0-pro-260628",
"image": "https://example.com/poster.png",
"layer_decomposition": true,
"size": "auto",
"watermark": false
}'
The response contains one base image (z_index: 0) and up to 16 transparent PNG layers. Each layer can include name, description, and bounding_box.absolute/normalized. To recompose, scale each layer to its bounding-box width and height, place it at left/top, and draw in ascending z_index. Any layer failure fails the whole decomposition.
Async tasks
Generation can take time. Prefer "async": true; the response returns task_id. Poll using:
POST /seedream/tasks
{"action": "retrieve", "id": "<task_id>"}
Follow async task polling. Use callback_url only when a real public webhook exists. Do not use a health endpoint as a fake callback.
Streaming
Lite/4.x support streaming. Send "stream": true with Accept: application/x-ndjson; read one normalized JSON event per line until image_generation.completed. Do not combine streaming with async or callback_url.
image_generation.partial_succeeded: one generated imageimage_generation.partial_failed: one failed item; other Lite images may still succeedimage_generation.completed: final usage and the only billing completion
Agent tools
- MCP:
pip install mcp-seedream-pro; useseedream_generate_image,seedream_edit_image,seedream_decompose_image, then poll withseedream_get_task. - CLI:
pip install seedream-cli; useseedream generate,seedream edit,seedream decompose, orseedream generate --stream --json. - Hosted MCP:
https://seedream.mcp.acedata.cloud/mcp.
MCP image tools are asynchronous, so use REST or CLI for real-time streaming.
Result and billing safeguards
- URL results expire; persist files promptly.
- Lite
data[]may mix successful images and per-itemerrorobjects. Count only successful images. - Pro layer items are billed individually by actual output size; the base and every successful layer count separately.
- Preserve
z_index, bounding boxes, item errors,tools, andusage; do not flatten the response to a URL list. - Never estimate final billed cost from requested size alone. Use the returned
cost/usage and the live pricing page: https://platform.acedata.cloud/services/seedream?tab=pricing.
Files (skills)
-
SKILL.md 6.7 KB
--- name: seedream-image description: Generate, edit, stream, or decompose images with Seedream 5.0 via AceDataCloud. Use for text-to-image, reference-image editing, related image sets, transparent-background edits, or editable layer extraction. license: Apache-2.0 metadata: author: acedatacloud version: "1.1" compatibility: Requires ACEDATACLOUD_API_TOKEN (get an API key at https://platform.acedata.cloud/console/applications). Optionally pair with mcp-seedream-pro or seedream-cli. --- # Seedream Image Use `POST https://api.acedata.cloud/seedream/images`. Authenticate with `Authorization: Bearer $ACEDATACLOUD_API_TOKEN` and JSON request bodies. ## First-time setup 1. Install the official Skill with `clawhub install @acedatacloud/seedream`. Check that the ClawHub publisher is **@acedatacloud**. 2. Sign in at [AceDataCloud → Applications](https://platform.acedata.cloud/console/applications), open **General application**, and check Seedream access, balance, and current pricing. Copy its API key, or select **Manage Keys → Create** for a separate key. Copy the key value without `Bearer `; a `platform-...` management token is not a service API key. 3. If you enable **Allowed APIs** restrictions, include `/seedream/images` and `/seedream/tasks`. Advanced workflows below may call additional routes. 4. On the OpenClaw Gateway host, put `ACEDATACLOUD_API_TOKEN=your_api_key_here` in `~/.openclaw/.env`, then restart the Gateway and start a new session. For a direct terminal test, run `export ACEDATACLOUD_API_TOKEN="your_api_key_here"` in that shell. Never put the key in a prompt or commit an `.env` file. 5. Follow the **Generate or edit** example below. If this workflow returns a task ID, query that same task until it finishes; do not submit the same billable request again just to check progress. [Illustrated key setup, first run, and troubleshooting](https://github.com/AceDataCloud/Skills#first-run-with-clawhub-and-openclaw) · [Token details](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/authentication.md) ## Pick the model from the requested capability | Capability | Seedream 5.0 Pro | Seedream 5.0 Lite | |---|---|---| | Model ID | `doubao-seedream-5-0-pro-260628` | `doubao-seedream-5-0-lite-260128` | | Generate/edit one image | Yes | Yes | | Reference images | Up to 10 | Up to 14 | | Related image set | No | Yes; input + output ≤ 15 | | Streaming / web search | No | Yes | | Layer decomposition / transparent background | Yes | No | | Prompt optimization | `standard`, `fast` | `standard` | | Preset sizes | `1K`, `1.5K`, `2K` | `2K`, `3K`, `4K` | Seedream 4.5 and 4.0 remain available for compatibility. Do not send a parameter to a model that does not support it. ## Generate or edit ```bash curl https://api.acedata.cloud/seedream/images \ -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedream-5-0-lite-260128", "prompt": "a four-panel storyboard of a courier crossing a rainy neon city", "size": "2K", "sequential_image_generation": "auto", "sequential_image_generation_options": {"max_images": 4}, "watermark": false }' ``` For editing, add `image` as one URL/Base64 string or an array. `response_format` is `url` or `b64_json`; 5.0 Pro/Lite also support `output_format` as `jpeg` or `png`. Explicit dimensions use `WIDTHxHEIGHT` and must satisfy the selected model's pixel and aspect-ratio limits. Use Lite web search only when current information matters: ```json {"tools": [{"type": "web_search"}]} ``` ## Transparent-background Pro edit Use one transparent PNG input and PNG output: ```json { "model": "doubao-seedream-5-0-pro-260628", "prompt": "replace the parrot with a peacock", "image": "https://example.com/layer.png", "background": "transparent", "output_format": "png", "size": "1.5K" } ``` Do not combine `background` with layer decomposition. `transparent` with JPEG is invalid. ## Decompose an image into editable layers `layer_decomposition` is Pro-only and requires exactly one PNG/JPEG. Omit `prompt` for automatic decomposition, describe desired elements in natural language, or use normalized `<bbox>` coordinates. ```bash curl https://api.acedata.cloud/seedream/images \ -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "doubao-seedream-5-0-pro-260628", "image": "https://example.com/poster.png", "layer_decomposition": true, "size": "auto", "watermark": false }' ``` The response contains one base image (`z_index: 0`) and up to 16 transparent PNG layers. Each layer can include `name`, `description`, and `bounding_box.absolute`/`normalized`. To recompose, scale each layer to its bounding-box width and height, place it at left/top, and draw in ascending `z_index`. Any layer failure fails the whole decomposition. ## Async tasks Generation can take time. Prefer `"async": true`; the response returns `task_id`. Poll using: ```json POST /seedream/tasks {"action": "retrieve", "id": "<task_id>"} ``` Follow [async task polling](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/async-tasks.md). Use `callback_url` only when a real public webhook exists. Do not use a health endpoint as a fake callback. ## Streaming Lite/4.x support streaming. Send `"stream": true` with `Accept: application/x-ndjson`; read one normalized JSON event per line until `image_generation.completed`. Do not combine streaming with `async` or `callback_url`. - `image_generation.partial_succeeded`: one generated image - `image_generation.partial_failed`: one failed item; other Lite images may still succeed - `image_generation.completed`: final usage and the only billing completion ## Agent tools - MCP: `pip install mcp-seedream-pro`; use `seedream_generate_image`, `seedream_edit_image`, `seedream_decompose_image`, then poll with `seedream_get_task`. - CLI: `pip install seedream-cli`; use `seedream generate`, `seedream edit`, `seedream decompose`, or `seedream generate --stream --json`. - Hosted MCP: `https://seedream.mcp.acedata.cloud/mcp`. MCP image tools are asynchronous, so use REST or CLI for real-time streaming. ## Result and billing safeguards - URL results expire; persist files promptly. - Lite `data[]` may mix successful images and per-item `error` objects. Count only successful images. - Pro layer items are billed individually by actual output size; the base and every successful layer count separately. - Preserve `z_index`, bounding boxes, item errors, `tools`, and `usage`; do not flatten the response to a URL list. - Never estimate final billed cost from requested size alone. Use the returned `cost`/usage and the live pricing page: https://platform.acedata.cloud/services/seedream?tab=pricing.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.