ChatTTS 语音合成API接口文档

模型介绍

ChatTTS 是一款专为实时对话场景深度定制的语音生成（TTS）模型。不同于传统朗读型模型，ChatTTS 旨在解决 AI 交互中的自然语音合成问题。

模型基于约 10 万小时的高质量中英文混合数据进行训练，具备极强的韵律感与表现力。它能够完美支持中文与英文的混合合成，为对话机器人、虚拟数字人及音视频内容创作提供高度拟人、流畅自然的语音输出能力。

基础信息

请求头

请求参数

公共参数

参数详细说明

input

• 类型：字符串
• 必填：是
• 说明：要转换为语音的文本内容
• 示例："今天天气真好，适合出去游玩"

prompt

• 类型：字符串
• 必填：否
• 默认值：[oral_1]
• 说明：ChatTTS 的提示词参数，用于控制语音的语调和风格
• 可选值：
  • [oral_1] - 默认口语风格
  • [oral_2] - 另一种口语风格
  • [oral_3] - 正式风格
  • 数字格式如 1、2、3 会自动转换为 [oral_1]、[oral_2]、[oral_3]

temperature

• 类型：浮点数
• 必填：否
• 默认值：0.2
• 范围：0.0 - 1.0
• 说明：控制生成结果的随机性，值越小越稳定，值越大越随机

top_P

• 类型：浮点数
• 必填：否
• 默认值：0.7
• 范围：0.0 - 1.0
• 说明：Nucleus 采样参数，值越高词汇选择范围越广

top_K

• 类型：整数
• 必填：否
• 默认值：20
• 范围：大于 0
• 说明：Top-K 采样参数，从概率最高的 K 个词中采样

voice

• 类型：字符串
• 必填：否
• 说明：指定使用某个预设音色

voice_url

• 类型：字符串 (URL)
• 必填：否
• 说明：自定义音色参考音频的 URL 地址

skip_refine

• 类型：整数
• 必填：否
• 默认值：0
• 说明：是否跳过文本优化步骤，1 表示跳过，0 表示不跳过

custom_voice

• 类型：整数
• 必填：否
• 默认值：0
• 说明：是否使用自定义音色，1 表示使用，0 表示不使用

请求示例

cURL 请求

curl -X POST 'https://www.yuntts.com/api/v1/chattts_generate' 
  -H 'Content-Type: application/json' 
  -H 'Authorization: Bearer YOUR_API_KEY' 
  -d '{
    "input": "今天天气真好，适合出去游玩",
    "prompt": "[oral_1]",
    "temperature": "0.2",
    "top_P": "0.7",
    "top_K": "20",
    "skip_refine": "0",
    "custom_voice": "0"
  }'

JavaScript 请求

async function synthesizeSpeech() {
    const apiKey = 'YOUR_API_KEY';
    const inputText = '今天天气真好，适合出去游玩';

    const response = await fetch('https://www.yuntts.com/api/v1/chattts_generate', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${apiKey}`
        },
        body: JSON.stringify({
            input: inputText,
            prompt: '[oral_1]',
            temperature: 0.2,
            top_P: 0.7,
            top_K: 20,
            skip_refine: 0,
            custom_voice: 0
        })
    });

    const data = await response.json();
    console.log(data);
}

Python 请求

import requests

url = 'https://www.yuntts.com/api/v1/chattts_generate'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
}
data = {
    'input': '今天天气真好，适合出去游玩',
    'prompt': '[oral_1]',
    'temperature': 0.2,
    'top_P': 0.7,
    'top_K': 20,
    'skip_refine': 0,
    'custom_voice': 0
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

返回数据

成功返回

成功返回示例

{
    "code": 200,
    "message": "语音合成成功",
    "data": {
        "task_id": "chtts_abc123def456",
        "audio_url": "https://your-domain.com/uploads/abc123.mp3",
        "char_count": 12,
        "cost": 0.03,
        "balance": 99.97
    }
}

失败返回

失败返回示例

{
    "code": 403,
    "error": "insufficient_balance",
    "message": "余额不足，需要0.03元，当前余额0元"
}

状态码说明

计费说明

计费方式

• 计费类型：按次计费（不是按字符数）
• 基础费率：0.03 元/次
• 最低扣费：0.01 元

折扣说明

费用计算示例

• 普通用户：0.03 元/次
• VIP 用户：0.03 × 0.9 = 0.027 元/次
• SVIP 用户：0.03 × 0.8 = 0.024 元/次

余额不足处理

当用户余额小于所需费用时，接口会返回 403 错误，不会扣除任何费用。

扣费失败处理

当扣费失败时，接口会返回 500 错误，不会扣除任何费用。

错误处理建议

常见错误及解决方案

1. 余额不足 (403)

{
    "code": 403,
    "error": "insufficient_balance",
    "message": "余额不足，需要0.03元，当前余额0元"
}

解决方案：请充值后再试。

2. API 密钥无效 (401)

{
    "code": 401,
    "error": "invalid_key",
    "message": "通过API密钥查询用户失败"
}

解决方案：检查 API Key 是否正确，或重新生成 API Key。

3. 缺少必要参数 (400)

{
    "code": 400,
    "error": "invalid_parameters",
    "message": "缺少必要参数：input"
}

解决方案：确保请求中包含 input 参数。

4. 网络超时 (500)

{
    "code": 500,
    "error": "api_request_failed",
    "message": "语音合成失败：cURL error 28: Resolving timed out..."
}

解决方案：

1. 检查网络连接
2. 稍后重试
3. 联系服务器管理员检查 DNS 配置

音频文件说明

音频格式

• 格式：MP3
• 采样率：根据 API 返回

音频有效期

• 请在 24 小时内下载，过期后可能自动清理

下载方式

1. 直接访问返回的 audio_url 下载

版本历史

注意事项

1. 字符限制：单次请求的文本长度建议不超过实际限制
2. 并发限制：请勿过于频繁请求，以免触发 API 限流
3. 余额检查：建议在请求前检查用户余额
4. 错误重试：建议实现错误重试机制
5. HTTPS：生产环境建议使用 HTTPS