Habilidade de TTS (Texto para Fala)
Esta habilidade orienta a implementação da funcionalidade de texto para fala (TTS) usando o pacote z-ai-web-dev-sdk, permitindo a conversão de texto em áudio de fala natural.
Caminho da Habilidade
Localização da Habilidade: {project_path}/skills/TTS
Esta habilidade está localizada no caminho acima em seu projeto.
Scripts de Referência: Scripts de teste de exemplo estão disponíveis no diretório {Skill Location}/scripts/ para teste e referência rápidos. 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 lado cliente.
Limitações e Restrições da API
Antes de implementar a funcionalidade TTS, esteja ciente destas limitações importantes:
Restrições de Texto de Entrada
- Comprimento máximo: 1024 caracteres por requisição
- Texto que exceder 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
- Valores devem ser maiores que 0 (exclusivo) e até 10 (inclusivo)
Formato e Streaming
- Limitação de streaming: Quando
stream: trueestá habilitado, 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 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 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
Diferentes Vozes e Velocidade
# Usar voz específica
z-ai tts -i "Bem-vindo ao nosso serviço" -o ./bem-vindo.wav --voice tongtong
# Ajustar velocidade da fala (0.5-2.0)
z-ai tts -i "Esta é uma fala mais rápida" -o ./rapida.wav --speed 1.5
# Fala mais lenta
z-ai tts -i "Esta é uma fala mais lenta" -o ./lenta.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 por Streaming
# Geração de áudio por 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 - Habilitar saída por 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 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 de processamento de áudio personalizados
- 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', './bem-vindo.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 na 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)
// 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 Dinâmica de Conteúdo
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 áudio, 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
- 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 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 });
}
}
app.post('/api/tts', async (req, res) => {
try {
const { text, voice, speed } = req.body;
const timestamp = Date.now();
const outputPath = path.join(outputDir, `tts_${timestamp}.wav`);
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));
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('Servidor TTS rodando na porta 3000'));
Referência de API
Método zai.audio.tts.create(options)
| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
input | string | Sim | - | Texto para converter em fala (máx. 1024 caracteres) |
voice | string | Sim | - | Voz a ser usada (tongtong, chuichui, xiaochen, jam, kazi, douji, luodo) |
speed | number | Não | 1.0 | Velocidade da fala (0.5 a 2.0) |
volume | number | Não | 1.0 | Volume do áudio (> 0 e <= 10) |
response_format | string | Não | 'wav' | Formato de saída (wav, mp3, pcm) |
stream | boolean | Não | false | Habilitar saída por streaming (apenas pcm) |
Solução de Problemas
Problemas Comuns
-
Erro de validação de comprimento do texto: O texto de entrada excede o limite máximo de 1024 caracteres. Divida o texto em partes menores.
-
Erro de parâmetro de velocidade inválido: O valor da velocidade está fora da faixa permitida (0.5-2.0). Certifique-se de que a velocidade está dentro do intervalo especificado.
-
Erro de formato de streaming: Quando
stream: trueestá definido, apenas o formatopcmé suportado. Altere o formato para pcm ou desabilite o streaming. -
Instância do SDK não inicializada: Certifique-se de que
ZAI.create()é chamado antes de usar qualquer funcionalidade TTS. -
Erro de caminho de saída: Certifique-se de que o diretório de saída existe ou seja criado com
fs.mkdirSynccom a opçãorecursive: true.