![\"Seedream](\"logo/seedream-imagegen-logo.png\"){kind=logo}
\n\n \n
\n English · 简体中文\n
\n\n## What is it?\n\nSeedream Imagegen is a **Claude Code skill** that gives Claude the ability to generate and edit raster images using ByteDance's Doubao Seedream 5.0 models via Volcengine Ark. After a one-time local API key setup, you describe what you want in natural language — Claude writes the prompt, picks the right model, calls the API, validates the output, and delivers the result. You never paste the key into the conversation, write a prompt template, or run the generation script yourself.\n\nUnder the hood, a single validated Python CLI handles everything: model selection with capability checks, payload construction with image preflight, free dry-run previews, payload-fingerprinted request state locks that prevent accidental double-billing, atomic no-clobber saves, and recursive secret redaction in all diagnostics.\n\n## Capabilities\n\n### Generation (`generate`)\n\n- **Text-to-image** — photorealistic scenes, product photography, illustrations, concept art, UI mockups, infographics, scientific diagrams, ads, logos, historical reconstructions, and more.\n- **Reference-image generation** — provide up to 14 (Lite) or 10 (Pro) images as style, composition, or content references. The agent labels each image by role and writes structured prompts around them.\n- **Multi-image fusion** — combine subjects, backgrounds, and styles from multiple references into one coherent result.\n- **Lite image sets** — generate a sequence of related images with consistent characters, settings, and style across all frames (streaming or batch).\n- **Web-aware generation (Lite)** — the model can perform native web search to incorporate current facts, news, weather, or market data directly into the image.\n\n### Editing (`edit`)\n\n- **Targeted edits** — change only what you specify (text, objects, clothing, lighting, weather) while preserving everything else — identity, background, composition, and unedited regions.\n- **Coordinate and region interaction (Pro)** — draw circles, arrows, numbered points, or doodles on an image and the model edits precisely those regions. Pro is optimized for this; Lite supports basic markup.\n- **Sketch-to-render** — turn rough sketches or wireframes into photorealistic or styled renders.\n\n### Chroma-key transparency\n\n- Generate subjects on flat green/magenta/blue/cyan backgrounds, then run the bundled `remove_chroma_key.py` to produce clean transparent PNGs or WebPs — with soft matte, edge feathering, despill, and border-connected mode. Not for hair, glass, smoke, or translucency.\n\n### Safety by design\n\n- **Billing guards** — every real request creates a payload-fingerprinted state lock. Timeouts, disconnects, 5xx errors, and uncertain saves are marked `ambiguous` and never retried automatically. You verify output and billing before the next request.\n- **Input validation** — local files and data URIs are decoded and checked for format, dimensions, file size, and aspect ratio before any network call; remote references receive strict public-URL syntax checks and are fetched by Ark.\n- **Safe output downloads** — every returned hostname is resolved before connecting; all A/AAAA answers must be public, the socket is pinned to the validated IP, and redirects are refused.\n- **Atomic saves** — images are written via hardlink or exclusive-create, preventing partial files and accidental overwrites.\n- **Secret redaction** — API keys, Base64 image data, and signed URLs are stripped from all diagnostics, dry-run output, and error messages.\n\n## How to use\n\nOnce installed and configured, just talk to Claude Code naturally:\n\n> *\"Generate a minimalist product photo of a ceramic coffee cup on a warm wooden table, morning light from the left, 2K, save to output/cup.png\"*\n\n> *\"Edit this photo — change the model's shirt from red to navy blue, keep everything else exactly the same\"*\n\n> *\"Create a 4-panel illustration series of a fox exploring four seasons, consistent character design throughout\"*\n\nClaude handles model selection (Lite vs Pro), writes a grounded structured prompt, and completes necessary retries, regenerations, or variations within the requested task without a separate confirmation step. It does not add `--dry-run` automatically; dry-run remains available when you explicitly request a local preflight. A `pending` or `ambiguous` request still stops the workflow because its output and billing state are unknown.\n\n## Model comparison\n\n| Capability | Lite | Pro |\n|---|---|---|\n| Resolution tiers | 2K / 3K / 4K | 1K / 1.5K / 2K |\n| Reference images | Up to 14 | Up to 10 |\n| Image sets (batch) | ✓ | ✗ |\n| Streaming output | ✓ | ✗ |\n| Native web search | ✓ | ✗ |\n| Coordinate/region editing | Basic markup | Optimized, preferred |\n\n- **Lite** is the CLI default and supports single images, image sets, high resolutions (3K/4K), web-aware generation, and streaming. When the user has not selected a model and the task does not require web search, the skill asks first; cancellation or an empty answer is not treated as a Lite selection.\n- **Pro** is for precise interactive editing with coordinate/region controls, or when you specifically need Pro's output characteristics at 1K/1.5K/2K.\n\nThe official [Image Generation API/model support matrix](https://www.volcengine.com/docs/82379/1541523?lang=zh) provides directly reviewable model IDs, reference-image limits, resolution tiers, and Lite/Pro capability boundaries. The general prompt guide explicitly covers Seedream 5.0 Lite, 4.5, and 4.0; Pro conservatively inherits those general natural-language principles while its model-specific behavior follows the [Pro tutorial](https://www.volcengine.com/docs/82379/2582774?lang=zh) and [interactive-editing guide](https://www.volcengine.com/docs/82379/2582775?lang=zh). [`references/lite.md`](skills/imagegen/references/lite.md), [`references/pro.md`](skills/imagegen/references/pro.md), and the test suite turn those published capabilities into this release's local execution contract.\n\n## Documentation\n\n- [Skill workflow](skills/imagegen/SKILL.md) — model selection rules, generation flow, billing safeguards, and delivery checklist.\n- [Prompt guidance](skills/imagegen/references/prompting.md) — the single source of truth for natural-language cores, detail density, grounded information, editing patterns, and acceptance criteria.\n- [Prompt recipes and visual assets](skills/imagegen/references/sample-prompts.md) — twelve composable recipes and five optional style references, including dedicated landscape, portrait, and flowchart contracts; visual assets are never injected by default.\n- [CLI reference](skills/imagegen/references/cli.md) — all parameters, shell conventions, dry-run behavior, state inspection, and typical commands.\n- [Lite specification](skills/imagegen/references/lite.md) / [Pro specification](skills/imagegen/references/pro.md) — model-specific payload constraints, size tables, group/image-set rules, and SSE stream events.\n- [Chroma-key reference](skills/imagegen/references/chroma-key.md) — validated command, alpha contract, failure rules, and three-step delivery check.\n- [Execution flow](docs/execution-flow.md) — full architecture, request lifecycle, state machine, and security mechanisms.\n\n## Requirements\n\n- Claude Code 2.1.196+ with skills support.\n- **Python** 3.10+ and `pip`.\n- A **Volcengine Ark API key** with Seedream model access. [Get one here](https://console.volcengine.com/ark/).\n- Network access to `https://ark.cn-beijing.volces.com/api/v3` (or your custom endpoint).\n- `skills/imagegen/requirements.txt` contains only runtime dependencies (Pillow and pillow-heif). Repository development uses the root `requirements-dev.txt`, which includes the runtime file plus pytest and PyYAML.\n\n## Install\n\n### Via npx skills (recommended)\n\nPersonal install — available in every project:\n\n```powershell\nnpx skills add YFan945/Seedream-Imagegen --skill imagegen -g -a claude-code --copy -y\nTest-Path \"$HOME\\.claude\\skills\\imagegen\\SKILL.md\"\npython -m pip install -r \"$HOME\\.claude\\skills\\imagegen\\requirements.txt\"\n```\n\nProject install — run from the target project root:\n\n```powershell\nnpx skills add YFan945/Seedream-Imagegen --skill imagegen -a claude-code --copy -y\nTest-Path \".claude\\skills\\imagegen\\SKILL.md\"\npython -m pip install -r \".claude\\skills\\imagegen\\requirements.txt\"\n```\n\nSuccess means the file `SKILL.md` exists at the expected path. Claude Code documents skill locations in its [skills guide](https://code.claude.com/docs/en/slash-commands); `npx skills` documents `-a claude-code` in its [CLI repository](https://github.com/vercel-labs/skills).\n\n### Update\n\nBefore updating, back up the skill-local `.env` to a safe location. It contains your Ark credentials and must not be committed or pasted into logs.\n\nFor a personal install:\n\n```powershell\nnpx skills update imagegen -g -y\nTest-Path \"$HOME\\.claude\\skills\\imagegen\\SKILL.md\"\npython -m pip install -r \"$HOME\\.claude\\skills\\imagegen\\requirements.txt\"\n```\n\nFor a project install, run from the target project root:\n\n```powershell\nnpx skills update imagegen -p -y\nTest-Path \".claude\\skills\\imagegen\\SKILL.md\"\npython -m pip install -r \".claude\\skills\\imagegen\\requirements.txt\"\n```\n\nRestore the backed-up `.env` if the update replaced the installed directory. Reinstall the requirements after every update because pinned runtime dependencies may change. If the current Claude Code session still uses the previous instructions, start a new session.\n\nFor a manual Git install, back up `.env`, run `git -C \"$HOME\\seedream-imagegen\" pull --ff-only`, replace the installed `imagegen` directory with the refreshed `skills/imagegen` directory, restore `.env`, and reinstall `requirements.txt`. For a ZIP install, download the latest [Release](https://github.com/YFan945/Seedream-Imagegen/releases), replace the installed directory the same way, and restore `.env`.\n\n### Manual Git install\n\n```powershell\ngit clone --depth 1 https://github.com/YFan945/Seedream-Imagegen.git \"$HOME\\seedream-imagegen\"\nCopy-Item \"$HOME\\seedream-imagegen\\skills\\imagegen\" \"$HOME\\.claude\\skills\\imagegen\" -Recurse\npython -m pip install -r \"$HOME\\.claude\\skills\\imagegen\\requirements.txt\"\n```\n\n```bash\ngit clone --depth 1 https://github.com/YFan945/Seedream-Imagegen.git \"$HOME/seedream-imagegen\"\ncp -R \"$HOME/seedream-imagegen/skills/imagegen\" \"$HOME/.claude/skills/imagegen\"\npython -m pip install -r \"$HOME/.claude/skills/imagegen/requirements.txt\"\n```\n\nFor ZIP: rename the extracted directory to `imagegen` and verify the `SKILL.md` path.\n\n### Uninstall\n\nRemove the `imagegen` directory, or for CLI-managed personal installs: `npx skills remove imagegen -g -a claude-code`.\n\n## Configuration\n\nCopy `.env.example` to `.env` inside the installed skill directory and set your API key:\n\n```dotenv\nARK_API_KEY=your_ark_api_key\n# ARK_BASE_URL=https://custom.example/api/v3\n# ARK_PRO_MODEL=your_pro_model_id\n# ARK_LITE_MODEL=your_lite_model_id\n```\n\n- Built-in defaults: base URL `https://ark.cn-beijing.volces.com/api/v3`, Pro/Lite model IDs are pre-configured.\n- Priority: process environment > skill-local `.env` > built-in defaults.\n- The CLI reads these four keys lazily into an immutable per-run config. It never modifies `os.environ` or your `.env` file.\n- UTF-8 files with or without BOM are accepted.\n- **Never commit `.env`** or paste credentials into prompts or logs.\n\n## Smoke test (free)\n\nRun from any directory. Local-only, no API key required:\n\n```powershell\n$skillDir = \"$HOME\\.claude\\skills\\imagegen\"\n$projectDir = (Get-Location).Path\npython \"$skillDir\\scripts\\image_gen.py\" generate --model lite `\n --prompt \"一只坐在窗边的橘猫，柔和晨光\" `\n --out \"$projectDir\\output\\cat.png\" --dry-run\n```\n\nThis prints the validated payload, output plan, and preflight diagnostics without calling the API.\n\nDefault behavior: single images save to `$projectDir/` with prompt-derived filenames; Lite image sets save to `$projectDir/images/`. `--private-filenames` (hash-based naming) is off by default — use only when explicitly needed. Real generation may incur charges. State locks live in `$projectDir/.seedream-requests/`; inspect them with `state --project-dir`. Never delete a `pending` or `ambiguous` state file without verifying output and billing first.\n\n## Chroma-key scope\n\nChroma key works for **flat, high-saturation backgrounds** (green, magenta, blue, cyan) and **solid subjects** that don't share the key hue. It is not a general segmentation tool — hair, smoke, glass, liquids, motion blur, soft shadows, and translucency are out of scope. See [`references/chroma-key.md`](skills/imagegen/references/chroma-key.md) for the validated command, alpha contract, and delivery check.\n\n## Development\n\nFrom the cloned repository root:\n\n```powershell\npython -m pip install -r requirements-dev.txt\npython -m pytest -q\npython -m compileall -q skills/imagegen/scripts tests\ngit diff --check\n```\n\n`pyproject.toml` provides project metadata and `pytest` configuration; it does not duplicate dependency declarations. Skill users install `skills/imagegen/requirements.txt`; contributors and CI install `requirements-dev.txt`. See [`docs/execution-flow.md`](docs/execution-flow.md) for the full architecture, and [`AGENTS.md`](AGENTS.md) for contribution rules. Image-generation unit tests replace HTTP and socket connections with failing mocks, while CLI contract tests use explicit dry-run; the suite never issues billable requests.\n\n## License\n\nApache License 2.0. See [LICENSE.txt](LICENSE.txt).\n"}