TTS(文本转语音)技能 是做什么的?
此技能指导使用 z-ai-web-dev-sdk 包实现文本转语音(TTS)功能,可将文本转换为自然的语音音频。
技能路径
技能位置:{project_path}/skills/TTS
该技能位于项目中的上述路径。
参考脚本:示例测试脚本位于 {Skill Location}/scripts/ 目录中,用于快速测试和参考。请参阅 {Skill Location}/scripts/tts.ts 获取工作示例。
概述
文本转语音允许您构建应用程序,从文本输入生成语音音频,支持各种语音、速度和输出格式,适用于多种用例。
重要提示:z-ai-web-dev-sdk 必须仅在后台代码中使用。切勿在客户端代码中使用。
API 限制与约束
在实现 TTS 功能之前,请注意以下重要限制:
输入文本约束
- 最大长度:每次请求 1024 个字符
- 超过此限制的文本必须拆分为较小的块
音频参数
- 速度范围:0.5 到 2.0
- 0.5 = 半速(较慢)
- 1.0 = 正常速度(默认)
- 2.0 = 双倍速度(较快)
- 音量范围:大于 0,最高 10
- 默认值:1.0
- 值必须大于 0(不包含)且不超过 10(包含)
格式与流
- 流式限制:当启用
stream: true时,仅支持pcm格式 - 非流式:支持
wav、pcm和mp3格式 - 采样率:24000 Hz(推荐)
长文本最佳实践
function splitTextIntoChunks(text, maxLength = 1000) {
const chunks = [];
const sentences = text.match(/[^.!?]+[.!?]+/g) || [text];
let currentChunk = '';
for (const sentence of sentences) {
if ((currentChunk + sentence).length <= maxLength) {
currentChunk += sentence;
} else {
if (currentChunk) chunks.push(currentChunk.trim());
currentChunk = sentence;
}
}
if (currentChunk) chunks.push(currentChunk.trim());
return chunks;
}
前提条件
z-ai-web-dev-sdk 包已安装。请按以下示例所示导入。
CLI 用法(用于简单任务)
对于简单的文本转语音转换,您可以使用 z-ai CLI 代替编写代码。这非常适合快速音频生成、测试语音或简单自动化。
基本 TTS
# 将文本转换为语音(默认 WAV 格式)
z-ai tts --input "Hello, world" --output ./hello.wav
# 使用短选项
z-ai tts -i "Hello, world" -o ./hello.wav
不同语音和速度
# 使用特定语音
z-ai tts -i "Welcome to our service" -o ./welcome.wav --voice tongtong
# 调整语音速度(0.5-2.0)
z-ai tts -i "This is faster speech" -o ./fast.wav --speed 1.5
# 慢速语音
z-ai tts -i "This is slower speech" -o ./slow.wav --speed 0.8
不同输出格式
# MP3 格式
z-ai tts -i "Hello World" -o ./hello.mp3 --format mp3
# WAV 格式(默认)
z-ai tts -i "Hello World" -o ./hello.wav --format wav
# PCM 格式
z-ai tts -i "Hello World" -o ./hello.pcm --format pcm
流式输出
# 流式音频生成
z-ai tts -i "This is a longer text that will be streamed" -o ./stream.wav --stream
CLI 参数
--input, -i <text>:必需 - 要转换为语音的文本(最多 1024 个字符)--output, -o <path>:必需 - 输出音频文件路径--voice, -v <voice>:可选 - 语音类型(默认:tongtong)--speed, -s <number>:可选 - 语音速度,0.5-2.0(默认:1.0)--format, -f <format>:可选 - 输出格式:wav、mp3、pcm(默认:wav)--stream:可选 - 启用流式输出(仅支持 pcm 格式)
何时使用 CLI 与 SDK
CLI 适用于:
- 快速文本转语音转换
- 测试不同的语音和速度
- 简单的批量音频生成
- 命令行自动化脚本
SDK 适用于:
- 应用程序中的动态音频生成
- 与 Web 服务集成
- 自定义音频处理管道
- 具有复杂需求的生产级应用程序
基本 TTS 实现
简单文本转语音
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function textToSpeech(text, outputPath) {
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// 从 Response 对象获取数组缓冲区
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
console.log(`音频已保存至 ${outputPath}`);
return outputPath;
}
// 使用示例
await textToSpeech('Hello, world!', './output.wav');
多种语音选项
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithVoice(text, voice, outputPath) {
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: voice, // 可用语音:tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
speed: 1.0,
response_format: 'wav',
stream: false
});
// 从 Response 对象获取数组缓冲区
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// 使用示例
await generateWithVoice('Welcome to our service', 'tongtong', './welcome.wav');
可调速度
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithSpeed(text, speed, outputPath) {
const zai = await ZAI.create();
// 速度范围:0.5 到 2.0(API 约束)
// 0.5 = 半速(较慢)
// 1.0 = 正常速度(默认)
// 2.0 = 双倍速度(较快)
// 超出此范围的值将导致 API 错误
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: speed,
response_format: 'wav',
stream: false
});
// 从 Response 对象获取数组缓冲区
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// 使用示例 - 较慢的叙述
await generateWithSpeed('This is an important announcement', 0.8, './slow.wav');
// 使用示例 - 较快的叙述
await generateWithSpeed('Quick update', 1.3, './fast.wav');
可调音量
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithVolume(text, volume, outputPath) {
const zai = await ZAI.create();
// 音量范围:大于 0,最高 10(API 约束)
// 值必须 > 0(不包含)且 <= 10(包含)
// 默认值:1.0(正常音量)
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
volume: volume, // 可选参数
response_format: 'wav',
stream: false
});
// 从 Response 对象获取数组缓冲区
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// 使用示例 - 更大声
await generateWithVolume('This is an announcement', 5.0, './loud.wav');
// 使用示例 - 更安静
await generateWithVolume('Whispered message', 0.5, './quiet.wav');
高级用例
批量处理
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
async function batchTextToSpeech(textArray, outputDir) {
const zai = await ZAI.create();
const results = [];
// 确保输出目录存在
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
for (let i = 0; i < textArray.length; i++) {
try {
const text = textArray[i];
const outputPath = path.join(outputDir, `audio_${i + 1}.wav`);
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// 从 Response 对象获取数组缓冲区
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
results.push({
success: true,
text,
path: outputPath
});
} catch (error) {
results.push({
success: false,
text: textArray[i],
error: error.message
});
}
}
return results;
}
// 使用示例
const texts = [
'Welcome to chapter one',
'Welcome to chapter two',
'Welcome to chapter three'
];
const results = await batchTextToSpeech(texts, './audio-output');
console.log('已生成:', results.length, '个音频文件');
动态内容生成
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
class TTSGenerator {
constructor() {
this.zai = null;
}
async initialize() {
this.zai = await ZAI.create();
}
async generateAudio(text, options = {}) {
const {
voice = 'tongtong',
speed = 1.0,
format = 'wav'
} = options;
const response = await this.zai.audio.tts.create({
input: text,
voice: voice,
speed: speed,
response_format: format,
stream: false
});
// 从 Response 对象获取数组缓冲区
const arrayBuffer = await response.arrayBuffer();
return Buffer.from(new Uint8Array(arrayBuffer));
}
async saveAudio(text, outputPath, options = {}) {
const buffer = await this.generateAudio(text, options);
if (buffer) {
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
return null;
}
}
// 使用示例
const generator = new TTSGenerator();
await generator.initialize();
await generator.saveAudio(
'Hello, this is a test',
'./output.wav',
{ speed: 1.2 }
);
Next.js API 路由示例
import { NextRequest, NextResponse } from 'next/server';
export async function POST(req: NextRequest) {
try {
const { text, voice = 'tongtong', speed = 1.0 } = await req.json();
// 导入 ZAI SDK
const ZAI = (await import('z-ai-web-dev-sdk')).default;
// 创建 SDK 实例
const zai = await ZAI.create();
// 生成 TTS 音频
const response = await zai.audio.tts.create({
input: text.trim(),
voice: voice,
speed: speed,
response_format: 'wav',
stream: false,
});
// 从 Response 对象获取数组缓冲区
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
// 返回音频作为响应
return new NextResponse(buffer, {
status: 200,
headers: {
'Content-Type': 'audio/wav',
'Content-Length': buffer.length.toString(),
'Cache-Control': 'no-cache',
},
});
} catch (error) {
console.error('TTS API 错误:', error);
return NextResponse.json(
{
error: error instanceof Error ? error.message : '生成语音失败,请稍后重试',
},
{ status: 500 }
);
}
}
最佳实践
1. 文本准备
function prepareTextForTTS(text) {
// 移除多余空白
text = text.replace(/\s+/g, ' ').trim();
// 扩展常见缩写以改善发音
const abbreviations = {
'Dr.': 'Doctor',
'Mr.': 'Mister',
'Mrs.': 'Misses',
'etc.': 'et cetera'
};
for (const [abbr, full] of Object.entries(abbreviations)) {
text = text.replace(new RegExp(abbr, 'g'), full);
}
return text;
}
2. 错误处理
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function safeTTS(text, outputPath) {
try {
// 验证输入
if (!text || text.trim().length === 0) {
throw new Error('文本输入不能为空');
}
if (text.length > 1024) {
throw new Error('文本输入超过最大长度 1024 个字符');
}
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// 从 Response 对象获取数组缓冲区
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return {
success: true,
path: outputPath,
size: buffer.length
};
} catch (error) {
console.error('TTS 错误:', error);
return {
success: false,
error: error.message
};
}
}
3. SDK 实例复用
import ZAI from 'z-ai-web-dev-sdk';
// 创建单例
let zaiInstance = null;
async function getZAIInstance() {
if (!zaiInstance) {
zaiInstance = await ZAI.create();
}
return zaiInstance;
}
// 使用示例
const zai = await getZAIInstance();
const response = await zai.audio.tts.create({ ... });
常见用例
- 有声读物与播客:将书面内容转换为音频格式
- 电子学习:为教育内容创建旁白
- 无障碍功能:提供文本内容的音频版本
- 语音助手:生成动态响应
- 公告系统:创建自动化音频通知
- IVR 系统:生成电话系统提示音
- 内容本地化:创建不同语言的音频
集成示例
Express.js API 端点
import express from 'express';
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
const app = express();
app.use(express.json());
let zaiInstance;
const outputDir = './audio-output';
async function initZAI() {
zaiInstance = await ZAI.create();
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
}
initZAI();
app.post('/tts', async (req, res) => {
try {
const { text, voice = 'tongtong', speed = 1.0, format = 'wav' } = req.body;
if (!text || text.trim().length === 0) {
return res.status(400).json({ error: '文本输入不能为空' });
}
if (text.length > 1024) {
return res.status(400).json({ error: '文本输入超过最大长度 1024 个字符' });
}
const filename = `tts-${Date.now()}.${format}`;
const outputPath = path.join(outputDir, filename);
const response = await zaiInstance.audio.tts.create({
input: text,
voice: voice,
speed: speed,
response_format: format,
stream: false
});
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
res.json({
success: true,
filename: filename,
path: outputPath,
size: buffer.length
});
} catch (error) {
console.error('TTS 错误:', error);
res.status(500).json({ error: '生成语音失败' });
}
});
app.get('/tts/:filename', (req, res) => {
const filePath = path.join(outputDir, req.params.filename);
if (fs.existsSync(filePath)) {
res.sendFile(filePath);
} else {
res.status(404).json({ error: '文件未找到' });
}
});
app.listen(3000, () => {
console.log('TTS 服务运行在端口 3000');
});
WebSocket 实时音频流
import WebSocket from 'ws';
import ZAI from 'z-ai-web-dev-sdk';
const wss = new WebSocket.Server({ port: 8080 });
wss.on('connection', (ws) => {
console.log('客户端已连接');
ws.on('message', async (message) => {
try {
const { text, voice = 'tongtong', speed = 1.0 } = JSON.parse(message);
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: voice,
speed: speed,
response_format: 'pcm', // 流式必须使用 pcm
stream: true
});
// 使用 ReadableStream 处理流式响应
const reader = response.body.getReader();
while (true) {
const { done, value } = await reader.read();
if (done) break;
// 将音频块发送给客户端
ws.send(value);
}
ws.send(JSON.stringify({ type: 'end' }));
} catch (error) {
ws.send(JSON.stringify({ type: 'error', message: error.message }));
}
});
ws.on('close', () => {
console.log('客户端已断开连接');
});
});
console.log('WebSocket 服务器运行在 ws://localhost:8080');