选择模型、音色与输出
请先选择模型：模型决定了可用的音色、控制参数和输出方式。控制台会展示当前项目已经启用的音色和语言。
1. 选择模型
Luna-TTS表达自然、连贯，适合旁白、内容朗读和产品提示音。模型 ID 为
luna-tts。Luna-TTS Character可通过场景控制呈现角色化表达，适合角色配音、游戏台词和陪伴场景。模型 ID 为
luna-tts-character。| 对比项 | Luna-TTS | Luna-TTS Character |
|---|---|---|
| 适用场景 | 旁白、内容朗读、语音提示 | 角色配音、游戏台词、角色陪伴 |
model_id | luna-tts | luna-tts-character |
| 音色 | Luna-TTS 系统音色和克隆音色 | 仅支持 Character 系统音色，不支持克隆音色 |
| 输出 | 完整音频或流式音频 | 仅完整音频 |
省略 model_id 时默认使用 luna-tts。切换模型时，请从对应的音色列表中重新选择 voice_id；系统音色不能跨模型调用。
2. 选择音色与参数
通过 voice_id 指定当前项目已启用的音色。language 请使用当前账号已启用的语言代码。
匹配模型根据
model_id，从 Luna-TTS 或 Character 对应的列表中选择音色。匹配受众使用受众实际会听到的文本，检查语言、口音和表达方式。
按需使用克隆音色克隆音色仅支持 Luna-TTS；Character 只能使用专属系统音色。
保持输出一致效果确认后，复用相同的模型、音色、语言和参数组合。
| 设置 | Luna-TTS | Luna-TTS Character |
|---|---|---|
语速 speed | 0.6–1.2；省略或设为 0 时使用默认语速 | 不支持 |
音量 volume | -5–5 | -5–5 |
说话场景 scene | 不支持 | normal：日常对话（默认）whisper：耳语 |
文本归一化 text_normalization | true 启用归一化（默认）；false 保留输入文本 | 同步 HTTP 接口接受但忽略，建议省略该字段 |
| 表达标签 | 在 text 中直接插入官方标签，例如 [laughs] | 不支持 |
每次只调整一个参数
先用默认参数生成一句具有代表性的文本，下一次请求只修改一个参数。这样更容易判断音色、语速、音量或表达方式带来的差异。
3. 选择输出方式
| 适用场景 | 模型 | 接口 | 响应 |
|---|---|---|---|
| 需要在播放或保存前获得完整文件 | Luna-TTS 或 Luna-TTS Character | POST /v1/text-to-speech | 完整音频字节 |
| 希望在生成过程中尽早开始处理音频 | 仅 Luna-TTS | POST /v1/text-to-speech/stream | HTTP 分块音频 |
两个接口均默认返回 WAV，audio_format 可省略或设为 wav；也均可传 audio_format: "pcm"，获取不含 WAV 容器的有符号 PCM16LE 原始音频，流式仅支持 Luna-TTS。
流式响应是 HTTP 分块音频，不是 SSE 或 JSON 事件流。请按顺序处理响应字节。WAV 包含文件头，需要支持 WAV 的解码器；PCM 则需读取响应中的 X-Audio-Sample-Rate、X-Audio-Channels、X-Audio-Bit-Depth 配置播放器，不能假定固定采样率。详见流式契约与 PCM 示例。
4. 试听与检查
- 使用一段能代表真实产品场景的简短文本开始试听。
- 确认目标语言和口音，并检查人名、数字、缩写、少见符号、停顿和节奏。
- 每次只调整一个参数，并与上一次结果对比。
- 在实际播放环境中检查效果。电话和 IVR 场景需要确认渠道是否接受所选 WAV 或 PCM 格式及其采样率和声道数，必要时先转换音频。
- 效果确认后，将
model_id、voice_id、语言和参数保存为一组配置。