git clone https://github.com/mittulmadaan/byteplus-seedream-mcp
cd byteplus-seedream-mcp
pip install packages/seedream-sdk packages/seedream-mcp -e packages/seedream-cli
seedream auth login        # stores credentials in ~/.seedream/credentials
seedream skill install     # patches Claude Desktop + Claude Code configs automatically
# Restart your AI client

{
  "mcpServers": {
    "seedream": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "seedream_mcp"]
    }
  }
}

docker build -f packages/seedream-mcp/docker/Dockerfile -t seedream-mcp .

docker run -p 8000:8000 \
  -e MCP_TRANSPORT=sse \
  -e ARK_API_KEY=<key> \
  -e ARK_AK=<ak> \
  -e ARK_SK=<sk> \
  -e MCP_AUTH_TOKEN=<strong-random-token> \
  seedream-mcp

# Text-to-image
seedream_generate(prompt="A silver espresso machine, morning light, steam rising", size="2K")
→ { model: "seedream-4-5-251128", count: 1, images: [{ url: "https://..." }] }

# Seedream 5.0 Lite, 4K
seedream_generate(prompt="Editorial close-up portrait, sculptural hat, studio lighting",
                  model="5.0-lite", size="4K")

# Editing / reference — say what to change and what to keep
seedream_generate(
  prompt="Use Image 1. Replace the background with a snowy forest at dusk. Keep the
          subject's pose, outfit, and the product label unchanged.",
  image_urls=["https://example.com/photo.png"]
)

# Consistent multi-panel set
seedream_generate(prompt="A 4-panel comic of a cat's morning, flat pastel style",
                  sequential=true, num_images=4)

seedream_list_tos_buckets()                                  # ask which bucket
seedream_upload_image_to_tos(file_path="/path/ref.png", bucket="<name>")
→ { url: "https://<bucket>.tos-....bytepluses.com/ref.png" }
# then pass that url in image_urls

git clone https://github.com/mittulmadaan/byteplus-seedream-mcp
cd byteplus-seedream-mcp
pip install packages/seedream-sdk packages/seedream-mcp -e packages/seedream-cli
seedream auth login

# Text-to-image
seedream generate -p "A serene mountain landscape at sunset with golden clouds" \
  --size 2K --output out/

# Seedream 5.0 Lite, 4K
seedream generate -p "Editorial portrait, dramatic studio lighting" \
  --model 5.0-lite --size 4K --output out/

# Editing / reference — local path auto-uploads to TOS
seedream generate -p "Replace the background with a snowy forest. Keep the pose." \
  --ref ./photo.png --bucket my-bucket --output out/

# Consistent multi-panel set
seedream generate -p "A 4-panel comic of a cat's morning, flat pastel style" \
  --sequential -n 4 --output out/

seedream generate \
  --prompt        "..."       # description / edit instruction (required)
  --model         5.0-lite    # 4.5 (default) | 5.0-lite | full model ID
  --size          2K          # 1K* | 2K | 4K | adaptive* | WxH   (*5.0 Lite only)
  --ref           <url|path>  # reference image; repeatable; local paths auto-upload
  --bucket        <name>      # TOS bucket for local --ref uploads
  --seed          42          # reproducible results
  --guidance-scale 7.5        # prompt adherence 1.0–20.0
  --sequential                # generate a consistent multi-panel set
  --num-images    4           # images in a sequential set (refs + n ≤ 15)
  --optimize-prompt           # let the API optimize the prompt
  --watermark                 # add a watermark
  --output        out/        # download the image(s) into this directory

# Auth
seedream auth login           # store credentials interactively
seedream auth check           # verify keys are configured
seedream auth logout

# TOS object storage — upload a LOCAL file, get a public URL
seedream tos buckets                             # list buckets
seedream tos upload ./photo.png --bucket <name>  # upload, prints public URL

# Info
seedream models               # list models, sizes, features
seedream ping                 # verify credentials and connectivity

# Skill management
seedream skill install        # install into Claude Desktop + Claude Code
seedream skill check          # show install status
seedream skill uninstall

git clone https://github.com/mittulmadaan/byteplus-seedream-mcp
cd byteplus-seedream-mcp
pip install packages/seedream-sdk packages/seedream-mcp -e packages/seedream-cli
seedream auth login
seedream skill install        # copies skill file + patches Claude Code settings
# Restart Claude Code

from seedream import SeedreamClient

client = SeedreamClient()  # reads from env vars or ~/.seedream/credentials

# Text-to-image — synchronous, returns URLs directly
result = client.generate(
    prompt="A sunrise over mountains, warm light",
    model="4.5",
    size="2K",
)
print(result.urls)

# Editing with a reference image
result = client.generate(
    prompt="Replace the background with a beach. Keep the subject unchanged.",
    image_urls=["https://example.com/photo.png"],
    model="5.0-lite",
)

# Generate and download to a directory
result = client.generate_and_download(
    "A 4-panel comic of a cat's day", "out/",
    sequential=True, num_images=4,
)
for img in result.images:
    print(img.local_path)

packages/
  seedream-sdk/          # core: HTTP client, TOS HMAC signing, config, types (zero deps)
  seedream-mcp/          # MCP server — thin wrappers over SDK
    docker/              # Dockerfile + docker-compose
  seedream-cli/          # CLI — typer + rich
    seedream_cli/commands/
      auth.py generate.py tos.py models.py skill.py

skills/
  seedream.md            # Claude Code skill definition
  references/            # prompting, editing, sequential sets, models, assets

.github/workflows/
  ci.yml                 # lint + test (Python 3.10 / 3.11 / 3.12)
  release-sdk.yml        # → PyPI on tag sdk/v*
  release-mcp.yml        # → PyPI + Docker Hub on tag mcp/v*
  release-cli.yml        # → PyPI on tag cli/v*

git tag sdk/v1.0.1 && git push --tags   # publishes seedream-sdk to PyPI
git tag mcp/v1.0.1 && git push --tags   # publishes seedream-mcp to PyPI + Docker Hub
git tag cli/v1.0.1 && git push --tags   # publishes seedream-cli to PyPI