语音合成 (TTS)Text-to-Speech (TTS)

将文本转换为自然逼真的语音,支持 40+ 种语言、100+ 种音色,包含情绪表达、语速控制和角色扮演等高级特性,满足有声书、客服机器人、智能硬件等多种场景需求。Convert text into natural speech across 40+ languages with 100+ voices. Includes advanced features like emotion, speed control, and role play for audiobooks, customer service bots, and smart devices.

快速概览

Quick Overview

属性Attribute说明Description
合成端点Synthesis EndpointPOST /v1/tts
音色列表端点Voice List EndpointGET /v1/tts/voices
认证AuthenticationBearer Token(Authorization 请求头)Bearer Token in Authorization header
请求体Request Bodyapplication/json(JSON 格式)application/json (JSON format)
文本上限Text Limit单次最多 3000 字符,长文本建议分段或使用流式合成Max 3000 characters per request; chunk or stream for long text
音色数量Voice Count100+ 种音色,覆盖 40+ 种语言100+ voices covering 40+ languages
输出格式Output FormatsMP3 / WAV / OGG / PCMMP3 / WAV / OGG / PCM
高级特性Advanced Features情绪表达、语速/音调控制、音量调节、SSML 标记Emotion, speed/pitch control, volume adjustment, SSML markup

请求端点

Endpoint

POST/v1/tts

认证

Authentication

所有 API 请求需在 HTTP Header 中携带 Access Token。

All API requests must include an Access Token in the HTTP Header.

Authorization: Bearer {access_token}

请求头

Request Headers

请求头Header必填Required说明Description
Authorizationrequired格式 Bearer {access_token},用于身份认证Format: Bearer {access_token}, used for authentication
Content-Typerequired固定为 application/jsonMust be application/json

请求参数

Request Parameters

参数Parameter类型Type必填Required说明Description
textstringrequired待合成文本,单次最大 3000 字符。支持 SSML 标记Text to synthesize, max 3000 chars. Supports SSML
voicestringrequired音色 ID,如 zh-CN-XiaoxiaoNeuralen-US-JennyNeuralVoice ID, e.g. zh-CN-XiaoxiaoNeural, en-US-JennyNeural
speedfloatoptional语速倍率:0.5 ~ 2.0,默认 1.0Speed ratio: 0.5 ~ 2.0; default 1.0
pitchfloatoptional音调调整:-20 ~ 20,默认 0。正值偏高,负值偏低Pitch: -20 ~ 20; default 0. Positive higher, negative lower
volumefloatoptional音量倍率:0.0 ~ 1.0,默认 1.0Volume ratio: 0.0 ~ 1.0; default 1.0
output_formatstringoptional音频格式:mp3 / wav / ogg / pcm,默认 mp3Format: mp3 / wav / ogg / pcm; default mp3
sample_rateintegeroptional采样率:8000 / 16000 / 24000 / 48000 Hz,默认 24000Sample rate: 8000/16000/24000/48000 Hz, default 24000
emotionstringoptional情绪风格:neutral / happy / sad / angry / fearful / disgusted / surprisedEmotion style: neutral / happy / sad / angry / fearful / disgusted / surprised
emotion_intensitystringoptional情绪强度:subtle / normal / strong,默认 normalEmotion intensity: subtle / normal / strong; default normal
rolestringoptional角色扮演:narrator / child / elder / customer_service / news_anchor,需音色支持Role: narrator / child / elder / customer_service / news_anchor; voice must support it
ssmlbooleanoptional是否启用 SSML 解析(支持停顿、发音、强调等标记),默认 falseEnable SSML parsing (pause, pronunciation, emphasis); default false
return_urlbooleanoptional是否返回音频下载 URL(而非直接返回二进制流),默认 falseReturn audio download URL instead of binary stream; default false
callback_urlstringoptional异步回调地址,处理完成后 POST 结果到此 URL。适合长文本Async callback URL, receives POST result upon completion. Best for long text

输出格式对比

Output Format Comparison

格式Format特点Features推荐场景Best For
mp3 体积小、兼容性最好,有损压缩 Small size, best compatibility, lossy compression 网页播放、APP 音频、移动端场景 Web playback, apps, mobile scenarios
wav 无损格式,音质最高,体积较大 Lossless, highest quality, larger size 音频后期处理、专业场景 Audio post-processing, professional use
ogg 开源格式,压缩效率高 Open format, high compression efficiency 游戏、流媒体、HTML5 应用 Games, streaming, HTML5 apps
pcm 原始 PCM 数据,无压缩 Raw PCM data, uncompressed 硬件直连、嵌入式系统、语音对讲 Hardware integration, embedded systems, intercoms

情绪风格说明

Emotion Styles

emotion 参数为语音注入情绪色彩,部分音色支持多种情绪风格。配合 emotion_intensity 可控制情绪的强度。

The emotion parameter adds emotional color to speech. Some voices support multiple styles. Use emotion_intensity to control the strength.

情绪Emotion说明Description典型场景Typical Scenario
neutral中性,自然平和Neutral, natural and calm默认场景,新闻播报、说明性内容Default, news, instructional content
happy开心,愉悦向上Happy, joyful and upbeat促销广告、节日祝福、儿童内容Promotions, greetings, children's content
sad悲伤,低沉缓慢Sad, low and slow有声小说、剧情旁白Audiobooks, narrative scenes
angry生气,急促有力Angry, urgent and forceful戏剧表演、角色配音Drama, character voice-over
fearful恐惧,颤抖紧张Fearful, trembling and tense恐怖故事、惊悚场景Horror, suspense scenes
disgusted厌恶,嫌弃语气Disgusted, repulsed tone戏剧表达、特定角色Dramatic expression, specific roles
surprised惊讶,突兀上扬Surprised, abrupt and rising新闻快讯、互动场景Breaking news, interactive scenarios
💡 情绪支持说明
  • 并非所有音色都支持全部情绪风格,具体支持的 styles 请查看音色列表接口
  • Not all voices support all emotion styles; check the voice list API for supported styles
  • emotion_intensity 仅在指定 emotion 且音色支持时生效
  • emotion_intensity only works when emotion is specified and the voice supports it

请求示例

Request Examples

# 基础用法:中文合成 MP3
curl -X POST https://api.itranslator.cc/v1/tts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "欢迎使用 iTranslator 语音合成服务。",
    "voice": "zh-CN-XiaoxiaoNeural",
    "speed": 1.0,
    "output_format": "mp3"
  }' \
  -o output.mp3

# 带情绪表达:开心风格 + 强度
curl -X POST https://api.itranslator.cc/v1/tts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Great news! Our new product is now available.",
    "voice": "en-US-JennyNeural",
    "emotion": "happy",
    "emotion_intensity": "strong",
    "output_format": "mp3"
  }' \
  -o happy.mp3

# SSML 标记:插入停顿和发音控制
curl -X POST https://api.itranslator.cc/v1/tts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "欢迎来到iTranslator语音合成服务。",
    "voice": "zh-CN-YunxiNeural",
    "ssml": true,
    "output_format": "wav",
    "sample_rate": 24000
  }' \
  -o ssml.wav

# 返回音频 URL(而非二进制流)
curl -X POST https://api.itranslator.cc/v1/tts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This audio will be available via URL.",
    "voice": "en-US-GuyNeural",
    "return_url": true
  }'

响应参数

Response Parameters

默认情况下接口直接返回音频二进制流(Content-Type: audio/mpeg 等对应格式),需以二进制方式保存。当 return_url=true 时返回 JSON:

By default the API returns the audio binary stream (Content-Type: audio/mpeg etc.), which should be saved as binary. When return_url=true, returns JSON:

字段Field类型Type说明Description
audio_urlstring音频文件下载 URL(有效期 24 小时)Audio file download URL (valid 24 hours)
formatstring音频格式:mp3 / wav / ogg / pcmAudio format: mp3 / wav / ogg / pcm
durationnumber音频时长(秒)Audio duration in seconds
sizeinteger音频文件大小(字节)Audio file size in bytes
voicestring使用的音色 IDVoice ID used
billed_charactersinteger计费字符数Number of billed characters

响应示例

Response Example

二进制流模式(默认)

Binary Stream Mode (default)

响应体为音频二进制数据,Content-Typeaudio/mpeg(或对应格式),直接写入文件即可。

Response body is binary audio data with Content-Type as audio/mpeg (or corresponding format). Write directly to file.

URL 返回模式(return_url=true)

URL Return Mode (return_url=true)

{
  "audio_url": "https://cdn.itranslator.cc/tts/abc123.mp3",
  "format": "mp3",
  "duration": 3.2,
  "size": 51200,
  "voice": "zh-CN-XiaoxiaoNeural",
  "billed_characters": 18
}

获取音色列表

Voice List

GET/v1/tts/voices

查询所有可用音色,支持按语言、性别筛选。返回的 styles 字段标识该音色支持的情绪风格列表。

Query all available voices, filterable by language and gender. The styles field indicates supported emotion styles.

查询参数

Query Parameters

参数Parameter类型Type说明Description
languagestringoptional按语言代码筛选,如 zh-CNen-USFilter by language code, e.g. zh-CN, en-US
genderstringoptional按性别筛选:male / femaleFilter by gender: male / female

音色列表响应示例

Voice List Response Example

{
  "voices": [
    {
      "id": "zh-CN-XiaoxiaoNeural",
      "name": "晓晓",
      "gender": "female",
      "language": "zh-CN",
      "styles": ["neutral", "cheerful", "sad", "angry", "fearful"],
      "roles": ["narrator", "child", "customer_service"]
    },
    {
      "id": "zh-CN-YunxiNeural",
      "name": "云希",
      "gender": "male",
      "language": "zh-CN",
      "styles": ["neutral", "newscast", "cheerful"],
      "roles": ["narrator", "news_anchor"]
    },
    {
      "id": "en-US-JennyNeural",
      "name": "Jenny",
      "gender": "female",
      "language": "en-US",
      "styles": ["neutral", "cheerful", "sad"],
      "roles": ["narrator", "customer_service"]
    },
    {
      "id": "en-US-GuyNeural",
      "name": "Guy",
      "gender": "male",
      "language": "en-US",
      "styles": ["neutral", "newscast", "angry"],
      "roles": ["news_anchor", "narrator"]
    }
  ],
  "total": 120
}

SSML 支持

SSML Support

启用 ssml=true 后,text 参数支持 SSML(Speech Synthesis Markup Language)标记,可实现更精细的语音控制:

When ssml=true is enabled, the text parameter supports SSML (Speech Synthesis Markup Language) for fine-grained speech control:

标记Tag说明Description示例Example
<break>插入停顿Insert a pause<break time="500ms"/><break time="500ms"/>
<emphasis>强调某些词Emphasize words<emphasis>重要</emphasis><emphasis>important</emphasis>
<prosody>控制语速/音调/音量Control rate/pitch/volume<prosody rate="slow">慢速</prosody><prosody rate="slow">slow</prosody>
<phoneme>指定发音Specify pronunciation<phoneme alphabet="pinyin" ph="zhōng guó">中国</phoneme><phoneme alphabet="ipa" ph="ˈkæt">cat</phoneme>
<say-as>特殊读法Special reading<say-as interpret-as="digits">123</say-as><say-as interpret-as="digits">123</say-as>
<sub>别名替换Alias substitution<sub alias="人工智能">AI</sub><sub alias="Artificial Intelligence">AI</sub>

错误码

Error Codes

HTTP Code错误码Error Code说明Description
2000成功Success
4001001参数错误,请检查必填参数和参数格式Invalid parameter; check required fields and format
4001002文本超过 3000 字符限制Text exceeds 3000 character limit
4001003音色 ID 不存在或不支持Voice ID does not exist or not supported
4001004音色不支持指定的情绪风格或角色Voice does not support the specified emotion style or role
4001005SSML 格式错误,无法解析Invalid SSML format, cannot parse
4012001认证失败,Token 无效或已过期Authentication failed; invalid or expired token
4032003无权限访问该资源Access denied; insufficient permissions
4133001请求体超出大小限制Request body exceeds size limit
4153002不支持的输出格式Unsupported output format
4294001请求频率超限,请稍后重试Rate limit exceeded; please retry later
4564002套餐配额已用尽,请升级或等待重置Plan quota exhausted; upgrade or wait for reset
5005001服务器处理失败,请重试或联系技术支持Server processing failed; retry or contact support
5035002服务暂时不可用,建议稍后重试Service temporarily unavailable; retry later

最佳实践

Best Practices

  • 选择合适的音色:客服场景选择温柔的女声,新闻播报选择沉稳的男声,有声书选择表现力丰富的音色。
  • Choose the right voice: Gentle female for customer service, calm male for news, expressive voice for audiobooks.
  • 合理使用情绪:情绪风格能显著提升表达力,但过度使用可能显得不自然,建议结合场景适度使用。
  • Use emotions wisely: Emotion styles enhance expressiveness but excessive use may sound unnatural; use moderately based on context.
  • 长文本分段处理:超过 3000 字符的文本需分段调用,建议按句子或段落分割,每段控制在 1000 字以内。
  • Chunk long text: Text exceeding 3000 chars must be chunked; split by sentence or paragraph, keeping each chunk under 1000 chars.
  • SSML 提升表现力:使用 <break> 添加自然停顿,<emphasis> 强调关键词,<prosody> 局部调整语速。
  • Use SSML: Add natural pauses with <break>, emphasize keywords with <emphasis>, locally adjust speed with <prosody>.
  • 采样率选择:网页播放 24kHz 足够,专业音频处理使用 48kHz,电话场景使用 16kHz 或 8kHz。
  • Sample rate: 24kHz for web, 48kHz for professional audio, 16kHz or 8kHz for telephony.
  • 缓存复用:相同文本的合成结果建议缓存,避免重复调用浪费配额。
  • Cache results: Cache synthesis results for the same text to avoid redundant API calls.
  • 安全提醒:请勿在客户端代码中暴露 Access Token,建议通过后端代理调用。
  • Security: Do not expose Access Token in client-side code; use a backend proxy.

应用场景

Use Cases

场景Scenario推荐配置Recommended Config说明Notes
📖 有声书制作 📖 Audiobook Production 表现力音色 + SSML + 情绪 长文本分段合成,结合 SSML 控制停顿和情感,多角色使用不同音色 Chunk long text, use SSML for pauses and emotions, multiple voices for characters
🎧 客服机器人 🎧 Customer Service Bot 温柔女声 + role=customer_service 自然亲切的语气,中性情绪,适中语速 Natural and friendly tone, neutral emotion, moderate speed
📰 新闻播报 📰 News Broadcasting 沉稳男声 + role=news_anchor 专业新闻主播风格,语速适中,清晰准确 Professional anchor style, moderate speed, clear and accurate
🎮 游戏配音 🎮 Game Voice-Over 多音色 + 情绪切换 + OGG 不同角色使用不同音色和情绪,OGG 格式体积小适合游戏 Different voices and emotions per character, OGG for small file size
📢 营销广告 📢 Marketing Ads 热情音色 + emotion=happy 高昂热情的语气,强情绪强度,适合促销和活动 Enthusiastic tone, strong emotion intensity, ideal for promotions
🤖 智能硬件 🤖 Smart Devices PCM 格式 + 16kHz 低延迟 PCM 输出,适合音箱、机器人等嵌入式设备 Low-latency PCM output for smart speakers, robots, and embedded devices
🎓 教育内容 🎓 Educational Content 清晰音色 + speed=0.9 稍慢语速便于学习理解,使用 SSML 标注重点发音 Slightly slower speed for learning, SSML for key pronunciation
使用说明
  • 请求体使用 application/json 格式,需设置 Content-Type: application/json 请求头。
  • Request body uses application/json format; set Content-Type: application/json header.
  • 默认返回音频二进制流,需以二进制方式写入文件。设置 return_url=true 可改为返回下载 URL。
  • By default returns binary audio stream; write as binary. Set return_url=true to get a download URL instead.
  • 长文本建议分段合成或使用异步回调模式,避免请求超时。
  • For long text, use chunked synthesis or async callback mode to avoid timeouts.
  • 请勿在客户端代码中暴露 Access Token,建议通过后端代理调用。
  • Do not expose your Access Token in client-side code; use a backend proxy.