Seedream-Imagegen

Seedream Imagegen

What is it?

Seedream 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.

Under 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.

Capabilities

Generation (generate)

• Text-to-image — photorealistic scenes, product photography, illustrations, concept art, UI mockups, infographics, scientific diagrams, ads, logos, historical reconstructions, and more.
• 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.
• Multi-image fusion — combine subjects, backgrounds, and styles from multiple references into one coherent result.
• Lite image sets — generate a sequence of related images with consistent characters, settings, and style across all frames (streaming or batch).
• Web-aware generation (Lite) — the model can perform native web search to incorporate current facts, news, weather, or market data directly into the image.

Editing (edit)

• Targeted edits — change only what you specify (text, objects, clothing, lighting, weather) while preserving everything else — identity, background, composition, and unedited regions.
• 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.
• Sketch-to-render — turn rough sketches or wireframes into photorealistic or styled renders.

Chroma-key transparency

• 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.

Safety by design

• 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.
• 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.
• 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.
• Atomic saves — images are written via hardlink or exclusive-create, preventing partial files and accidental overwrites.
• Secret redaction — API keys, Base64 image data, and signed URLs are stripped from all diagnostics, dry-run output, and error messages.

How to use

Once installed and configured, just talk to Claude Code naturally:

"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"

"Edit this photo — change the model's shirt from red to navy blue, keep everything else exactly the same"

"Create a 4-panel illustration series of a fox exploring four seasons, consistent character design throughout"

Claude 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.

Model comparison

• 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.
• Pro is for precise interactive editing with coordinate/region controls, or when you specifically need Pro's output characteristics at 1K/1.5K/2K.

The official Image Generation API/model support matrix 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 and interactive-editing guide. references/lite.md, references/pro.md, and the test suite turn those published capabilities into this release's local execution contract.

Documentation

• Skill workflow — model selection rules, generation flow, billing safeguards, and delivery checklist.
• Prompt guidance — the single source of truth for natural-language cores, detail density, grounded information, editing patterns, and acceptance criteria.
• Prompt recipes and visual assets — twelve composable recipes and five optional style references, including dedicated landscape, portrait, and flowchart contracts; visual assets are never injected by default.
• CLI reference — all parameters, shell conventions, dry-run behavior, state inspection, and typical commands.
• Lite specification / Pro specification — model-specific payload constraints, size tables, group/image-set rules, and SSE stream events.
• Chroma-key reference — validated command, alpha contract, failure rules, and three-step delivery check.
• Execution flow — full architecture, request lifecycle, state machine, and security mechanisms.

Requirements

• Claude Code 2.1.196+ with skills support.
• Python 3.10+ and pip.
• A Volcengine Ark API key with Seedream model access. Get one here.
• Network access to https://ark.cn-beijing.volces.com/api/v3 (or your custom endpoint).
• 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.

Install

Via npx skills (recommended)

Personal install — available in every project:

npx skills add YFan945/Seedream-Imagegen --skill imagegen -g -a claude-code --copy -y
Test-Path "$HOME\.claude\skills\imagegen\SKILL.md"
python -m pip install -r "$HOME\.claude\skills\imagegen\requirements.txt"

Project install — run from the target project root:

npx skills add YFan945/Seedream-Imagegen --skill imagegen -a claude-code --copy -y
Test-Path ".claude\skills\imagegen\SKILL.md"
python -m pip install -r ".claude\skills\imagegen\requirements.txt"

Success means the file SKILL.md exists at the expected path. Claude Code documents skill locations in its skills guide; npx skills documents -a claude-code in its CLI repository.

Update

Before 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.

For a personal install:

npx skills update imagegen -g -y
Test-Path "$HOME\.claude\skills\imagegen\SKILL.md"
python -m pip install -r "$HOME\.claude\skills\imagegen\requirements.txt"

For a project install, run from the target project root:

npx skills update imagegen -p -y
Test-Path ".claude\skills\imagegen\SKILL.md"
python -m pip install -r ".claude\skills\imagegen\requirements.txt"

Restore 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.

For 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, replace the installed directory the same way, and restore .env.

Manual Git install

git clone --depth 1 https://github.com/YFan945/Seedream-Imagegen.git "$HOME\seedream-imagegen"
Copy-Item "$HOME\seedream-imagegen\skills\imagegen" "$HOME\.claude\skills\imagegen" -Recurse
python -m pip install -r "$HOME\.claude\skills\imagegen\requirements.txt"

git clone --depth 1 https://github.com/YFan945/Seedream-Imagegen.git "$HOME/seedream-imagegen"
cp -R "$HOME/seedream-imagegen/skills/imagegen" "$HOME/.claude/skills/imagegen"
python -m pip install -r "$HOME/.claude/skills/imagegen/requirements.txt"

For ZIP: rename the extracted directory to imagegen and verify the SKILL.md path.

Uninstall

Remove the imagegen directory, or for CLI-managed personal installs: npx skills remove imagegen -g -a claude-code.

Configuration

Copy .env.example to .env inside the installed skill directory and set your API key:

ARK_API_KEY=your_ark_api_key
# ARK_BASE_URL=https://custom.example/api/v3
# ARK_PRO_MODEL=your_pro_model_id
# ARK_LITE_MODEL=your_lite_model_id

• Built-in defaults: base URL https://ark.cn-beijing.volces.com/api/v3, Pro/Lite model IDs are pre-configured.
• Priority: process environment > skill-local .env > built-in defaults.
• The CLI reads these four keys lazily into an immutable per-run config. It never modifies os.environ or your .env file.
• UTF-8 files with or without BOM are accepted.
• Never commit .env or paste credentials into prompts or logs.

Smoke test (free)

Run from any directory. Local-only, no API key required:

$skillDir = "$HOME\.claude\skills\imagegen"
$projectDir = (Get-Location).Path
python "$skillDir\scripts\image_gen.py" generate --model lite `
  --prompt "一只坐在窗边的橘猫，柔和晨光" `
  --out "$projectDir\output\cat.png" --dry-run

This prints the validated payload, output plan, and preflight diagnostics without calling the API.

Default 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.

Chroma-key scope

Chroma 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 for the validated command, alpha contract, and delivery check.

Development

From the cloned repository root:

python -m pip install -r requirements-dev.txt
python -m pytest -q
python -m compileall -q skills/imagegen/scripts tests
git diff --check

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 for the full architecture, and 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.

License

Apache License 2.0. See LICENSE.txt.