seedaudio-cli

CLI for Volcengine Doubao speech synthesis (豆包语音合成大模型 2.0, seed-tts-2.0), with an accompanying SKILL for Claude Code / AI agents.

It targets the V3 HTTP Chunked unidirectional TTS endpoint (/api/v3/tts/unidirectional): one-shot text in, audio file out. Synthesis is synchronous — there is no task/polling model.

Install

# Recommended:
uv tool install zjandrew-seedaudio-cli

# Or with pipx:
pipx install zjandrew-seedaudio-cli

# Companion SKILL:
npx skills add zjandrew/seedaudio-cli -g -y

The PyPI distribution is named zjandrew-seedaudio-cli; the binary is still seedaudio-cli.

Local development:

git clone https://github.com/zjandrew/seedaudio-cli.git
cd seedaudio-cli
uv sync --all-extras
uv run seedaudio-cli --version

Configure

TTS auth is the 语音技术 console API Key model — a single X-Api-Key, not the Ark ARK_API_KEY Bearer that the video API uses. Get it from 控制台 > API Key 管理.

# Interactive wizard (creates ~/.seedaudio-cli/config.json, chmod 600):
seedaudio-cli config init

# Or env vars:
export SEEDAUDIO_API_KEY=...
export SEEDAUDIO_ENDPOINT=https://openspeech.bytedance.com   # optional

# Or programmatic:
seedaudio-cli config set api_key ...
seedaudio-cli config set default_voice zh_female_vv_uranus_bigtts
# resource_id is auto-inferred from the voice (S_/ICL_/saturn_ -> seed-icl-2.0, else
# seed-tts-2.0); set it only to pin/override globally:
seedaudio-cli config set resource_id seed-icl-2.0           # optional global pin

Priority: CLI flag > env var > config file > built-in default.

Multiple profiles

seedaudio-cli config list
seedaudio-cli config add prod
seedaudio-cli config use prod
seedaudio-cli --profile prod synthesize -p "..."

Usage

# Text → speech (mp3)
seedaudio-cli synthesize -p "你好，欢迎使用豆包语音合成" \
  --voice zh_female_vv_uranus_bigtts --out hello.mp3

# Tune delivery
seedaudio-cli synthesize -p "新闻播报示例" --voice zh_male_liufei_uranus_bigtts \
  --speech-rate 10 --loudness-rate 0 --pitch 0 --encoding wav --sample-rate 24000 --out news.wav

# Emotion / style via voice instruction (context_texts)
seedaudio-cli synthesize -p "今天真是太开心啦" --voice zh_female_vv_uranus_bigtts \
  -m seed-tts-2.0-expressive --instruct "用特别开心、撒娇的语气说" --out happy.mp3

# Long text — the streaming endpoint returns a COMPLETE file in one request, even for
# thousands of chars / minutes of audio, so a whole article or chapter just works:
seedaudio-cli synthesize --text-file chapter1.txt --voice zh_male_xuanyijieshuo_uranus_bigtts --out chapter1.mp3
# (book-length >tens-of-thousands of chars: use Volcengine's async long-text API, not wrapped here)

# Multi-role dialogue: each line `角色: 台词`, mapped to a voice per role
seedaudio-cli dialogue --script play.txt \
  --voice 旁白=zh_male_xuanyijieshuo_uranus_bigtts \
  --voice 小美=zh_female_wenrouxiaoya_uranus_bigtts \
  --instruct 小美="用温柔的语气说" --out play.mp3

# Creative generation (seed-audio-1.0, <=120s): sound effects / reference audio or image.
# Needs the seed-audio-1.0 capability enabled in the console (separate from TTS).
seedaudio-cli create -p "下雨环境音,远处偶尔闷雷,舒缓" --out rain.mp3
seedaudio-cli create -p "用 @音频1 的音色温柔地说:晚安" --ref audio:./sample.wav --out g.mp3
seedaudio-cli create -p "给这个角色配一句台词" --ref image:./char.png --out line.mp3

# Word-level timestamps alongside the audio
seedaudio-cli synthesize -p "字幕对齐示例" --voice zh_female_vv_uranus_bigtts \
  --subtitle --out clip.mp3   # writes clip.mp3 + clip.mp3.words.json

# Discover voices (curated subset; full list in the console)
seedaudio-cli voices --language zh

# Dry run (prints the request body, no API call — works without credentials)
seedaudio-cli --dry-run synthesize -p "..." --voice zh_female_vv_uranus_bigtts

SKILL

skills/seedaudio/SKILL.md ships in this repo. Install for Claude Code:

npx skills add zjandrew/seedaudio-cli -g -y

Exit codes

License

MIT