语音合成 (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 Endpoint POST /v1/tts
音色列表端点 Voice List Endpoint GET /v1/tts/voices
认证 Authentication Bearer Token(Authorization 请求头) Bearer Token in Authorization header
请求体 Request Body application/json(JSON 格式)application/json (JSON format)
文本上限 Text Limit 单次最多 3000 字符,长文本建议分段或使用流式合成 Max 3000 characters per request; chunk or stream for long text
音色数量 Voice Count 100+ 种音色,覆盖 40+ 种语言 100+ voices covering 40+ languages
输出格式 Output Formats MP3 / WAV / OGG / PCM MP3 / 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/json Must be application/json
请求参数 Request Parameters
参数 Parameter 类型 Type 必填 Required 说明 Description
text string required 待合成文本,单次最大 3000 字符。支持 SSML 标记 Text to synthesize, max 3000 chars. Supports SSML
voice string required 音色 ID,如 zh-CN-XiaoxiaoNeural、en-US-JennyNeural Voice ID, e.g. zh-CN-XiaoxiaoNeural, en-US-JennyNeural
speed float optional 语速倍率:0.5 ~ 2.0,默认 1.0 Speed ratio: 0.5 ~ 2.0; default 1.0
pitch float optional 音调调整:-20 ~ 20,默认 0。正值偏高,负值偏低 Pitch: -20 ~ 20; default 0. Positive higher, negative lower
volume float optional 音量倍率:0.0 ~ 1.0,默认 1.0 Volume ratio: 0.0 ~ 1.0; default 1.0
output_format string optional 音频格式:mp3 / wav / ogg / pcm,默认 mp3 Format: mp3 / wav / ogg / pcm; default mp3
sample_rate integer optional 采样率:8000 / 16000 / 24000 / 48000 Hz,默认 24000 Sample rate: 8000/16000/24000/48000 Hz, default 24000
emotion string optional 情绪风格:neutral / happy / sad / angry / fearful / disgusted / surprised Emotion style: neutral / happy / sad / angry / fearful / disgusted / surprised
emotion_intensity string optional 情绪强度:subtle / normal / strong,默认 normal Emotion intensity: subtle / normal / strong; default normal
role string optional 角色扮演:narrator / child / elder / customer_service / news_anchor,需音色支持 Role: narrator / child / elder / customer_service / news_anchor; voice must support it
ssml boolean optional 是否启用 SSML 解析(支持停顿、发音、强调等标记),默认 false Enable SSML parsing (pause, pronunciation, emphasis); default false
return_url boolean optional 是否返回音频下载 URL(而非直接返回二进制流),默认 false Return audio download URL instead of binary stream; default false
callback_url string optional 异步回调地址,处理完成后 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
💡 情绪支持说明
💡 Emotion Support
并非所有音色都支持全部情绪风格,具体支持的 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
cURL
Python
JavaScript
Java
Go
# 基础用法:中文合成 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
}'
import requests
token = "YOUR_ACCESS_TOKEN"
url = "https://api.itranslator.cc/v1/tts"
# 基础用法
resp = requests.post(
url,
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
json={
"text": "欢迎使用 iTranslator 语音合成服务。",
"voice": "zh-CN-XiaoxiaoNeural",
"speed": 1.0,
"output_format": "mp3"
}
)
with open("output.mp3", "wb") as f:
f.write(resp.content)
# 高级用法:情绪 + 音量 + SSML
payload = {
"text": "新品发布啦全场八折! ",
"voice": "zh-CN-XiaoxiaoNeural",
"emotion": "happy",
"emotion_intensity": "strong",
"speed": 1.1,
"volume": 0.9,
"ssml": True,
"output_format": "mp3",
"sample_rate": 24000
}
resp = requests.post(
url,
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
json=payload
)
with open("promo.mp3", "wb") as f:
f.write(resp.content)
# 返回 URL 模式
resp = requests.post(
url,
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
json={
"text": "Long text content here...",
"voice": "en-US-JennyNeural",
"return_url": True
}
)
print(f"音频 URL: {resp.json()['audio_url']}")
const axios = require("axios");
const fs = require("fs");
async function synthesizeSpeech() {
// 基础合成:直接获取二进制流
const resp = await axios.post(
"https://api.itranslator.cc/v1/tts",
{
text: "欢迎使用 iTranslator 语音合成服务。",
voice: "zh-CN-XiaoxiaoNeural",
speed: 1.0,
output_format: "mp3"
},
{
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`,
"Content-Type": "application/json"
},
responseType: "arraybuffer"
}
);
fs.writeFileSync("output.mp3", resp.data);
console.log("✅ 音频已保存到 output.mp3");
// 情绪 + SSML 高级合成
const advanced = await axios.post(
"https://api.itranslator.cc/v1/tts",
{
text: "Breaking newsat this hour. ",
voice: "en-US-GuyNeural",
emotion: "surprised",
emotion_intensity: "strong",
ssml: true,
output_format: "wav",
sample_rate: 48000
},
{
headers: {
Authorization: `Bearer ${process.env.API_TOKEN}`,
"Content-Type": "application/json"
},
responseType: "arraybuffer"
}
);
fs.writeFileSync("news.wav", advanced.data);
}
synthesizeSpeech().catch(console.error);
import okhttp3.*;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
public class TTSExample {
public static void main(String[] args) throws IOException {
OkHttpClient client = new OkHttpClient();
String json = "{"
+ "\"text\": \"欢迎使用 iTranslator 语音合成服务。\","
+ "\"voice\": \"zh-CN-XiaoxiaoNeural\","
+ "\"speed\": 1.0,"
+ "\"output_format\": \"mp3\""
+ "}";
RequestBody body = RequestBody.create(json,
MediaType.parse("application/json"));
Request request = new Request.Builder()
.url("https://api.itranslator.cc/v1/tts")
.header("Authorization", "Bearer " + System.getenv("API_TOKEN"))
.header("Content-Type", "application/json")
.post(body)
.build();
try (Response response = client.newCall(request).execute()) {
try (FileOutputStream fos = new FileOutputStream("output.mp3")) {
fos.write(response.body().bytes());
}
System.out.println("✅ 音频已保存到 output.mp3");
}
}
}
package main
import (
"bytes"
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
token := os.Getenv("API_TOKEN")
url := "https://api.itranslator.cc/v1/tts"
payload := strings.NewReader(`{
"text": "欢迎使用 iTranslator 语音合成服务。",
"voice": "zh-CN-XiaoxiaoNeural",
"speed": 1.0,
"output_format": "mp3"
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
out, _ := os.Create("output.mp3")
defer out.Close()
io.Copy(out, resp.Body)
fmt.Println("✅ 音频已保存到 output.mp3")
}
Copy
响应参数 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_url string 音频文件下载 URL(有效期 24 小时) Audio file download URL (valid 24 hours)
format string 音频格式:mp3 / wav / ogg / pcm Audio format: mp3 / wav / ogg / pcm
duration number 音频时长(秒) Audio duration in seconds
size integer 音频文件大小(字节) Audio file size in bytes
voice string 使用的音色 ID Voice ID used
billed_characters integer 计费字符数 Number of billed characters
响应示例 Response Example
二进制流模式(默认) Binary Stream Mode (default)
响应体为音频二进制数据,Content-Type 为 audio/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
language string optional 按语言代码筛选,如 zh-CN、en-US Filter by language code, e.g. zh-CN, en-US
gender string optional 按性别筛选:male / female Filter 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
200 0成功 Success
400 1001参数错误,请检查必填参数和参数格式 Invalid parameter; check required fields and format
400 1002文本超过 3000 字符限制 Text exceeds 3000 character limit
400 1003音色 ID 不存在或不支持 Voice ID does not exist or not supported
400 1004音色不支持指定的情绪风格或角色 Voice does not support the specified emotion style or role
400 1005SSML 格式错误,无法解析 Invalid SSML format, cannot parse
401 2001认证失败,Token 无效或已过期 Authentication failed; invalid or expired token
403 2003无权限访问该资源 Access denied; insufficient permissions
413 3001请求体超出大小限制 Request body exceeds size limit
415 3002不支持的输出格式 Unsupported output format
429 4001请求频率超限,请稍后重试 Rate limit exceeded; please retry later
456 4002套餐配额已用尽,请升级或等待重置 Plan quota exhausted; upgrade or wait for reset
500 5001服务器处理失败,请重试或联系技术支持 Server processing failed; retry or contact support
503 5002服务暂时不可用,建议稍后重试 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
使用说明
Notes
请求体使用 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.