audiogen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/audiogen — Game Audio Generation via ElevenLabs

/audiogen — 通过 ElevenLabs 生成游戏音频

Generate background music, character voice lines, and sound effects for games via the ElevenLabs REST API. One CLI (

generate.cjs

), three modalities, zero npm deps. Usable both as a Claude Code skill and as a standalone shell CLI (e.g. from CI).

通过 ElevenLabs REST API 为游戏生成背景音乐、角色台词和音效。一个 CLI（

generate.cjs

），三种生成模式，零 npm 依赖。既可作为 Claude Code skill 使用，也可作为独立的 shell CLI（例如在 CI 中使用）。

Prerequisites

前置条件

Node.js >= 20.14 — required for the built-in
```
process.loadEnvFile
```
. The CLI asserts this at entry and fails with a clear message on older Node.
ELEVENLABS_API_KEY
— get one at https://elevenlabs.io/app/settings/api-keys. Either export it in your shell, or add
```
ELEVENLABS_API_KEY=...
```
to a
```
.env
```
file at the project root. The CLI loads every
```
.env
```
in cwd and its parents, then in the script directory and its parents; the nearest file wins for each variable. Shell-exported values take precedence over
.env
values (Node's default; not an audiogen choice).
ElevenLabs plan — any plan works, free or paid. Don't assume which one the user has:
```
plan
```
(below) checks. Only free-plan audio must credit ElevenLabs, and free accounts are limited to
```
--output-format mp3_44100_64
```
. See Licensing.

Node.js >= 20.14 — 内置的
```
process.loadEnvFile
```
所必需。CLI 会在入口处检查此条件，并在 Node 版本较旧时以清晰消息失败。
ELEVENLABS_API_KEY
— 可在 https://elevenlabs.io/app/settings/api-keys 获取。可以将其导出到 shell，或在项目根目录的
```
.env
```
文件中添加
```
ELEVENLABS_API_KEY=...
```
。CLI 会加载 cwd 及其父目录中的所有
```
.env
```
，然后加载脚本目录及其父目录中的所有
```
.env
```
；每个变量均以最近的文件为准。通过 shell 导出的值优先于
.env
中的值（这是 Node 的默认行为，并非 audiogen 的特殊选择）。
ElevenLabs 套餐 — 任何套餐均可，免费或付费。不要假定用户使用的是哪一种：
```
plan
```
（见下文）会进行检查。只有免费套餐生成的音频必须署名 ElevenLabs，且免费账户仅限使用
```
--output-format mp3_44100_64
```
。参见许可。

Quick Start

快速开始

bash

undefined

bash

undefined

Background music — 30 seconds of orchestral tension

背景音乐 — 30 秒的管弦乐紧张氛围

/audiogen music tense orchestral battle cue --length-ms 30000

Voice line — must specify a voice

台词 — 必须指定音色

/audiogen voice "Halt, traveller! What brings you here?" --voice-id Rachel

Sound effect — 2 seconds

音效 — 2 秒

/audiogen sfx heavy wooden door slam with reverb --duration 2

Voice catalog browse

浏览音色目录

/audiogen voices --gender female --language en


Each of these runs the bundled CLI as
`node ${CLAUDE_SKILL_DIR}/generate.cjs <subcommand> ...`. All outputs default
to `assets/audio/{music,voice,sfx}/<slug>.mp3` in the current working
directory.

/audiogen voices --gender female --language en


以上每条命令都会以 `node ${CLAUDE_SKILL_DIR}/generate.cjs <subcommand> ...` 的方式运行内置 CLI。默认情况下，所有输出都会写入当前工作目录中的 `assets/audio/{music,voice,sfx}/<slug>.mp3`。

Handling No Arguments

无参数处理

If the user invokes

/audiogen

with nothing after it, ask what they want to generate before calling the CLI. Don't guess — the three modalities are priced and shaped very differently. A good clarification: "Music (background track), a voice line, or a sound effect? And how long should it be?"

如果用户调用

/audiogen

时没有提供任何后续内容，请先询问他们想生成什么，再调用 CLI。不要猜测——三种生成模式的价格和生成形态差异很大。可以这样澄清：“音乐（背景音轨）、台词，还是音效？时长需要多久？”

Arguments — Subcommand Dispatch

参数——子命令分派

The first positional word is always a subcommand:

/audiogen music|voice|sfx|voices|plan <rest...>

When the user's phrasing makes intent obvious, pick the subcommand yourself:

"boss battle music", "title screen theme", "tavern loop" →
```
music
```
"goblin says ...", "narrator line", "NPC dialogue" →
```
voice
```
"door slam", "coin pickup", "spell cast" →
```
sfx
```
"find a female British voice", "list premade voices" →
```
voices
```

When the phrasing is ambiguous (e.g. "a scream" — voice or sfx?), ask.

voices

is the catalog-browse command, not a generator.

第一个位置参数始终是子命令：

/audiogen music|voice|sfx|voices|plan <rest...>

当用户的表述已明确表达意图时，请自行选择子命令：

“Boss 战音乐”、“标题界面主题”、“酒馆循环” →
```
music
```
“哥布林说……”、“旁白台词”、“NPC 对话” →
```
voice
```
“门砰地关上”、“拾取金币”、“施放法术” →
```
sfx
```
“找一个英国女声”、“列出预制音色” →
```
voices
```

当表述存在歧义时（例如“一声尖叫”——是 voice 还是 sfx？），应询问用户。

voices

是目录浏览命令，而不是生成命令。

Subcommand Reference

子命令参考

music

— background tracks

music

— 背景音轨

/audiogen music <prompt...> [--length-ms MS] [--seed N] [--force-instrumental] [--output-format FMT] [--output PATH]

Generates one music clip via

POST /v1/music

```
--length-ms
```
— 3000–600000. Default
```
30000
```
(30 s). Max 5 minutes.
```
--seed
```
— integer seed for reproducibility.
```
--force-instrumental
```
— suppress vocals.
```
--output-format
```
—
```
mp3_*
```
,
```
pcm_*
```
,
```
opus_*
```
,
```
ulaw_8000
```
,
```
alaw_8000
```
. Default
```
mp3_44100_128
```
. WAV formats (
wav_*
) are rejected — the music endpoint does not accept them.

Loop caveat. There is no native "seamless loop" flag for music. For looping game BGM, loop in the engine / HTML, or build a

composition_plan

(not exposed in this CLI). See Loop Caveat below.

/audiogen music <prompt...> [--length-ms MS] [--seed N] [--force-instrumental] [--output-format FMT] [--output PATH]

通过

POST /v1/music

生成一段音乐。

```
--length-ms
```
— 3000–600000。默认值为
```
30000
```
（30 秒），最长 5 分钟。
```
--seed
```
— 用于实现可复现性的整数种子。
```
--force-instrumental
```
— 禁止人声。
```
--output-format
```
—
```
mp3_*
```
、
```
pcm_*
```
、
```
opus_*
```
、
```
ulaw_8000
```
、
```
alaw_8000
```
。默认值为
```
mp3_44100_128
```
。WAV 格式（
wav_*
）会被拒绝——音乐端点不支持这些格式。

循环注意事项。 音乐没有原生的“无缝循环”标志。要让游戏 BGM 循环播放，请在游戏引擎或 HTML 中实现循环，或创建

composition_plan

（本 CLI 未公开此功能）。参见下文的循环注意事项。

voice

— TTS (text-to-speech)

voice

— TTS（文本转语音）

/audiogen voice <text...> --voice-id <NAME_OR_ID> [--language-code CODE] [--stability N] [--similarity-boost N] [--style N] [--speed N] [--model-id ID] [--seed N] [--output-format FMT] [--output PATH]

Generates one TTS clip via

POST /v1/text-to-speech/{voice_id}

```
--voice-id
```
— required. Accepts either an exact voice name from the local cache (case-insensitive), or a 20-char alphanumeric voice ID. If the name isn't cached, fall back to
```
audiogen voices <query>
```
to discover one.
Input cap: 40,000 characters (enforced client-side).
```
--model-id
```
— default
```
eleven_multilingual_v2
```
. Others:
```
eleven_flash_v2_5
```
(fast/cheap),
```
eleven_turbo_v2_5
```
,
```
eleven_v3
```
(expressive — best for emotional lines).

--stability

--similarity-boost

--style

--speed

— all optional

voice_settings

fields. Ranges 0–1 except

--speed

(0.5–2).

```
--output-format
```
— includes
```
wav_*
```
in addition to the usual set (WAV is supported for TTS but not for music or sfx).

通过

POST /v1/text-to-speech/{voice_id}

生成一段 TTS 音频。

```
--voice-id
```
— 必填。接受本地缓存中完全匹配的音色名称（不区分大小写），或 20 位字母数字 voice ID。如果名称未缓存，则回退使用
```
audiogen voices <query>
```
查找。
输入上限：40,000 个字符（在客户端强制执行）。
```
--model-id
```
— 默认为
```
eleven_multilingual_v2
```
。其他选项包括：
```
eleven_flash_v2_5
```
（快速且经济）、
```
eleven_turbo_v2_5
```
、
```
eleven_v3
```
（表现力强，最适合富有情感色彩的台词）。
```
--stability
```
、
```
--similarity-boost
```
、
```
--style
```
、
```
--speed
```
— 均为可选的
```
voice_settings
```
字段。除
```
--speed
```
的范围为 0.5–2 外，其余字段的范围均为 0–1。
```
--output-format
```
— 除常用格式外还支持
```
wav_*
```
（TTS 支持 WAV，但音乐和 sfx 不支持）。

sfx

— sound effects

sfx

— 音效

/audiogen sfx <prompt...> [--duration N] [--loop] [--prompt-influence N] [--output-format FMT] [--output PATH]

Generates one sound effect via

POST /v1/sound-generation

```
--duration
```
— 0.5 to 30 seconds. Optional — omit to let the API auto-pick a duration. The 30-second ceiling is a hard API limit; for longer ambience, generate a loopable clip and repeat in-engine.
```
--loop
```
— native API flag (requires the
```
eleven_text_to_sound_v2
```
model, which is the default). Produces a seamlessly loopable waveform.
```
--prompt-influence
```
— 0–1. Default
```
0.3
```
. Higher = closer adherence to the prompt; lower = more creative latitude.

--output-format

—

mp3_*

pcm_*

opus_*

ulaw_*

alaw_*

. WAV rejected, same as music.

/audiogen sfx <prompt...> [--duration N] [--loop] [--prompt-influence N] [--output-format FMT] [--output PATH]

通过

POST /v1/sound-generation

生成一段音效。

```
--duration
```
— 0.5 至 30 秒。此参数为可选项；省略时由 API 自动选择时长。30 秒上限是 API 的硬性限制；如果需要更长的环境音，请生成可循环片段并在引擎中重复播放。
```
--loop
```
— 原生 API 标志，要求使用
```
eleven_text_to_sound_v2
```
模型，该模型为默认模型。可生成首尾匹配、能够在引擎中无缝重复的波形。
```
--prompt-influence
```
— 0–1。默认值为
```
0.3
```
。数值越高，结果越严格遵循提示词；数值越低，创作自由度越高。
```
--output-format
```
—
```
mp3_*
```
、
```
pcm_*
```
、
```
opus_*
```
、
```
ulaw_*
```
、
```
alaw_*
```
。WAV 会被拒绝，与音乐端点相同。

voices

— browse the voice catalog

voices

— 浏览音色目录

/audiogen voices [query...] [--accent STR] [--gender male|female] [--language CODE] [--category STR] [--limit N] [--page-size N] [--json] [--refresh]

Lists voices from

GET /v2/voices

with client-side filters. Results are cached at

.audiogen-voices.json

in the project root with a 24-hour TTL; stale caches are refreshed automatically. Use

--refresh

to force a re-fetch.

```
query
```
(optional positional) — substring match on voice name, description, and labels.
```
--accent
```
— substring match on accent labels (e.g.
```
british
```
,
```
american
```
).
```
--gender
```
—
```
male
```
or
```
female
```
.
```
--language
```
— ISO code (
```
en
```
,
```
ja
```
,
```
es
```
, …).
```
--category
```
— e.g.
```
premade
```
,
```
cloned
```
,
```
professional
```
.
```
--limit
```
— cap the number of rows in the table view (default 50).
```
--json
```
ignores this.
```
--json
```
— emit raw JSON for scripting; table view otherwise.

The cache file is gitignored. It is not a source of truth — the ElevenLabs catalog is — but is the canonical resolver for

--voice-id <name>

/audiogen voices [query...] [--accent STR] [--gender male|female] [--language CODE] [--category STR] [--limit N] [--page-size N] [--json] [--refresh]

通过

GET /v2/voices

列出音色，并在客户端进行筛选。结果会缓存在项目根目录的

.audiogen-voices.json

中，TTL 为 24 小时；缓存过期后会自动刷新。使用

--refresh

可强制重新获取。

```
query
```
（可选位置参数）— 对音色名称、描述和标签进行子字符串匹配。
```
--accent
```
— 对口音标签进行子字符串匹配，例如
```
british
```
、
```
american
```
。
```
--gender
```
—
```
male
```
或
```
female
```
。
```
--language
```
— ISO 代码，例如
```
en
```
、
```
ja
```
、
```
es
```
。
```
--category
```
— 例如
```
premade
```
、
```
cloned
```
、
```
professional
```
。
```
--limit
```
— 限制表格视图中显示的行数，默认值为 50。使用
```
--json
```
时忽略此限制。
```
--json
```
— 输出原始 JSON 以供脚本处理；否则显示表格视图。

缓存文件已加入 gitignore。它不是事实来源——ElevenLabs 目录才是事实来源——但它是解析

--voice-id <name>

的标准依据。

plan

— which ElevenLabs plan this key is on

plan

— 当前 API 密钥对应的 ElevenLabs 套餐

/audiogen plan

Reads

GET /v1/user/subscription

and prints one JSON line, for example

{"plan":"free","creditRequired":true,"creditsLeft":9900,"creditLimit":10000}

plan

free

, a paid plan's name (

starter

creator

pro

, …), or

unknown

when the key isn't allowed to read the account (keys can be limited to generation) or ElevenLabs can't be reached. It costs no credits. Run it once before the first generation in a session; see Licensing for what to do with the answer.

/audiogen plan

读取

GET /v1/user/subscription

并打印一行 JSON，例如：

{"plan":"free","creditRequired":true,"creditsLeft":9900,"creditLimit":10000}

当密钥无权读取账户信息（密钥可能仅被限制用于生成），或无法连接 ElevenLabs 时，

plan

的值为

unknown

。此命令不消耗 credits。请在一次会话首次生成前运行一次；具体处理方式参见许可。

How to Compose Prompts

如何编写提示词

Music and SFX prompts are free-form natural language. Write like you are briefing a human foley artist or composer:

Be specific about instrumentation, tempo, mood. "Sorrowful string quartet, 60 BPM, dry room tone" beats "sad music."
Name the genre or era. "NES chiptune", "Sega Genesis FM synthesis", "1950s noir jazz combo" all land recognizably.
Describe the scene. "Heavy iron portcullis slamming shut in a stone corridor, long reverb tail" beats "door sound."
Stack adjectives for SFX. The model responds well to three or four descriptors chained ("crunchy, wet, low-frequency, metallic").

For quick starting points, see ${CLAUDE_SKILL_DIR}/reference.md
— it contains ~20 music presets, ~15 voice archetypes, and ~25 SFX presets. Presets are templates, not literal prompts: expand them with any additional cues from the user's phrasing.

音乐和 SFX 提示词采用自由形式的自然语言。编写方式应像是在向人类 foley 艺术家或作曲家说明需求：

明确说明乐器配置、速度和情绪。“悲伤的四重奏，60 BPM，干燥的室内底噪”优于“悲伤的音乐”。
注明流派或时代。“NES chiptune”、“Sega Genesis FM synthesis”、“1950s noir jazz combo”都能产生辨识度鲜明的效果。
描述场景。“沉重的铁闸门在石质走廊中猛然落下，带有长时间混响尾音”优于“门的声音”。
**为 SFX 叠加多个形容词。**模型对三到四个串联的描述词反应良好，例如“酥脆、湿、低频、金属感”。

如需快速上手，请参阅 ${CLAUDE_SKILL_DIR}/reference.md
——其中包含约 20 个音乐预设、约 15 种音色原型和约 25 个 SFX 预设。预设只是模板，并非必须逐字使用的提示词；应根据用户的表述进行扩展并补充相关线索。

Choosing a Voice

如何选择音色

If the user names a voice ("use Rachel", "use JBFqn..."), pass that to
```
--voice-id
```
directly. 20-char alphanumeric strings are treated as IDs; anything else is matched against the cache by name (case-insensitive).
If the user describes what they want ("gruff old wizard", "young American female"), run
```
/audiogen voices <query>
```
first — possibly with
```
--gender
```
,
```
--accent
```
, or
```
--language
```
. Pick a candidate by name, then call
```
voice
```
with that name.
The voice cache auto-refreshes after 24 hours. Use
```
--refresh
```
if the user says "new voices were added" or you hit a "voice not found" error.
See
```
${CLAUDE_SKILL_DIR}/reference.md
```
for archetype-to-search-query guidance (e.g. "Arcane Scholar →
```
voices wise old male english
```
").

如果用户指定了音色（“使用 Rachel”、“使用 JBFqn...”），请直接将其传给
```
--voice-id
```
。20 位字母数字字符串会被视为 ID；其他内容则按名称与缓存进行不区分大小写的匹配。
如果用户描述了所需效果（“粗犷的老巫师”、“年轻的美国女性”），请先运行
```
/audiogen voices <query>
```
，并根据需要添加
```
--gender
```
、
```
--accent
```
或
```
--language
```
。选择一个候选音色名称后，再使用该名称调用
```
voice
```
。
音色缓存会在 24 小时后自动刷新。如果用户表示“新增了音色”，或者遇到“voice not found”错误，请使用
```
--refresh
```
。
有关音色原型到搜索查询的对应关系，请参阅
```
${CLAUDE_SKILL_DIR}/reference.md
```
，例如“Arcane Scholar →
```
voices wise old male english
```
”。

Output Organization

输出组织方式

Default layout in the current working directory:

assets/audio/
  music/   — background tracks
  voice/   — TTS lines
  sfx/     — sound effects

Filename is derived from the prompt (lowercased, non-alphanumerics collapsed to
```
-
```
, first 40 chars). Non-Latin prompts fall back to
```
audio-YYYYMMDD-HHMMSS
```
.
Auto-versioning on collision. If
```
assets/audio/music/foo.mp3
```
exists, the next call becomes
```
foo-v2.mp3
```
, then
```
-v3
```
, up to
```
-v999
```
. Pass
```
--force
```
to overwrite in place.
--output PATH
overrides everything:
- If
```
PATH
```
  is an existing directory (or ends with
```
/
```
  ), the slug is written inside it.
- Otherwise
```
PATH
```
  is the literal output filename (auto-versioning still applies unless
```
--force
```
  ).

Filenames are a collision-avoidance mechanism, not a version manifest. If the user wants to track iterations ("go back to v1", "that was better than v2"), use

--history-parent <id>

against

.audiogen-history.jsonl

— see Regeneration & Iteration.

当前工作目录中的默认布局：

assets/audio/
  music/   — 背景音轨
  voice/   — TTS 台词
  sfx/     — 音效

文件名根据提示词生成（转为小写，非字母数字字符合并为
```
-
```
，最多取前 40 个字符）。如果提示词不包含拉丁字母，则回退使用
```
audio-YYYYMMDD-HHMMSS
```
。
**发生冲突时自动添加版本号。**如果
```
assets/audio/music/foo.mp3
```
已存在，下一次调用将生成
```
foo-v2.mp3
```
，随后为
```
-v3
```
，最多可到
```
-v999
```
。传入
```
--force
```
可直接覆盖原文件。
--output PATH
会覆盖上述所有规则：
- 如果
```
PATH
```
  是现有目录或以
```
/
```
  结尾，则在目录内写入采用 slug 规则生成的文件名。
- 否则，
```
PATH
```
  会被视为完整输出文件名（除非指定
```
--force
```
  ，否则仍会执行自动版本控制）。

文件名仅用于避免冲突，并不充当版本清单。如果用户需要跟踪迭代过程（例如“回到 v1”、“v2 更好”），请对
.audiogen-history.jsonl
使用
--history-parent <id>
——参见重新生成与迭代。

Confirmation Policy

确认策略

Single generation: run without asking. The user asked for one thing; deliver it.
Batch of 3+ generations in one turn: before starting, quote the estimated cost (see Cost) and confirm. Example: "That's 5 music clips at ~$0.15 each = ~$0.75. OK to proceed?"
Voice cloning (IVC/PVC) is out of scope — ElevenLabs requires explicit consent-recording workflows that belong in their UI, not a CLI. Direct the user to https://elevenlabs.io/voice-lab.

**单次生成：**直接执行，无需询问。用户只要求生成一样内容；交付结果即可。
一轮中批量生成 3 个或更多内容：开始前，引用预计费用（参见费用）并请求确认。例如：“这将生成 5 段音乐，每段约 $0.15，总计约 $0.75。可以继续吗？”
音色克隆（IVC/PVC）不在支持范围内——ElevenLabs 要求采用明确的同意录音流程，而这些流程应由其 UI 提供，而非 CLI。将用户引导至 https://elevenlabs.io/voice-lab。

Handling Errors

错误处理

The CLI prints every failure as

audiogen: <message>

on stderr and exits 1. Common patterns:

401 / 402 — API key invalid, out of credits, or tier restriction. Check the key and billing page.
422 with
output_format
in the detail — the free plan's format limit, so the account is on the free plan. The CLI appends the hint "Free-tier accounts are restricted to
```
mp3_44100_64
```
. Try
```
--output-format mp3_44100_64
```
."
422 other — prompt rejected (content policy, unsupported parameter combo, …). Refine the prompt and retry.
429 — concurrency limit hit (Free 2, Creator 5, Pro 10, Business 15). The CLI retries 3x with backoff; after that, the user should wait or upgrade.
empty audio response
— a 200 with zero bytes; the CLI deletes the empty file and reports. Refine the prompt and retry.
voice not found
/ duplicate name — the cache has no match, or two cached voices share a name. The error lists the candidate IDs; pass one directly via
```
--voice-id <ID>
```
.

Every error block includes the HTTP status and, when available, the

xi-request-id

header — include that when filing issues with ElevenLabs support.

CLI 会将所有失败以

audiogen: <message>

的形式输出到 stderr，并以状态码 1 退出。常见模式包括：

401 / 402 — API 密钥无效、credits 不足或套餐受限。请检查密钥和账单页面。
422，且详情中包含
output_format
— 免费套餐存在格式限制，说明账户使用的是免费套餐。CLI 会附加提示：“免费套餐账户仅支持
```
mp3_44100_64
```
。请尝试
```
--output-format mp3_44100_64
```
。”
其他 422 — 提示词被拒绝（内容策略、不受支持的参数组合等）。请优化提示词后重试。
429 — 达到并发限制（Free 为 2，Creator 为 5，Pro 为 10，Business 为 15）。CLI 会进行 3 次退避重试；之后用户应等待一段时间或升级套餐。
empty audio response
— 返回 200，但响应包含零字节。CLI 会删除空文件并报告错误。请优化提示词后重试。
voice not found
/ 重复名称 — 缓存中没有匹配项，或两个缓存音色名称相同。错误信息会列出候选 ID；请通过
```
--voice-id <ID>
```
直接传入其中一个。

每个错误块都包含 HTTP 状态，并在可获取时包含

xi-request-id

header——联系 ElevenLabs 支持团队时请一并提供该信息。

Regeneration & Iteration

重新生成与迭代

Every successful generation appends one JSON line to

.audiogen-history.jsonl

in the working directory. Schema:

{ts, id, parent_id?, type, prompt, model_id, output_path,
 output_format, request_body, request_id?, audiogenVersion}

```
--history-id ID
```
— tag a generation with an explicit id (otherwise the CLI auto-generates one from the output path).
```
--history-parent ID
```
— mark this generation as a derivative of a prior record. Use for "make that goblin voice gruffer", "same track with more brass", etc.

History-file write failures are logged to stderr but never abort the generation — you got the audio, the bookkeeping is best-effort.

每次成功生成都会向工作目录中的

.audiogen-history.jsonl

追加一行 JSON。Schema 如下：

{ts, id, parent_id?, type, prompt, model_id, output_path,
 output_format, request_body, request_id?, audiogenVersion}

```
--history-id ID
```
— 为生成任务指定明确的 ID；否则 CLI 会根据输出路径自动生成一个 ID。
```
--history-parent ID
```
— 将本次生成标记为此前记录的衍生版本。可用于“让那个哥布林的声音更粗犷”、“同一首曲子加入更多铜管”等场景。

历史文件写入失败会记录到 stderr，但绝不会中止生成——音频已经生成，记录工作仅采用尽力而为的方式。

Loop Caveat

循环注意事项

Music has no native loop flag. Generate the track, then loop in the game engine or HTML
```
<audio loop>
```
. For a natively seamless loop, you need to craft a
```
composition_plan
```
(not exposed in this CLI — use the raw ElevenLabs API or their web UI).
SFX has native
--loop
on the default
```
eleven_text_to_sound_v2
```
model. Produces a clip with matching start/end so it can repeat seamlessly in-engine.

**音乐没有原生循环标志。**先生成音轨，然后在游戏引擎或 HTML
```
<audio loop>
```
中循环播放。若要生成原生无缝循环，需要编写
```
composition_plan
```
（本 CLI 未公开此功能——请使用原始 ElevenLabs API 或其 Web UI）。
默认的
```
eleven_text_to_sound_v2
```
模型支持 SFX 原生
```
--loop
```
，可生成首尾匹配、能够在引擎中无缝重复的片段。

Cost

费用

The live pricing page at https://elevenlabs.io/pricing/api is authoritative — the numbers below may lag. Approximate API-tier rates as of April 2026:

Music: ~$0.30 per minute of output.
TTS: Flash / Turbo ~$0.05 per 1,000 characters; Multilingual v2 and v3 ~$0.10 per 1,000 characters.
SFX: ~$0.12 per generation, flat (1 second and 30 seconds cost the same).
Free tier: 10,000 credits/month — roughly 60 minutes of Flash TTS, or a handful of SFX.

Consult

${CLAUDE_SKILL_DIR}/reference.md

for a detailed cost table and worked examples. When in doubt, quote from the live page, not from this file.

**实时定价页面 https://elevenlabs.io/pricing/api 是权威依据——以下数字可能滞后。**截至 2026 年 4 月，各 API 套餐的大致费率如下：

**音乐：**每分钟输出约 $0.30。
**TTS：**Flash / Turbo 每 1,000 个字符约 $0.05；Multilingual v2 和 v3 每 1,000 个字符约 $0.10。
**SFX：**每次生成约 $0.12，采用统一计费（生成 1 秒和 30 秒的费用相同）。
**免费套餐：**每月 10,000 credits——约相当于 60 分钟的 Flash TTS，或少量 SFX。

有关详细费用表和计算示例，请参阅

${CLAUDE_SKILL_DIR}/reference.md

。如有疑问，请以实时页面为准，而不是以本文档为准。

Licensing

许可

Paid-plan output — user-owned, with perpetual commercial rights that survive account cancellation. No credit needed.
Free-plan output — commercial use permitted, but it must credit ElevenLabs per their terms.

Go by what

plan

reports, never by guessing:

```
free
```
— generate with
```
--output-format mp3_44100_64
```
(the only format free accounts get), and tell the user once that the audio needs a credit, such as "Music and sound effects created with ElevenLabs." in their credits or README.
a paid plan — say nothing about credits.
```
unknown
```
— generate normally. If the default
```
mp3_44100_128
```
works, it's a paid plan: no credit. If it fails with the free-tier
```
output_format
```
hint, it's the free plan: retry with
```
--output-format mp3_44100_64
```
and mention the credit as above. If nothing gets generated, don't bring up credits.

When audiogen runs for another skill that has its own credit rule, such as gamegen, follow that skill's rule for where the credit goes.

Voice cloning (IVC / PVC) — requires explicit, recorded consent from the voice owner. NEVER clone a public figure's voice. Cloning flows live in the ElevenLabs UI; this skill does not expose them.

付费套餐输出 — 归用户所有，并包含永久商业使用权，该权利在账户取消后仍然有效。无需署名。
免费套餐输出 — 允许商业使用，但必须按照 ElevenLabs 的条款署名 ElevenLabs。

始终以

plan

的结果为准，不要进行猜测：

```
free
```
— 使用
```
--output-format mp3_44100_64
```
生成（这是免费账户唯一可用的格式），并一次性告知用户音频需要署名，例如在 credits 或 README 中写明“Music and sound effects created with ElevenLabs.”。
付费套餐 — 不要提及署名要求。
```
unknown
```
— 正常生成。如果默认的
```
mp3_44100_128
```
可用，则说明这是付费套餐，无需署名。如果因免费套餐的
```
output_format
```
提示而失败，则说明这是免费套餐：请使用
```
--output-format mp3_44100_64
```
重试，并按上述方式提及署名要求。如果没有生成任何内容，则不要提及署名要求。

当 audiogen 被另一个具有独立署名规则的 skill（例如 gamegen）调用时，署名位置应遵循该 skill 的规则。

音色克隆（IVC / PVC） — 必须获得音色所有者的明确录音同意。**绝不克隆公众人物的声音。**克隆流程位于 ElevenLabs UI 中，本 skill 未公开相关功能。

Key Rules

关键规则

NEVER clone a public figure's voice — it is TOS-forbidden and legally hazardous.
ALWAYS require explicit, recorded consent before cloning a real person's voice (IVC or PVC). Direct users to the ElevenLabs UI — this CLI does not implement cloning.
NEVER pass
```
wav_*
```
formats to
```
music
```
or
```
sfx
```
— the API rejects them. TTS accepts WAV.
NEVER call
```
sfx
```
without a text prompt — the endpoint will return 400.
ALWAYS keep SFX durations in
```
[0.5, 30]
```
— the 30 s ceiling is a hard API limit.
ALWAYS quote estimated cost before a batch of 3+ generations.
ALWAYS treat filenames (
```
-v2
```
,
```
-v3
```
, …) as collision avoidance, not a version manifest. Use
```
--history-parent
```
for genuine iteration threading.
NEVER edit
```
.audiogen-history.jsonl
```
by hand — it is append-only.

绝不克隆公众人物的声音——这违反 TOS，并存在法律风险。
克隆真人的声音（IVC 或 PVC）前，始终要求获得明确且已录音的同意。将用户引导至 ElevenLabs UI——本 CLI 未实现克隆功能。
向
```
music
```
或
```
sfx
```
传入
```
wav_*
```
格式时，绝不执行——API 会拒绝这些格式。TTS 支持 WAV。
未提供文本提示词时，绝不调用
```
sfx
```
——端点将返回 400。
SFX 时长应始终保持在
```
[0.5, 30]
```
范围内——30 秒上限是 API 的硬性限制。
批量生成 3 个或更多内容前，始终引用预计费用。
始终将文件名（
```
-v2
```
、
```
-v3
```
等）视为避免冲突的机制，而不是版本清单。真正的迭代关联应使用
```
--history-parent
```
。
绝不手动编辑
```
.audiogen-history.jsonl
```
——该文件只能追加内容。

Edge Cases

边缘情况

Free-tier 422 with
output_format
— the CLI appends a hint suggesting
```
--output-format mp3_44100_64
```
. Follow it; it also means the account is on the free plan (see Licensing).
Music loops — no native API flag. Use engine-side looping or craft a
```
composition_plan
```
out-of-band.
Duplicate voice names — the cache may contain two "Adam"s (e.g. a premade and a cloned one).
```
--voice-id Adam
```
will fail with a disambiguation error listing both IDs; retry with an ID.
20-char voice name — if a cached voice happens to have a 20-char alphanumeric name, the CLI treats it as an ID (passthrough). A warning is written to stderr. Rename the voice in ElevenLabs or pass the real ID.
0-byte 200 response — the CLI deletes the empty file and reports
```
"empty audio response; refine prompt or retry."
```
. Treat as transient; refine and retry.
Non-Latin prompts — the slug function strips non-
```
[a-z0-9]
```
characters; if nothing is left, the filename falls back to
```
audio-YYYYMMDD-HHMMSS
```
(local time zone).
Stale voice cache — cache is 24 h; pass
```
--refresh
```
if a newly-added voice is not found.
.env
precedence — shell-exported
```
ELEVENLABS_API_KEY
```
wins over any
```
.env
```
value (Node's default). Unset shell variable if you want the
```
.env
```
value to take effect.

免费套餐返回包含
output_format
的 422 — CLI 会附加建议使用
```
--output-format mp3_44100_64
```
的提示。请遵循该提示；这也意味着账户使用的是免费套餐（参见许可）。
音乐循环 — 没有原生 API 标志。请使用引擎侧循环，或在 CLI 之外编写
```
composition_plan
```
。
重复音色名称 — 缓存中可能存在两个“Adam”（例如一个预制、一个克隆）。
```
--voice-id Adam
```
将触发消歧错误并列出两个 ID；请改用 ID 重试。
20 位音色名称 — 如果某个缓存音色恰好具有 20 位字母数字名称，CLI 会将其视为 ID 并直接传递，同时向 stderr 写入警告。请在 ElevenLabs 中重命名该音色，或传入真正的 ID。
200 响应包含 0 字节 — CLI 会删除空文件并报告
```
"empty audio response; refine prompt or retry."
```
。请将其视为暂时性错误，优化提示词后重试。
非拉丁字母提示词 — slug 函数会移除非
```
[a-z0-9]
```
字符；如果没有剩余字符，文件名将回退为
```
audio-YYYYMMDD-HHMMSS
```
（使用本地时区）。
音色缓存过期 — 缓存有效期为 24 小时；如果找不到新增音色，请传入
```
--refresh
```
。
.env
优先级 — 通过 shell 导出的
```
ELEVENLABS_API_KEY
```
优先于任何
```
.env
```
值（Node 的默认行为）。如果希望使用
```
.env
```
中的值，请取消设置 shell 环境变量。

Script Location

脚本位置

The CLI is bundled next to this

SKILL.md

, at

${CLAUDE_SKILL_DIR}/generate.cjs

. That path works whether the skill was installed as a plugin or copied into a skills folder. It is dual-shape: as a skill backend (invoked via this SKILL.md), and as a standalone CLI. Run it directly from any shell for scripting, CI, or manual experimentation:

node ${CLAUDE_SKILL_DIR}/generate.cjs music "chiptune boss" \
  --length-ms 45000

All flags work identically in both modes. Run

--help

for the authoritative flag surface; this file is prose,

generate.cjs --help

is canon.

CLI 与此

SKILL.md

放在一起，位于

${CLAUDE_SKILL_DIR}/generate.cjs

。无论该 skill 是作为插件安装，还是被复制到 skills 文件夹中，此路径均可使用。它具有双重形态：既可作为由本

SKILL.md

调用的 skill 后端，也可作为独立 CLI。你可以在任意 shell 中直接运行它，用于脚本、CI 或手动实验：

node ${CLAUDE_SKILL_DIR}/generate.cjs music "chiptune boss" \
  --length-ms 45000

两种模式下的所有 flag 均完全相同。运行

--help

可获取权威的 flag 列表；本文档仅为说明，

generate.cjs --help

才是权威依据。