Skill de TTS (Texto a Voz)
Esta skill guía la implementación de funcionalidad de texto a voz (TTS) usando el paquete z-ai-web-dev-sdk, permitiendo la conversión de texto en audio de voz con sonido natural.
Ruta de la Skill
Ubicación de la Skill: {project_path}/skills/TTS
Esta skill se encuentra en la ruta anterior de tu proyecto.
Scripts de Referencia: Hay scripts de prueba de ejemplo disponibles en el directorio {Skill Location}/scripts/ para pruebas rápidas y referencia. Consulta {Skill Location}/scripts/tts.ts para un ejemplo funcional.
Descripción General
Texto a Voz te permite construir aplicaciones que generan audio hablado a partir de texto de entrada, soportando varias voces, velocidades y formatos de salida para diversos casos de uso.
IMPORTANTE: z-ai-web-dev-sdk DEBE usarse solo en código backend. Nunca lo uses en código del lado del cliente.
Limitaciones y Restricciones de la API
Antes de implementar la funcionalidad TTS, ten en cuenta estas limitaciones importantes:
Restricciones del Texto de Entrada
- Longitud máxima: 1024 caracteres por solicitud
- El texto que exceda este límite debe dividirse en fragmentos más pequeños
Parámetros de Audio
- Rango de velocidad: 0.5 a 2.0
- 0.5 = mitad de velocidad (más lento)
- 1.0 = velocidad normal (predeterminado)
- 2.0 = velocidad doble (más rápido)
- Rango de volumen: Mayor que 0, hasta 10
- Predeterminado: 1.0
- Los valores deben ser mayores que 0 (exclusivo) y hasta 10 (inclusive)
Formato y Streaming
- Limitación de streaming: Cuando
stream: trueestá habilitado, solo se soporta el formatopcm - Sin streaming: Soporta formatos
wav,pcmymp3 - Frecuencia de muestreo: 24000 Hz (recomendado)
Mejor Práctica para Texto Largo
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;
}
Prerrequisitos
El paquete z-ai-web-dev-sdk ya está instalado. Impórtalo como se muestra en los ejemplos a continuación.
Uso desde CLI (Para Tareas Simples)
Para conversiones de texto a voz simples, puedes usar la CLI de z-ai en lugar de escribir código. Esto es ideal para generación rápida de audio, probar voces o automatización simple.
TTS Básico
# Convertir texto a voz (formato WAV predeterminado)
z-ai tts --input "Hola, mundo" --output ./hola.wav
# Usando opciones cortas
z-ai tts -i "Hola, mundo" -o ./hola.wav
Diferentes Voces y Velocidad
# Usar voz específica
z-ai tts -i "Bienvenido a nuestro servicio" -o ./bienvenido.wav --voice tongtong
# Ajustar velocidad del habla (0.5-2.0)
z-ai tts -i "Este es un habla más rápida" -o ./rapido.wav --speed 1.5
# Habla más lenta
z-ai tts -i "Este es un habla más lenta" -o ./lento.wav --speed 0.8
Diferentes Formatos de Salida
# Formato MP3
z-ai tts -i "Hola Mundo" -o ./hola.mp3 --format mp3
# Formato WAV (predeterminado)
z-ai tts -i "Hola Mundo" -o ./hola.wav --format wav
# Formato PCM
z-ai tts -i "Hola Mundo" -o ./hola.pcm --format pcm
Salida en Streaming
# Generación de audio en streaming
z-ai tts -i "Este es un texto más largo que se transmitirá en streaming" -o ./stream.wav --stream
Parámetros de CLI
--input, -i <texto>: Requerido - Texto a convertir en voz (máx. 1024 caracteres)--output, -o <ruta>: Requerido - Ruta del archivo de audio de salida--voice, -v <voz>: Opcional - Tipo de voz (predeterminado: tongtong)--speed, -s <número>: Opcional - Velocidad del habla, 0.5-2.0 (predeterminado: 1.0)--format, -f <formato>: Opcional - Formato de salida: wav, mp3, pcm (predeterminado: wav)--stream: Opcional - Habilitar salida en streaming (solo soporta formato pcm)
Cuándo Usar CLI vs SDK
Usa CLI para:
- Conversiones rápidas de texto a voz
- Probar diferentes voces y velocidades
- Generación simple de audio por lotes
- Scripts de automatización en línea de comandos
Usa SDK para:
- Generación dinámica de audio en aplicaciones
- Integración con servicios web
- Tuberías personalizadas de procesamiento de audio
- Aplicaciones de producción con requisitos complejos
Implementación Básica de TTS
Texto a Voz Simple
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
});
// Obtener array buffer del objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
console.log(`Audio guardado en ${outputPath}`);
return outputPath;
}
// Uso
await textToSpeech('¡Hola, mundo!', './salida.wav');
Múltiples Opciones de Voz
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, // Voces disponibles: tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
speed: 1.0,
response_format: 'wav',
stream: false
});
// Obtener array buffer del objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Uso
await generateWithVoice('Bienvenido a nuestro servicio', 'tongtong', './bienvenido.wav');
Velocidad Ajustable
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithSpeed(text, speed, outputPath) {
const zai = await ZAI.create();
// Rango de velocidad: 0.5 a 2.0 (restricción de la API)
// 0.5 = mitad de velocidad (más lento)
// 1.0 = velocidad normal (predeterminado)
// 2.0 = velocidad doble (más rápido)
// Valores fuera de este rango causarán errores en la API
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: speed,
response_format: 'wav',
stream: false
});
// Obtener array buffer del objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Uso - narración más lenta
await generateWithSpeed('Este es un anuncio importante', 0.8, './lento.wav');
// Uso - narración más rápida
await generateWithSpeed('Actualización rápida', 1.3, './rapido.wav');
Volumen Ajustable
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithVolume(text, volume, outputPath) {
const zai = await ZAI.create();
// Rango de volumen: mayor que 0, hasta 10 (restricción de la API)
// Los valores deben ser > 0 (exclusivo) y <= 10 (inclusive)
// Predeterminado: 1.0 (volumen normal)
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
volume: volume, // Parámetro opcional
response_format: 'wav',
stream: false
});
// Obtener array buffer del objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Uso - audio más fuerte
await generateWithVolume('Este es un anuncio', 5.0, './fuerte.wav');
// Uso - audio más suave
await generateWithVolume('Mensaje susurrado', 0.5, './suave.wav');
Casos de Uso Avanzados
Procesamiento por Lotes
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 = [];
// Asegurarse de que el directorio de salida exista
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
});
// Obtener array buffer del objeto 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;
}
// Uso
const texts = [
'Bienvenido al capítulo uno',
'Bienvenido al capítulo dos',
'Bienvenido al capítulo tres'
];
const results = await batchTextToSpeech(texts, './salida-audio');
console.log('Generados:', results.length, 'archivos de audio');
Generación Dinámica de Contenido
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
});
// Obtener array buffer del objeto 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;
}
}
// Uso
const generator = new TTSGenerator();
await generator.initialize();
await generator.saveAudio(
'Hola, esto es una prueba',
'./salida.wav',
{ speed: 1.2 }
);
Ejemplo de Ruta API de Next.js
import { NextRequest, NextResponse } from 'next/server';
export async function POST(req: NextRequest) {
try {
const { text, voice = 'tongtong', speed = 1.0 } = await req.json();
// Importar SDK de ZAI
const ZAI = (await import('z-ai-web-dev-sdk')).default;
// Crear instancia del SDK
const zai = await ZAI.create();
// Generar audio TTS
const response = await zai.audio.tts.create({
input: text.trim(),
voice: voice,
speed: speed,
response_format: 'wav',
stream: false,
});
// Obtener array buffer del objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
// Devolver audio como respuesta
return new NextResponse(buffer, {
status: 200,
headers: {
'Content-Type': 'audio/wav',
'Content-Length': buffer.length.toString(),
'Cache-Control': 'no-cache',
},
});
} catch (error) {
console.error('Error en API TTS:', error);
return NextResponse.json(
{
error: error instanceof Error ? error.message : 'Error al generar el audio, inténtalo de nuevo más tarde',
},
{ status: 500 }
);
}
}
Prácticas Recomendadas
1. Preparación del Texto
function prepareTextForTTS(text) {
// Eliminar espacios en blanco excesivos
text = text.replace(/\s+/g, ' ').trim();
// Expandir abreviaturas comunes para una mejor pronunciación
const abbreviations = {
'Dr.': 'Doctor',
'Mr.': 'Señor',
'Mrs.': 'Señora',
'etc.': 'y otros'
};
for (const [abbr, full] of Object.entries(abbreviations)) {
text = text.replace(new RegExp(abbr, 'g'), full);
}
return text;
}
2. Manejo de Errores
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function safeTTS(text, outputPath) {
try {
// Validar entrada
if (!text || text.trim().length === 0) {
throw new Error('La entrada de texto no puede estar vacía');
}
if (text.length > 1024) {
throw new Error('La entrada de texto excede la longitud máxima de 1024 caracteres');
}
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// Obtener array buffer del objeto 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('Error TTS:', error);
return {
success: false,
error: error.message
};
}
}
3. Reutilización de la Instancia del SDK
import ZAI from 'z-ai-web-dev-sdk';
// Crear una instancia singleton
let zaiInstance = null;
async function getZAIInstance() {
if (!zaiInstance) {
zaiInstance = await ZAI.create();
}
return zaiInstance;
}
// Uso
const zai = await getZAIInstance();
const response = await zai.audio.tts.create({ ... });
Casos de Uso Comunes
- Audiolibros y Podcasts: Convertir contenido escrito a formato de audio
- E-learning: Crear narración para contenido educativo
- Accesibilidad: Proporcionar versiones de audio de contenido de texto
- Asistentes de Voz: Generar respuestas dinámicas
- Anuncios: Crear notificaciones de audio automatizadas
- Sistemas IVR: Generar mensajes de sistemas telefónicos
- Localización de Contenido: Crear audio en diferentes idiomas
Ejemplos de Integración
Endpoint API de Express.js
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 = './salida-audio';
async function initZAI() {
zaiInstance = await ZAI.create();
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
}
app.post('/tts', async (req, res) => {
try {
const { text, voice, speed } = req.body;
if (!text) {
return res.status(400).json({ error: 'El texto es requerido' });
}
const zai = zaiInstance || await initZAI();
const response = await zaiInstance.audio.tts.create({
input: text.trim(),
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, `tts_${Date.now()}.wav`);
fs.writeFileSync(outputPath, buffer);
res.download(outputPath);
} catch (error) {
console.error('Error en TTS:', error);
res.status(500).json({ error: 'Error generando audio' });
}
});
app.listen(3000, () => {
initZAI();
console.log('Servidor escuchando en el puerto 3000');
});
Resolución de Problemas
Errores Comunes
-
Límite de caracteres excedido
- Asegúrate de que el texto de entrada no supere los 1024 caracteres
- Usa la función
splitTextIntoChunkspara textos más largos
-
Errores de velocidad fuera de rango
- Asegúrate de que la velocidad esté entre 0.5 y 2.0
-
Errores de formato de streaming
- Cuando uses
stream: true, usa solo formatopcm
- Cuando uses
-
Errores de volumen
- Asegúrate de que el volumen sea > 0 y <= 10
Problemas de Red
- Asegúrate de la conexión a internet
- Verifica que la API de z-ai esté accesible
- Implementa reintentos para fallos transitorios
Referencia de la API
Parámetros de Entrada
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
input | string | - | Texto a convertir (obligatorio, máx. 1024 caracteres) |
voice | string | tongtong | Voz a usar: tongtong, chuichui, xiaochen, jam, kazi, douji, luodo |
speed | number | 1.0 | Velocidad del habla (0.5-2.0) |
volume | number | 1.0 | Volumen del audio (>0 a 10) |
response_format | string | wav | Formato de salida: wav, mp3, pcm |
stream | boolean | false | Habilitar salida en streaming |
Formato de Salida
- Formato WAV: Calidad completa, compatible con la mayoría de reproductores
- Formato MP3: Tamaño de archivo comprimido, ideal para almacenamiento
- Formato PCM: Audio sin procesar, adecuado para streaming y procesamiento personalizado