Skill de TTS (Text-to-Speech)
Esta skill orienta a implementação da funcionalidade de conversão de texto em fala (TTS) usando o pacote z-ai-web-dev-sdk, permitindo a conversão de texto em áudio de fala com som natural.
Caminho da Skill
Localização da Skill: {project_path}/skills/TTS
Esta skill está localizada no caminho acima no seu projeto.
Scripts de Referência: Scripts de teste de exemplo estão disponíveis no diretório {Skill Location}/scripts/ para testes rápidos e referência. Consulte {Skill Location}/scripts/tts.ts para um exemplo funcional.
Visão Geral
Texto-para-Fala permite que você construa aplicações que geram áudio falado a partir de entrada de texto, suportando várias vozes, velocidades e formatos de saída para diversos casos de uso.
IMPORTANTE: O z-ai-web-dev-sdk DEVE ser usado apenas em código backend. Nunca o use em código cliente.
Limitações e Restrições da API
Antes de implementar a funcionalidade TTS, esteja ciente destas limitações importantes:
Restrições do Texto de Entrada
- Comprimento máximo: 1024 caracteres por requisição
- Texto que exceda esse limite deve ser dividido em pedaços menores
Parâmetros de Áudio
- Faixa de velocidade: 0,5 a 2,0
- 0,5 = metade da velocidade (mais lento)
- 1,0 = velocidade normal (padrão)
- 2,0 = dobro da velocidade (mais rápido)
- Faixa de volume: Maior que 0, até 10
- Padrão: 1,0
- Os valores devem ser maiores que 0 (exclusivo) e até 10 (inclusivo)
Formato e Streaming
- Limitação de streaming: Quando
stream: trueestá ativado, apenas o formatopcmé suportado - Sem streaming: Suporta os formatos
wav,pcmemp3 - Taxa de amostragem: 24000 Hz (recomendado)
Melhor Prática para Texto Longo
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;
}
Pré-requisitos
O pacote z-ai-web-dev-sdk já está instalado. Importe-o conforme mostrado nos exemplos abaixo.
Uso via CLI (Para Tarefas Simples)
Para conversões simples de texto em fala, você pode usar a CLI do z-ai em vez de escrever código. Isso é ideal para geração rápida de áudio, teste de vozes ou automação simples.
TTS Básico
# Converte texto em fala (formato WAV padrão)
z-ai tts --input "Olá, mundo" --output ./ola.wav
# Usando opções curtas
z-ai tts -i "Olá, mundo" -o ./ola.wav
Vozes e Velocidades Diferentes
# Usa uma voz específica
z-ai tts -i "Bem-vindo ao nosso serviço" -o ./bemvindo.wav --voice tongtong
# Ajusta a velocidade da fala (0,5-2,0)
z-ai tts -i "Esta é uma fala mais rápida" -o ./rapido.wav --speed 1.5
# Fala mais lenta
z-ai tts -i "Esta é uma fala mais lenta" -o ./lento.wav --speed 0.8
Diferentes Formatos de Saída
# Formato MP3
z-ai tts -i "Olá Mundo" -o ./ola.mp3 --format mp3
# Formato WAV (padrão)
z-ai tts -i "Olá Mundo" -o ./ola.wav --format wav
# Formato PCM
z-ai tts -i "Olá Mundo" -o ./ola.pcm --format pcm
Saída em Streaming
# Geração de áudio em streaming
z-ai tts -i "Este é um texto mais longo que será transmitido" -o ./stream.wav --stream
Parâmetros da CLI
--input, -i <texto>: Obrigatório - Texto a ser convertido em fala (máx. 1024 caracteres)--output, -o <caminho>: Obrigatório - Caminho do arquivo de áudio de saída--voice, -v <voz>: Opcional - Tipo de voz (padrão: tongtong)--speed, -s <número>: Opcional - Velocidade da fala, 0,5-2,0 (padrão: 1,0)--format, -f <formato>: Opcional - Formato de saída: wav, mp3, pcm (padrão: wav)--stream: Opcional - Ativa saída em streaming (suporta apenas formato pcm)
Quando Usar CLI vs SDK
Use CLI para:
- Conversões rápidas de texto em fala
- Testar diferentes vozes e velocidades
- Geração simples de áudio em lote
- Scripts de automação de linha de comando
Use SDK para:
- Geração dinâmica de áudio em aplicações
- Integração com serviços web
- Pipelines personalizados de processamento de áudio
- Aplicações de produção com requisitos complexos
Implementação Básica de TTS
Conversão Simples de Texto em Fala
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
});
// Obtém o array buffer do objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
console.log(`Áudio salvo em ${outputPath}`);
return outputPath;
}
// Uso
await textToSpeech('Olá, mundo!', './output.wav');
Múltiplas Opções 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, // Vozes disponíveis: tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
speed: 1.0,
response_format: 'wav',
stream: false
});
// Obtém o array buffer do objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Uso
await generateWithVoice('Bem-vindo ao nosso serviço', 'tongtong', './bemvindo.wav');
Velocidade Ajustável
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithSpeed(text, speed, outputPath) {
const zai = await ZAI.create();
// Faixa de velocidade: 0,5 a 2,0 (restrição da API)
// 0,5 = metade da velocidade (mais lento)
// 1,0 = velocidade normal (padrão)
// 2,0 = dobro da velocidade (mais rápido)
// Valores fora desta faixa causarão erros na API
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: speed,
response_format: 'wav',
stream: false
});
// Obtém o array buffer do objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Uso - narração mais lenta
await generateWithSpeed('Este é um anúncio importante', 0.8, './lento.wav');
// Uso - narração mais rápida
await generateWithSpeed('Atualização rápida', 1.3, './rapido.wav');
Volume Ajustável
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithVolume(text, volume, outputPath) {
const zai = await ZAI.create();
// Faixa de volume: maior que 0, até 10 (restrição da API)
// Os valores devem ser > 0 (exclusivo) e <= 10 (inclusivo)
// Padrão: 1,0 (volume 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
});
// Obtém o array buffer do objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Uso - áudio mais alto
await generateWithVolume('Este é um anúncio', 5.0, './alto.wav');
// Uso - áudio mais baixo
await generateWithVolume('Mensagem sussurrada', 0.5, './baixo.wav');
Casos de Uso Avançados
Processamento em Lote
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 = [];
// Garante que o diretório de saída 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
});
// Obtém o array buffer do 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 = [
'Bem-vindo ao capítulo um',
'Bem-vindo ao capítulo dois',
'Bem-vindo ao capítulo três'
];
const results = await batchTextToSpeech(texts, './audio-output');
console.log('Gerados:', results.length, 'arquivos de áudio');
Geração de Conteúdo Dinâmico
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
});
// Obtém o array buffer do 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(
'Olá, isto é um teste',
'./output.wav',
{ speed: 1.2 }
);
Exemplo de Rota de API 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();
// Importa o SDK ZAI
const ZAI = (await import('z-ai-web-dev-sdk')).default;
// Cria uma instância do SDK
const zai = await ZAI.create();
// Gera áudio TTS
const response = await zai.audio.tts.create({
input: text.trim(),
voice: voice,
speed: speed,
response_format: 'wav',
stream: false,
});
// Obtém o array buffer do objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
// Retorna o áudio como resposta
return new NextResponse(buffer, {
status: 200,
headers: {
'Content-Type': 'audio/wav',
'Content-Length': buffer.length.toString(),
'Cache-Control': 'no-cache',
},
});
} catch (error) {
console.error('Erro na API TTS:', error);
return NextResponse.json(
{
error: error instanceof Error ? error.message : 'Falha ao gerar áudio, tente novamente mais tarde',
},
{ status: 500 }
);
}
}
Melhores Práticas
1. Preparação de Texto
function prepareTextForTTS(text) {
// Remove espaços em branco excessivos
text = text.replace(/\s+/g, ' ').trim();
// Expande abreviações comuns para melhor pronúncia
const abbreviations = {
'Dr.': 'Doutor',
'Sr.': 'Senhor',
'Sra.': 'Senhora',
'etc.': 'et cetera'
};
for (const [abbr, full] of Object.entries(abbreviations)) {
text = text.replace(new RegExp(abbr, 'g'), full);
}
return text;
}
2. Tratamento de Erros
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function safeTTS(text, outputPath) {
try {
// Valida entrada
if (!text || text.trim().length === 0) {
throw new Error('A entrada de texto não pode estar vazia');
}
if (text.length > 1024) {
throw new Error('A entrada de texto excede o comprimento máximo 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
});
// Obtém o array buffer do 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('Erro TTS:', error);
return {
success: false,
error: error.message
};
}
}
3. Reutilização de Instância do SDK
import ZAI from 'z-ai-web-dev-sdk';
// Cria uma instância 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 Comuns
- Audiolivros e Podcasts: Converter conteúdo escrito em formato de áudio
- E-learning: Criar narração para conteúdo educacional
- Acessibilidade: Fornecer versões em áudio de conteúdo textual
- Assistentes de Voz: Gerar respostas dinâmicas
- Anúncios: Criar notificações de áudio automatizadas
- Sistemas IVR: Gerar prompts para sistemas telefônicos
- Localização de Conteúdo: Criar áudio em diferentes idiomas
Exemplos de Integração
Endpoint de API 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 = './audio-output';
async function initZAI() {
zaiInstance = await ZAI.create();
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
}
initZAI();
app.post('/api/tts', async (req, res) => {
try {
const { text, voice = 'tongtong', speed = 1.0 } = req.body;
const response = await zaiInstance.audio.tts.create({
input: text.trim(),
voice: voice,
speed: speed,
response_format: 'wav',
stream: false
});
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
const timestamp = Date.now();
const outputPath = path.join(outputDir, `tts-${timestamp}.wav`);
fs.writeFileSync(outputPath, buffer);
res.json({
success: true,
audioPath: outputPath,
size: buffer.length
});
} catch (error) {
console.error('Erro TTS:', error);
res.status(500).json({
success: false,
error: error instanceof Error ? error.message : 'Erro interno do servidor'
});
}
});
app.listen(3000, () => {
console.log('Servidor TTS rodando na porta 3000');
});
Conclusão
A skill TTS fornece capacidades robustas de conversão de texto em fala via CLI para tarefas rápidas e SDK para aplicações complexas. Siga as limitações da API, use as práticas recomendadas para tratamento de erros e preparação de texto, e reutilize instâncias do SDK para desempenho ideal. A flexibilidade em vozes, velocidade e formatos a torna adequada para diversos casos de uso, desde audiolivros até assistentes de voz.
Próximos Passos
- Experimente com diferentes vozes e velocidades
- Implemente tratamento de erros e validação
- Processe textos longos dividindo-os em pedaços
- Reutilize instâncias do SDK para melhor desempenho