Communitygithub.com

TTS文本转语音技能

使用 z-ai-web-dev-sdk 实现文本转语音(TTS)功能。当用户需要将文本转换为自然语音、创建音频内容、构建语音应用或生成语音音频文件时使用。支持多种语音、可调速度及多种音频格式。

TTS文本转语音技能 是什么?

TTS(文本转语音)技能基于 z-ai-web-dev-sdk 包,提供将文本转换为自然语音音频的能力,并集成到 AI 助手工作流中。它支持多种语音(如 tongtong、chuichui、xiaochen 等)、可调速度(0.5 至 2.0)和输出格式(WAV、MP3、PCM),满足从简单转换到复杂音频生成的各种场景。该技能只能在后端代码中使用,并受输入字符数(最多 1024 字符)和流式传输限制(流式时仅支持 PCM)等约束。它为开发者提供了借助 CLI 快速测试和利用 SDK 的编程方法。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AiCurv/ADBCommander/tree/HEAD/skills/TTS

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

TTS(文本转语音)技能

本技能指导如何使用 z-ai-web-dev-sdk 包实现文本转语音(TTS)功能,将文本转换为自然语音音频。

技能路径

技能位置:{project_path}/skills/TTS

本技能位于您项目中的以上路径。

参考脚本:测试示例脚本位于 {技能位置}/scripts/ 目录下,供快速测试和参考。请参见 {技能位置}/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 "你好,世界" --output ./hello.wav

# 使用短选项
z-ai tts -i "你好,世界" -o ./hello.wav

不同语音和速度

# 使用特定语音
z-ai tts -i "欢迎使用我们的服务" -o ./welcome.wav --voice tongtong

# 调整语速(0.5-2.0)
z-ai tts -i "这是较快语速" -o ./fast.wav --speed 1.5

# 较慢语速
z-ai tts -i "这是较慢语速" -o ./slow.wav --speed 0.8

不同输出格式

# MP3 格式
z-ai tts -i "你好,世界" -o ./hello.mp3 --format mp3

# WAV 格式(默认)
z-ai tts -i "你好,世界" -o ./hello.wav --format wav

# PCM 格式
z-ai tts -i "你好,世界" -o ./hello.pcm --format pcm

流式输出

# 流式音频生成
z-ai tts -i "这是一段较长的文本,将进行流式传输" -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('你好,世界!', './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('欢迎使用我们的服务', '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('这是一项重要公告', 0.8, './slow.wav');

// 使用 - 较快叙述
await generateWithSpeed('快速更新', 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('这是一项公告', 5.0, './loud.wav');

// 使用 - 较小音量
await generateWithVolume('悄声消息', 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 = [
  '欢迎来到第一章',
  '欢迎来到第二章',
  '欢迎来到第三章'
];

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(
  '你好,这是一项测试',
  './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({ ... });

常见用例

  1. 有声书与播客:将书写内容转换为音频格式
  2. 电子学习:为教育内容创建旁白
  3. 可访问性:提供文本内容的音频版本
  4. 语音助手:生成动态回复
  5. 公告:创建自动语音通知
  6. IVR 系统:生成电话系统提示
  7. 内容本地化:创建不同语言的音频

集成示例

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 });
  }
}

// ... (后续内容已省略)

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

AiCurv/ADBCommander

Generate a single-file Chinese atelier-style portfolio website (horizontal-row list + hover-reveal thumb interaction, art lishu typography "Alimama DaoLiTi" via CDN, light/dark theme, hash-routed detail pages). Takes a natural-language description of the studio (name, director, discipline, works) and outputs ONE working .html file. Runs in BOTH Claude Code (writes to ~/Desktop) and GLM / online chat (outputs HTML inline). Trigger phrases include "做个中式工作室作品集", "做个隶书作品集", "lishu-portfolio-gen ...", "做个白屋风格的作品集", or when user drags this skill folder into chat asking for an atelier-style site.

AiCurv/ADBCommander

Premium calm-tech SaaS landing template — bilingual (CN/EN) literary voice over a dark forest-night palette with warm gold accent, Cormorant + Noto Serif SC, Three.js procedural forest hero, station-based scrolling narrative, custom cursor. Built for ambient-AI / creative-tool / philosophical SaaS, not loud commercial launch.

AiCurv/ADBCommander

Pro-camera HUD mockup template — full-viewport black canvas wrapping a real video with monospace overlays (corner brackets, top status bar, side AF/exposure columns, bottom timecode + aperture/shutter/ISO row, vertical 8-filter wheel, animated reticle). For cinematographer portfolios, camera-app demos, LUT pack previews, filter-look auditions. NOT a TikTok/Reels mockup, NOT a storyboard, NOT a shot list, NOT a script document. The chrome wraps real footage — never a div placeholder.

AiCurv/ADBCommander

Premium pre-launch waitlist page template — dark charcoal canvas with subtle vignette, drifting portrait video-thumbnail cards, fade-up cascades, glass nav, live-updating join counter, single email form with success/error states. Built for creative-tool / AI / niche-SaaS invite-only launches with hushed exclusive tone, not loud growth-marketing.

AiCurv/ADBCommander

Route design-related HTML artifact tasks to the right artifact skill, reference, design system generation, or export skill.

AiCurv/ADBCommander

Implement AI-powered video generation capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to generate videos from text prompts or images, create video content programmatically, or build applications that produce video outputs. Supports asynchronous task management with status polling and result retrieval.

AiCurv/ADBCommander

Implement specialized video understanding capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to analyze video content, understand motion and temporal sequences, extract information from video frames, describe video scenes, or perform video-based AI analysis. Optimized for MP4, AVI, MOV, and other common video formats.

相关技能