# BytePlus Seed Audio

Generate natural speech and audio with **BytePlus Seed Audio 1.0** — from Claude, the
terminal, or your own code. Three surfaces over one zero-dependency SDK:

| I want to… | Use |
|---|---|
| Talk to Claude / Claude Code | **MCP server** (`seed-mcp`) |
| Generate from the terminal | **CLI** (`seed`) |
| Claude Code skill | **Skill** (`skills/seed.md`) |
| Build my own integration | **SDK** (`seed-sdk`) |

> **Providers:** Seed Audio runs on **two interchangeable backends**, chosen with
> `SEED_PROVIDER`: **BytePlus** (default — the native `voice.ap-southeast-1.bytepluses.com`
> API, synchronous; also works against the Volcengine host via `SEED_BYTEPLUS_TTS_URL`) or
> **fal.ai** (`SEED_PROVIDER=fal`, `bytedance/seed-audio-1.0`, async). The SDK hides the
> wire-format differences behind one interface — the MCP tools, CLI, and skill are identical
> either way. See [`seed/providers/`](packages/seed-sdk/seed/providers/).

## Prerequisites

- **Python 3.10+** and a local clone of this repo.
- Credentials for one provider:
  - **BytePlus** (default): `BYTEPLUS_SEED_API_KEY` (or the legacy `BYTEPLUS_SEED_APP_ID` +
    `BYTEPLUS_SEED_ACCESS_KEY`) — from the BytePlus console (<https://console.byteplus.com/voice/>).
  - **fal.ai** (optional): a `FAL_KEY` (<https://fal.ai/dashboard/keys>), then `SEED_PROVIDER=fal`.

## Install

```bash
git clone https://github.com/mittulmadaan/byteplus-seed-mcp
cd byteplus-seed-mcp

# Install the three packages
pip install ./packages/seed-sdk ./packages/seed-mcp ./packages/seed-cli

# Or, for development (uv workspace):
uv sync --all-packages --dev
```

> Not on PyPI yet — install from the repo. PyPI publishing kicks in on the first
> `sdk/v*` | `mcp/v*` | `cli/v*` release tag (see [Release](#release)).

---

## 🖥 MCP Server

Expose Seed Audio to Claude Desktop / Claude Code.

### Local (stdio)

After installing (above):

```bash
export BYTEPLUS_SEED_API_KEY=<your-byteplus-key>   # default provider
# (or use fal: export FAL_KEY=<key> && export SEED_PROVIDER=fal)
python -m seed_mcp                  # stdio transport (default)
```

Register it with `seed skill install` (below), or add it manually:

```json
{
  "mcpServers": {
    "seed": { "command": "python", "args": ["-m", "seed_mcp"] }
  }
}
```

### Hosted (Docker / SSE)

```bash
docker build -t byteplus-seed-mcp .
docker run -p 8000:8000 \
  -e MCP_TRANSPORT=sse \
  -e SEED_PROVIDER=byteplus \
  -e BYTEPLUS_SEED_API_KEY=<key> \
  -e MCP_AUTH_TOKEN=<strong-random-token> \
  byteplus-seed-mcp
# health: GET http://localhost:8000/health
```

A `render.yaml` is included for one-click Render deployment. Point your MCP client at
`https://<host>/mcp` (streamable HTTP) with a bearer token — credentials stay server-side,
clients authenticate with `MCP_AUTH_TOKEN` only:

```json
{
  "mcpServers": {
    "seed": {
      "type": "http",
      "url": "https://<host>/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}
```

### Tools

| Tool | Purpose |
|---|---|
| `seed_audio_generate` | Submit an audio job → returns `request_id` (or the `audio_url` directly on synchronous providers like BytePlus) |
| `seed_check_task` | Poll until `completed`; returns `audio_url` (fal/async) |
| `seed_list_voices` | List preset voice ids |
| `seed_list_models` | List Seed models + capabilities |
| `seed_ping` | Liveness, active provider, credential check |

---

## 💻 CLI

```bash
seed auth login                      # stores provider keys in ~/.seed/credentials (BytePlus by default)

# Generate
seed generate \
  --prompt "A short suspense radio drama in a late-night convenience store." \
  --watch

# With a preset voice
seed voices                          # list presets
seed generate -p "Welcome back to the late show." -v sophie_en_zh --watch

# Voice cloning from reference audio
seed generate -p "In @Audio1's voice: 'Once upon a time…'" \
  --audio-ref https://cdn.example.com/narrator.mp3 --watch

# Track a job
seed status <request_id>
seed watch  <request_id>

# Skill management (Claude Desktop + Claude Code)
seed skill install
seed skill check
```

Run `seed --help` for the full command reference.

---

## 🧠 Claude Code Skill

`skills/seed.md` (+ `skills/references/`) teaches Claude Code how to use Seed Audio well —
prompting, voice presets, cloning, multi-speaker scenes, and safety.

```bash
seed skill install                   # copies the skill + registers the MCP server
# restart Claude Code, then just ask it to "generate a 20s upbeat intro voiceover"
```

---

## 📦 SDK

```python
from seed import SeedClient

client = SeedClient()                                  # provider from SEED_PROVIDER (default: byteplus)
result = client.submit_audio(
    "A short suspense radio drama in a late-night convenience store.",
    output_format="mp3",
)
# BytePlus is synchronous — `result` is already completed. fal is async, so poll.
import time
while not result.terminal:
    time.sleep(5)
    result = client.check_task(result.request_id)
print(result.audio_url)
```

`seed-sdk` has **zero runtime dependencies** (stdlib `urllib` only).

---

## Repo structure

```
byteplus-seed-mcp/
├── packages/
│   ├── seed-sdk/      # core: client, types, credentials, providers/{fal,byteplus}
│   ├── seed-mcp/      # FastMCP server (5 tools, stdio + SSE)
│   └── seed-cli/      # Typer + Rich CLI, skill installer
├── skills/            # seed.md + references/
├── Dockerfile         # SSE server image
├── render.yaml        # Render.com deployment
└── pyproject.toml     # uv workspace
```

## Credentials

Resolution order (first non-empty wins): explicit arg → env var → `~/.seed/credentials`
`[default]` → `.env`.

| Provider | Env var(s) |
|---|---|
| BytePlus (default, new console) | `BYTEPLUS_SEED_API_KEY` |
| BytePlus (legacy console) | `BYTEPLUS_SEED_APP_ID` + `BYTEPLUS_SEED_ACCESS_KEY` |
| fal (`SEED_PROVIDER=fal`) | `FAL_KEY` |

> Never commit credentials or bake them into images. Protect hosted SSE endpoints with
> `MCP_AUTH_TOKEN`.

## Release

Independent per-package PyPI publishes via tags:

```bash
git tag sdk/v0.1.0 && git push --tags   # → seed-sdk
git tag mcp/v0.1.0 && git push --tags   # → seed-mcp
git tag cli/v0.1.0 && git push --tags   # → seed-cli
```

## Providers

```bash
# BytePlus (default, synchronous — submit returns the audio directly)
export BYTEPLUS_SEED_API_KEY=<key>   # or BYTEPLUS_SEED_APP_ID + BYTEPLUS_SEED_ACCESS_KEY

# fal (opt-in, async)
export FAL_KEY=<key> && export SEED_PROVIDER=fal
```

Voice ids differ between providers (fal presets vs BytePlus `speaker` ids). `seed ping` shows
the active provider and which credentials are configured.

## Roadmap

- [x] Native BytePlus Seed Audio provider (`SEED_PROVIDER=byteplus`)
- [ ] Local-file upload helper (host local audio/images → public URL)
- [ ] Additional Seed models as they ship

## Support

- Repo: <https://github.com/mittulmadaan/byteplus-seed-mcp>
- Seed Audio on fal: <https://fal.ai/models/bytedance/seed-audio-1.0>
- fal queue API: <https://docs.fal.ai/model-endpoints/queue>
- Volcano Engine (BytePlus) Audio Generation API: <https://www.volcengine.com/docs/6561/2550782>