# Seedream

Generate AI images with **BytePlus Seedream 4.5** and **Seedream 5.0 Lite** — from your
terminal, your AI client, or Claude Code.

---

## Choose your path

| I want to… | Use |
|---|---|
| Talk to Claude in natural language (Claude Desktop, Cursor, Windsurf) | [MCP Server](#-mcp-server) |
| Generate images from the terminal | [CLI](#-cli) |
| Use slash commands inside Claude Code | [Claude Code Skill](#-claude-code-skill) |

All three share the same credentials and the same underlying pipeline. The Seedream image
API is **synchronous** — a single call returns the finished image URL(s). There is no task
to poll.

---

## Models

| Model | ID | Sizes | Notes |
|---|---|---|---|
| **Seedream 4.5** | `seedream-4-5-251128` | 2K, 4K | Default. **No 1K.** |
| **Seedream 5.0 Lite** | `seedream-5-0-260128` | 1K, 2K, 4K, adaptive | Newer, cheaper, stronger reference consistency & layout reasoning. |

Aliases `4.5` and `5.0-lite` are accepted anywhere a model is specified.

---

## Prerequisites

**Python 3.10+**, a local clone of this repo, and keys from the [BytePlus console](https://console.byteplus.com):

| Key | Where | Used for |
|---|---|---|
| `ARK_API_KEY` | ModelArk → API Keys | Image generation *(required)* |
| `ARK_AK` | IAM → Access Keys | TOS upload of **local** reference images *(optional)* |
| `ARK_SK` | IAM → Access Keys | TOS upload of local reference images *(optional)* |
| `SEEDREAM_TOS_BUCKET` | TOS console → Buckets | Default bucket for uploads *(optional)* |
| `SEEDREAM_TOS_REGION` | — | TOS region, default `ap-southeast-1` *(optional)* |

Plain text-to-image (and references you pass as public URLs) need only `ARK_API_KEY`.

---

## 🖥 MCP Server

Lets Claude Desktop, Cursor, and Windsurf generate images from natural language.

### Setup

```bash
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
```

Then just ask Claude: *"Generate a 4K poster of iced cold brew on a sunlit table with the
headline Summer Cold Brew"*

### Manual config

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or the
equivalent on your OS:

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

Set credentials via environment variables before launching your client.

### Hosted / Docker

```bash
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
```

Your BytePlus credentials stay server-side. Clients connect using `MCP_AUTH_TOKEN` only.
Point your MCP client at `http://your-host:8000/mcp` (streamable HTTP transport).

### How to use

Use `seedream_generate` for everything — it returns image URLs directly:

```
# 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)
```

For a **local** reference image, upload it first:

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

### Available tools

| Tool | Description |
|---|---|
| `seedream_generate` | **Start here.** Text-to-image, editing, reference, sequential sets. Returns URL(s). |
| `seedream_upload_image_to_tos` | Upload a **local** image; returns a public URL. |
| `seedream_list_tos_buckets` | List TOS buckets so Claude can ask which to use. |
| `seedream_list_models` | List models, sizes, and features. |
| `seedream_ping` | Verify credentials and connectivity. |

---

## 💻 CLI

Full-featured terminal interface.

### Setup

```bash
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
```

### Generate an image

```bash
# 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/
```

### All flags

```bash
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
```

### Other commands

```bash
# 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
```

---

## 🧠 Claude Code Skill

Slash commands inside Claude Code, backed by the MCP server.

### Setup

```bash
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
```

The skill lives in [`skills/seedream.md`](skills/seedream.md) with detailed prompting,
editing, and model-selection guidance in [`skills/references/`](skills/references/).

---

## SDK

For building custom integrations:

```python
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)
```

Install: `pip install packages/seedream-sdk` (zero runtime dependencies — stdlib urllib only).

---

## Repo Structure

```
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*
```

---

## Credentials

Resolution order (first non-empty value wins):

1. Constructor args: `SeedreamClient(api_key="...", ak="...", sk="...")`
2. Environment variables: `ARK_API_KEY` (or `BYTEPLUS_API_KEY`), `ARK_AK`, `ARK_SK`
3. `~/.seedream/credentials` — written by `seedream auth login`
4. `.env` file in CWD (requires `python-dotenv`)

> Never embed credentials in client config files or Docker images. Use `MCP_AUTH_TOKEN` to
> protect hosted SSE endpoints.

---

## Release

```bash
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
```

---

## Support

- [BytePlus ModelArk — Seedream 4.0–5.0 tutorial](https://docs.byteplus.com/en/docs/ModelArk/1824121)
- [Image generation API](https://docs.byteplus.com/en/docs/ModelArk/1541523)
- [API key management](https://docs.byteplus.com/en/docs/ModelArk/1361424)

> **Note:** Seedream model IDs may change as BytePlus ships new versions. If a call returns
> an unknown-model error, re-check the docs above and update
> `packages/seedream-sdk/seedream/config.py`.