Was macht TTS (Text-to-Speech) Skill?
Diese Skill führt die Implementierung der Text-to-Speech (TTS)-Funktionalität mit dem z-ai-web-dev-sdk-Paket durch und ermöglicht die Umwandlung von Text in natürlich klingende Sprachaudioausgaben.
Skills-Pfad
Skill-Speicherort: {project_path}/skills/TTS
Diese Skill befindet sich unter dem oben genannten Pfad in Ihrem Projekt.
Referenzskripte: Beispieltestskripte sind im Verzeichnis {Skill Location}/scripts/ für schnelles Testen und als Referenz verfügbar. Siehe {Skill Location}/scripts/tts.ts für ein funktionierendes Beispiel.
Übersicht
Text-to-Speech ermöglicht es Ihnen, Anwendungen zu erstellen, die gesprochenes Audio aus Texteingaben generieren, und unterstützt verschiedene Stimmen, Geschwindigkeiten und Ausgabeformate für vielfältige Anwendungsfälle.
WICHTIG: z-ai-web-dev-sdk DARF NUR im Backend-Code verwendet werden. Niemals im clientseitigen Code einsetzen.
API-Einschränkungen und -Beschränkungen
Vor der Implementierung der TTS-Funktionalität sollten Sie diese wichtigen Einschränkungen beachten:
Texteingabe-Beschränkungen
- Maximale Länge: 1024 Zeichen pro Anfrage
- Text, der dieses Limit überschreitet, muss in kleinere Teile aufgeteilt werden
Audioparameter
- Geschwindigkeitsbereich: 0,5 bis 2,0
- 0,5 = halbe Geschwindigkeit (langsamer)
- 1,0 = normale Geschwindigkeit (Standard)
- 2,0 = doppelte Geschwindigkeit (schneller)
- Lautstärkebereich: Größer als 0, bis zu 10
- Standard: 1,0
- Werte müssen größer als 0 (ausschließlich) und bis zu 10 (einschließlich) sein
Format und Streaming
- Streaming-Einschränkung: Wenn
stream: trueaktiviert ist, wird nur das Formatpcmunterstützt - Ohne Streaming: Unterstützt die Formate
wav,pcmundmp3 - Abtastrate: 24000 Hz (empfohlen)
Best Practice für lange Texte
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;
}
Voraussetzungen
Das Paket z-ai-web-dev-sdk ist bereits installiert. Importieren Sie es, wie in den folgenden Beispielen gezeigt.
CLI-Nutzung (für einfache Aufgaben)
Für einfache Text-to-Speech-Umwandlungen können Sie anstelle des Schreibens von Code die z-ai-CLI verwenden. Dies ist ideal für schnelle Audioerzeugung, Testen von Stimmen oder einfache Automatisierung.
Einfache TTS
# Text in Sprache umwandeln (Standardformat WAV)
z-ai tts --input "Hallo, Welt" --output ./hallo.wav
# Verwendung kurzer Optionen
z-ai tts -i "Hallo, Welt" -o ./hallo.wav
Verschiedene Stimmen und Geschwindigkeiten
# Bestimmte Stimme verwenden
z-ai tts -i "Willkommen bei unserem Service" -o ./willkommen.wav --voice tongtong
# Sprachgeschwindigkeit anpassen (0,5-2,0)
z-ai tts -i "Dies ist schnellere Sprache" -o ./schnell.wav --speed 1.5
# Langsamere Sprache
z-ai tts -i "Dies ist langsamere Sprache" -o ./langsam.wav --speed 0.8
Verschiedene Ausgabeformate
# MP3-Format
z-ai tts -i "Hallo Welt" -o ./hallo.mp3 --format mp3
# WAV-Format (Standard)
z-ai tts -i "Hallo Welt" -o ./hallo.wav --format wav
# PCM-Format
z-ai tts -i "Hallo Welt" -o ./hallo.pcm --format pcm
Streaming-Ausgabe
# Stream-Audioerzeugung
z-ai tts -i "Dies ist ein längerer Text, der gestreamt wird" -o ./stream.wav --stream
CLI-Parameter
--input, -i <text>: Erforderlich - Text, der in Sprache umgewandelt werden soll (maximal 1024 Zeichen)--output, -o <pfad>: Erforderlich - Ausgabedateipfad für Audio--voice, -v <stimme>: Optional - Stimmtyp (Standard: tongtong)--speed, -s <zahl>: Optional - Sprachgeschwindigkeit, 0,5-2,0 (Standard: 1,0)--format, -f <format>: Optional - Ausgabeformat: wav, mp3, pcm (Standard: wav)--stream: Optional - Streaming-Ausgabe aktivieren (unterstützt nur pcm-Format)
Wann CLI vs. SDK verwenden
CLI verwenden für:
- Schnelle Text-to-Speech-Umwandlungen
- Testen verschiedener Stimmen und Geschwindigkeiten
- Einfache Batch-Audioerzeugung
- Befehlszeilen-Automatisierungsskripte
SDK verwenden für:
- Dynamische Audioerzeugung in Anwendungen
- Integration mit Webdiensten
- Benutzerdefinierte Audioverarbeitungspipelines
- Produktionsanwendungen mit komplexen Anforderungen
Einfache TTS-Implementierung
Einfache Text-to-Speech
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
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
console.log(`Audio gespeichert unter ${outputPath}`);
return outputPath;
}
// Verwendung
await textToSpeech('Hallo, Welt!', './ausgabe.wav');
Mehrere Stimmoptionen
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, // Verfügbare Stimmen: tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
speed: 1.0,
response_format: 'wav',
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Verwendung
await generateWithVoice('Willkommen bei unserem Service', 'tongtong', './willkommen.wav');
Einstellbare Geschwindigkeit
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithSpeed(text, speed, outputPath) {
const zai = await ZAI.create();
// Geschwindigkeitsbereich: 0,5 bis 2,0 (API-Einschränkung)
// 0,5 = halbe Geschwindigkeit (langsamer)
// 1,0 = normale Geschwindigkeit (Standard)
// 2,0 = doppelte Geschwindigkeit (schneller)
// Werte außerhalb dieses Bereichs verursachen API-Fehler
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: speed,
response_format: 'wav',
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Verwendung - langsamere Erzählung
await generateWithSpeed('Dies ist eine wichtige Ankündigung', 0.8, './langsam.wav');
// Verwendung - schnellere Erzählung
await generateWithSpeed('Kurzes Update', 1.3, './schnell.wav');
Einstellbare Lautstärke
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithVolume(text, volume, outputPath) {
const zai = await ZAI.create();
// Lautstärkebereich: größer als 0, bis zu 10 (API-Einschränkung)
// Werte müssen > 0 (ausschließlich) und <= 10 (einschließlich) sein
// Standard: 1.0 (normale Lautstärke)
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
volume: volume, // Optionaler Parameter
response_format: 'wav',
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Verwendung - lauteres Audio
await generateWithVolume('Dies ist eine Ankündigung', 5.0, './laut.wav');
// Verwendung - leiseres Audio
await generateWithVolume('Geflüsterte Nachricht', 0.5, './leise.wav');
Fortgeschrittene Anwendungsfälle
Batch-Verarbeitung
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 = [];
// Sicherstellen, dass das Ausgabeverzeichnis existiert
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
});
// ArrayBuffer aus dem Response-Objekt holen
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;
}
// Verwendung
const texts = [
'Willkommen zu Kapitel eins',
'Willkommen zu Kapitel zwei',
'Willkommen zu Kapitel drei'
];
const results = await batchTextToSpeech(texts, './audio-ausgabe');
console.log('Generiert:', results.length, 'Audiodateien');
Dynamische Inhaltsgenerierung
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
});
// ArrayBuffer aus dem Response-Objekt holen
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;
}
}
// Verwendung
const generator = new TTSGenerator();
await generator.initialize();
await generator.saveAudio(
'Hallo, das ist ein Test',
'./ausgabe.wav',
{ speed: 1.2 }
);
Beispiel einer Next.js-API-Route
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 importieren
const ZAI = (await import('z-ai-web-dev-sdk')).default;
// SDK-Instanz erstellen
const zai = await ZAI.create();
// TTS-Audio generieren
const response = await zai.audio.tts.create({
input: text.trim(),
voice: voice,
speed: speed,
response_format: 'wav',
stream: false,
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
// Audio als Antwort zurückgeben
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-Fehler:', error);
return NextResponse.json(
{
error: error instanceof Error ? error.message : 'Spracherzeugung fehlgeschlagen, bitte später erneut versuchen',
},
{ status: 500 }
);
}
}
Best Practices
1. Textvorbereitung
function prepareTextForTTS(text) {
// Übermäßige Leerzeichen entfernen
text = text.replace(/\s+/g, ' ').trim();
// Häufige Abkürzungen für bessere Aussprache erweitern
const abbreviations = {
'z.B.': 'zum Beispiel',
'bzw.': 'beziehungsweise',
'usw.': 'und so weiter',
'etc.': 'et cetera'
};
for (const [abbr, full] of Object.entries(abbreviations)) {
text = text.replace(new RegExp(abbr, 'g'), full);
}
return text;
}
2. Fehlerbehandlung
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function safeTTS(text, outputPath) {
try {
// Eingabe validieren
if (!text || text.trim().length === 0) {
throw new Error('Texteingabe darf nicht leer sein');
}
if (text.length > 1024) {
throw new Error('Texteingabe überschreitet die maximale Länge von 1024 Zeichen');
}
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
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-Fehler:', error);
return {
success: false,
error: error.message
};
}
}
3. Wiederverwendung der SDK-Instanz
import ZAI from 'z-ai-web-dev-sdk';
// Singleton-Instanz erstellen
let zaiInstance = null;
async function getZAIInstance() {
if (!zaiInstance) {
zaiInstance = await ZAI.create();
}
return zaiInstance;
}
// Verwendung
const zai = await getZAIInstance();
const response = await zai.audio.tts.create({ ... });
Häufige Anwendungsfälle
- Hörbücher & Podcasts: Schriftliche Inhalte in Audioformat umwandeln
- E-Learning: Erzählungen für Bildungsinhalte erstellen
- Barrierefreiheit: Audioversionen von Textinhalten bereitstellen
- Sprachassistenten: Dynamische Antworten generieren
- Ansagen: Automatisierte Audio-Benachrichtigungen erstellen
- IVR-Systeme: Telefonansagen generieren
- Content-Lokalisierung: Audio in verschiedenen Sprachen erstellen
Integrationsbeispiele
Express.js-API-Endpunkt
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-ausgabe';
async function initZAI() {
zaiInstance = await ZAI.create();
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
}
app.post('/api/tts', async (req, res) => {
try {
const { text, voice, speed } = req.body;
const response = await zaiInstance.audio.tts.create({
input: text,
voice: voice || 'tongtong',
speed: speed || 1.0,
response_format: 'wav',
stream: false
});
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
const outputPath = path.join(outputDir, `${Date.now()}.wav`);
fs.writeFileSync(outputPath, buffer);
res.json({
success: true,
path: outputPath,
size: buffer.length
});
} catch (error) {
res.status(500).json({
success: false,
error: error.message
});
}
});
app.listen(3000, () => {
console.log('TTS-Server läuft auf Port 3000');
});
Fehlerbehebung
Häufige Probleme
- API-Authentifizierungsfehler: Stellen Sie sicher, dass Ihre API-Schlüssel korrekt konfiguriert sind
- Texteingabe zu lang: Kürzen Sie die Texteingabe auf 1024 Zeichen
- Ungültiger Geschwindigkeitsbereich: Verwenden Sie Werte zwischen 0,5 und 2,0
- Ungültiger Lautstärkebereich: Verwenden Sie Werte zwischen 0 (exklusive) und 10 (inklusive)
Debugging-Tipps
- Verwenden Sie
console.log, um die SDK-Parameter zu überprüfen - Stellen Sie sicher, dass die Ausgabeverzeichnisse existieren
- Überprüfen Sie die Netzwerkkonnektivität zur API
- Validieren Sie die Texteingabe vor dem Senden an die API