Skill TTS (Texto para Fala)
Esta skill orienta a implementação de funcionalidade de texto para 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 em seu projeto.
Scripts de Referência: Scripts de exemplo de teste estão disponíveis no diretório {Skill Location}/scripts/ para testes e referência rápidos. Veja {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: z-ai-web-dev-sdk DEVE ser usado apenas em código backend. Nunca o use em código do lado do 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 este limite deve ser dividido em partes 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 = velocidade dupla (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: trueestiver ativado, apenas o formatopcmé suportado - Sem streaming: Suporta 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 para 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
# Converter texto para 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
Diferentes Vozes e Velocidade
# Usar voz específica
z-ai tts -i "Bem-vindo ao nosso serviço" -o ./bemvindo.wav --voice tongtong
# Ajustar 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 com Streaming
# Geração de áudio com 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 para converter 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 - Ativar saída com streaming (suporta apenas formato pcm)
Quando Usar CLI vs SDK
Use CLI para:
- Conversões rápidas de texto para fala
- Testar diferentes vozes e velocidades
- Geração de áudio em lote simples
- 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
Texto para Fala Simples
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
});
// Obter 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
});
// Obter 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 = velocidade dupla (mais rápido)
// Valores fora deste intervalo causarão erros da API
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: speed,
response_format: 'wav',
stream: false
});
// Obter 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
});
// Obter 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 = [];
// Garantir 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
});
// Obter 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
});
// Obter 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();
// Importar SDK ZAI
const ZAI = (await import('z-ai-web-dev-sdk')).default;
// Criar instância do SDK
const zai = await ZAI.create();
// Gerar áudio TTS
const response = await zai.audio.tts.create({
input: text.trim(),
voice: voice,
speed: speed,
response_format: 'wav',
stream: false,
});
// Obter array buffer do objeto Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
// Retornar á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 fala. Tente novamente mais tarde.',
},
{ status: 500 }
);
}
}
Melhores Práticas
1. Preparação de Texto
function prepareTextForTTS(text) {
// Remover espaços em branco excessivos
text = text.replace(/\s+/g, ' ').trim();
// Expandir 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 {
// Validar 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
});
// Obter 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 da Instância do SDK
import ZAI from 'z-ai-web-dev-sdk';
// Criar 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
- Audiobooks 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 de sistema telefônico
- 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, speed, format } = req.body;
if (!text) {
return res.status(400).json({ error: 'Texto é obrigatório' });
}
const response = await zaiInstance.audio.tts.create({
input: text,
voice: voice || 'tongtong',
speed: speed || 1.0,
response_format: format || 'wav',
stream: false
});
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
res.setHeader('Content-Type', `audio/${format || 'wav'}`);
res.send(buffer);
} catch (error) {
console.error('Erro TTS:', error);
res.status(500).json({ error: error.message });
}
});
app.listen(3000, () => console.log('Servidor rodando na porta 3000'));
Suporte a Vozes
Atualmente, as seguintes vozes estão disponíveis:
| Voz | Descrição | Melhor Para |
|---|---|---|
| tongtong | Voz feminina padrão | Uso geral, narração |
| chuichui | Voz feminina suave | Conteúdo calmante, histórias infantis |
| xiaochen | Voz masculina | Narração, anúncios |
| jam | Voz masculina jovem | Conteúdo casual, moderno |
| kazi | Voz masculina profissional | Conteúdo empresarial, apresentações |
| douji | Voz feminina enérgica | Promoções, conteúdo animado |
| luodo | Voz masculina profunda | Trailers, anúncios dramáticos |
Parâmetros de Áudio
| Parâmetro | Tipo | Padrão | Faixa | Descrição |
|---|---|---|---|---|
| input | string | - | 1-1024 caracteres | O texto para converter em fala |
| voice | string | 'tongtong' | Ver tabela de vozes | O tipo de voz a usar |
| speed | number | 1.0 | 0.5-2.0 | Velocidade da fala |
| volume | number | 1.0 | 0 < volume <= 10 | Volume do áudio |
| response_format | string | 'wav' | 'wav', 'mp3', 'pcm' | Formato do áudio de saída |
| stream | boolean | false | true/false | Ativar saída com streaming |
Resolução de Problemas
Problemas Comuns
-
Texto muito longo (erro: "Entrada de texto muito longa")
- Use a função auxiliar
splitTextIntoChunks()para dividir o texto
- Use a função auxiliar
-
Velocidade fora do intervalo (erro: "Velocidade inválida")
- Certifique-se de que a velocidade esteja entre 0.5 e 2.0
-
Streaming sem PCM (erro: "Formato não suportado para streaming")
- Ao usar streaming, defina
response_format: 'pcm'
- Ao usar streaming, defina
-
Taxa de limite excedida (erro: "Muitas requisições")
- Implemente intervalos entre requisições consecutivas
Dicas de Depuração
- Sempre registre as respostas da API para rastreamento de erros
- Teste com texto curto primeiro antes de processar documentos longos
- Verifique os caminhos dos arquivos de saída e permissões
- Monitore o uso da API para evitar exceder limites de taxa