Fish Audio TTS API​

Fish Audio TTS 提供同步文本转语音（Text-to-Speech）与即时语音克隆能力。调用 POST /v1/tts，传入文本和语音模型，直接返回二进制音频流，无需轮询。

开始前请准备：

1. 在 控制台 创建 API Key。
2. 确认当前账号可用的模型（s2.1-pro、s2-pro、s1 等）。
3. 所有请求发送到当前平台地址：https://art-api.yuyuflow.com。

鉴权​

本接口使用 API Key 鉴权：

Authorization: Bearer YOUR_API_KEY

请在 https://art-api.yuyuflow.com/dashboard/overview 获取 API Key。

请求​

POST https://art-api.yuyuflow.com/v1/tts

Headers​

Body 参数​

请求体支持 JSON 或 MessagePack 编码，两种编码接受相同字段。请求体原样透传到上游，所有 Fish Audio 原生字段均保留。

text string 必选

要合成的文本。支持情绪标记、音素控制标签和多说话人对话标记（见高级特性）。

reference_id string | string[] 可选

语音模型 ID。传入后在对应语音模型上合成。

• 单说话人：传字符串，如 "9a9cf47702da476aa4629e2506d4a857"。
• 多说话人对话：传数组，配合 text 中的 <|speaker:N|> 标记切换说话人，N 从 0 开始对应数组下标。

在 控制台 的 Voice Library 中查找已有模型 ID，或通过语音克隆创建新模型。

references object[] 可选

零样本即时克隆的参考音频。无需预先训练模型，直接传入一段 10～30 秒的干净音频及其转写文本即可。

每个元素结构：

prosody object 可选

韵律控制，调整语速和音量。

format string 可选

输出音频格式，默认 mp3。

latency string 可选

延迟与稳定性权衡。

chunk_length integer 可选

文本分块长度，控制引擎在开始生成前批量处理多少文本。默认 200，取值范围 100～300。较小的值首音频更快，较大的值对长文本更高效。

temperature number 可选

采样温度。较低值（如 0.7）输出更确定，较高值更随机。

top_p number 可选

核采样参数，与 temperature 配合控制生成多样性。

repetition_penalty number 可选

重复惩罚系数。大于 1.0 抑制重复声音，默认约 1.2。

max_new_tokens integer 可选

每个分块生成的最大音频 token 数，用于限制单次生成的音频长度。

normalize boolean 可选

是否自动展开数字和日期为自然读法。设为 true 时 "2024" 读作"二零二四"而非"两千零二十四"。

mp3_bitrate integer 可选

MP3 比特率，单位 kbps，可选 64 / 128 / 192。仅在 format=mp3 时生效。

sample_rate integer 可选

采样率，如 44100。仅在 format=wav 或 pcm 时生效。

opus_bitrate integer 可选

Opus 比特率，自动模式为 -1000。仅在 format=opus 时生效。

响应​

成功（200）​

直接返回二进制音频字节流，Content-Type 由上游根据 format 决定（如 audio/mpeg、audio/wav 等）。响应头原样透传。

将响应体写入文件即可得到音频文件：

curl ... --output output.mp3

错误​

非 200 状态码返回 JSON 错误体：

{
  "status": "error",
  "message": "text is required",
  "reason": "..."
}

示例​

基础文本转语音​

curl -X POST "https://art-api.yuyuflow.com/v1/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "model: s2.1-pro" \
  -d '{"text":"你好世界，欢迎使用语音合成。","format":"mp3"}' \
  --output output.mp3

指定语音模型​

curl -X POST "https://art-api.yuyuflow.com/v1/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "model: s2.1-pro" \
  -d '{"text":"这段文字将使用指定语音模型朗读。","reference_id":"YOUR_VOICE_MODEL_ID","format":"mp3"}' \
  --output output.mp3

多说话人对话​

用 <|speaker:N|> 标记切换说话人，reference_id 传数组，N 对应数组下标（从 0 开始）：

curl -X POST "https://art-api.yuyuflow.com/v1/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "model: s2.1-pro" \
  -d '{"text":"<|speaker:0|>你好！今天天气真好。<|speaker:1|>是啊，非常适合出门散步。","reference_id":["VOICE_ID_A","VOICE_ID_B"],"format":"mp3"}' \
  --output dialog.mp3

指定输出格式与采样率​

curl -X POST "https://art-api.yuyuflow.com/v1/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "model: s2.1-pro" \
  -d '{"text":"高质量无损音频输出。","reference_id":"YOUR_VOICE_MODEL_ID","format":"wav","sample_rate":44100}' \
  --output output.wav

韵律控制（加速朗读）​

curl -X POST "https://art-api.yuyuflow.com/v1/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "model: s2.1-pro" \
  -d '{"text":"这段语音将以 1.5 倍速朗读。","reference_id":"YOUR_VOICE_MODEL_ID","prosody":{"speed":1.5}}' \
  --output output.mp3

低延迟配置​

curl -X POST "https://art-api.yuyuflow.com/v1/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "model: s2.1-pro" \
  -d '{"text":"快速响应输出。","reference_id":"YOUR_VOICE_MODEL_ID","latency":"balanced","chunk_length":150}' \
  --output output.mp3

零样本即时克隆（msgpack）​

零样本克隆无需预先训练模型，直接传入一段 10～30 秒的干净参考音频及其转写文本即可。由于 references 包含二进制音频数据，需用 MessagePack 编码请求体。

Python 示例（ormsgpack + httpx）​

import os
import httpx
import ormsgpack

# 读取参考音频文件（建议 10~30 秒，干净人声）
with open("sample.wav", "rb") as f:
    audio_bytes = f.read()

payload = {
    "text": "这段语音将模仿参考音频的声音朗读。",
    "references": [
        {
            "audio": audio_bytes,
            "text": "这是参考音频对应的转写文本。",
        }
    ],
    "format": "mp3",
}

resp = httpx.post(
    "https://art-api.yuyuflow.com/v1/tts",
    content=ormsgpack.packb(payload),
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
        "Content-Type": "application/msgpack",
        "model": "s2.1-pro",
    },
    timeout=60,
)

with open("cloned_output.mp3", "wb") as f:
    f.write(resp.content)

print(f"已保存克隆语音，状态码: {resp.status_code}")

pip install httpx ormsgpack

同时使用 reference_id 和 references​

可以既指定已训练的 reference_id，又传入 references 做即时微调。具体行为以 Fish Audio 官方文档为准。

高级特性​

情绪控制​

在 text 中插入标记控制语音情绪和语气。不同模型语法不同：

常用情绪标记：

S2 系列还支持自然语言描述（不限于固定标签），如 [warm and happy]。多个标记可叠加：[sad][whispering] 我很想你。

音素控制​

用 <|phoneme_start|> 和 <|phoneme_end|> 标签手动指定多音字或专有名词的读音：

请把这个词读作<|phoneme_start|>hang2<|phoneme_end|>。

中文音素使用带声调数字的拼音（tone3 pinyin），声调 1～5 分别对应阴平、阳平、上声、去声、轻声。

数字与日期自然读法​

设置 normalize: true 自动展开数字和日期：

{
  "text": "今天是 2024 年 12 月 25 日，温度 23 度。",
  "normalize": true
}

模型列表​

常见问题​

• 请求返回 text is required：确认 body 中 text 字段非空。即使使用 msgpack 编码，text 字段也必须存在。
• 请求返回模型不存在或路由失败：确认 model 在请求头而非 body 里。未传 model 头时默认 s2.1-pro。
• 多说话人只有一个人的声音：确认 reference_id 传的是数组（["id_a","id_b"]），且 text 中的 <|speaker:N|> 下标与数组对应。
• 即时克隆效果差：使用 10～30 秒干净人声样本，避免背景噪音。参考音频的 text 转写要准确，直接影响克隆质量。
• msgpack 请求报解码错误：确认 Content-Type 设为 application/msgpack，且 body 是合法的 MessagePack 编码。JSON 编码无法传输二进制 audio bytes 字段。
• 情绪标记没有效果：S2 系列用 [方括号]，S1 用 (圆括号)，两者不可混用。情绪标记建议放在句首。
• 大文本生成慢：减小 chunk_length（如 150）可加快首音频，或设 latency: "balanced"。

继续阅读​

• Seedance 视频生成接入指南
• 生成视频 API：完整参数和模型能力
• 素材库 Python SDK：素材入库与真人认证