Lab 01 — Text to Speech: workshop passo a passo

English · Índice dos workshops · Lab 02 →

Neste workshop você não recebe apenas uma explicação da arquitetura. Você abre o terminal, cria o projeto, cria cada arquivo, cola uma implementação completa, executa um checkpoint e só então avança.

Ao terminar, você terá uma aplicação Next.js que:

transforma texto em áudio com gpt-4o-mini-tts;
mantém OPENAI_API_KEY somente no servidor;
valida texto, voz, formato, instruções e velocidade;
encaminha o áudio em streaming;
oferece player, cancelamento e download;
trata erros sem vazar detalhes internos;
possui testes que não fazem chamadas pagas;
pode ser publicada na Vercel.

Comece em 5 minutos

Resultado: Texto vira áudio reproduzível e baixável
Tempo completo: 2–3 horas
Dificuldade: Iniciante
Tecnologias: Next.js, TypeScript, Speech API, streaming
Pré-requisitos: Node.js 22+, Git e conta da API OpenAI
Custo: Chamadas de voz são cobradas conforme o uso; testes offline não geram custo

Se você já possui uma API key e quer ver a solução final antes de construir, abra o terminal na pasta onde guarda projetos e execute:

git clone --depth 1 https://github.com/glaucia86/openai-voice-playground.git
cd openai-voice-playground/labs/lab-01-text-to-speech
npm ci
cp .env.example .env.local
npm run dev

No Windows PowerShell, substitua cp .env.example .env.local por Copy-Item .env.example .env.local. Antes de npm run dev, abra .env.local, coloque sua chave depois de OPENAI_API_KEY= e salve. Acesse http://localhost:3000, use uma frase curta e faça apenas o teste que pretende pagar.

Prefere construir?

Com apoio (recomendado): use a branch starter e o primeiro checkpoint.
Desde uma pasta vazia: abra o Capítulo 1 e escolha o Caminho C.
Código final: consulte a implementação na main sem substituir seu trabalho.

Veja o resultado antes de construir

Demonstração real da interface do Lab 01 Text to Speech, incluindo a área que gera e reproduz áudio. — Gravação real e comprimida do Lab 01. O fluxo recebe um texto curto, gera o áudio e apresenta player e download; nenhuma credencial ou informação pessoal aparece.

Se você prefere movimento reduzido, a descrição equivalente é: a pessoa digita texto, escolhe voz e formato, envia o pedido, aguarda o estado de processamento e recebe controles para reproduzir ou baixar o áudio.

Arquitetura em uma tela

Fluxo do Lab 01: pessoa usuária, interface Next.js, rota de servidor, OpenAI Speech API e player com download. — Fonte editável: Mermaid. O SVG é usado no GitHub Pages para manter a renderização previsível e acessível.

A interface roda no navegador e envia somente os campos permitidos para /api/speech. A Route Handler roda no servidor, valida o corpo, aplica origem, acesso e quota, usa OPENAI_API_KEY para chamar a Speech API e encaminha o stream. O navegador recebe áudio e metadados seguros — nunca a chave padrão. No laboratório, limites locais ajudam no desenvolvimento; em produção ainda são necessários autenticação real, rate limit distribuído, orçamento e observabilidade sem conteúdo.

Pergunta de compreensão: por que o navegador recebe o áudio, mas nunca deve receber OPENAI_API_KEY?

Escolha como acompanhar

Caminho	O que você faz	Recomendação
A — executar e estudar	clona a `main` e abre a solução final	bom para conhecer o resultado primeiro
B — construir pelo starter	parte de uma base compilável e implementa cada fatia	recomendado para acompanhar o workshop
C — criar do zero	cria também pastas, configuração e dependências	bom para estudo aprofundado ou aula longa

O guia de acompanhamento explica como preservar seu trabalho e consultar checkpoints com git diff e git show.

Comece agora

Siga os capítulos na ordem. Cada um termina com uma condição objetiva de conclusão.

Prepare conta, terminal e projeto — Escolha o caminho, confira ferramentas, proteja a API key e prove que a base executa.
Construa a aplicação arquivo por arquivo — Crie configuração, contrato, backend, streaming, interface e testes com o conteúdo completo de cada arquivo.
Execute, diagnostique e publique — Rode todos os gates, faça um smoke test controlado, resolva erros comuns e publique.

Quer compreender as decisões com mais profundidade? Leia o artigo arquitetural do Lab 01 depois ou em paralelo. O artigo explica os porquês; os capítulos acima dizem exatamente o que fazer.

Starter recomendado

Abra o terminal na pasta onde guarda seus projetos e execute:

git clone --branch workshop/lab-01-v1-starter \
  https://github.com/glaucia86/openai-voice-playground.git
cd openai-voice-playground
git switch -c minha-solucao-lab-01
npm ci --prefix labs/lab-01-text-to-speech
npm run check:lab01

O primeiro gate deve passar sem API key e sem chamada à OpenAI. Depois, abra o Capítulo 1.

Checkpoints de recuperação

Depois de concluir	Referência	Comparação
base inicial	`workshop/lab-01-v1-starter`	ponto de partida
contrato e schemas	`workshop/lab-01-v1-step-01-contract`	ver diff
backend e streaming	`workshop/lab-01-v1-step-02-server`	ver diff
interface e testes	`workshop/lab-01-v1-step-03-interface`	ver diff

Não faça checkout de um checkpoint com alterações não salvas. Primeiro faça commit na sua branch; depois use a referência para comparar.

Antes de continuar, confirme que: você escolheu uma das três rotas, sabe que a API pode gerar custo, tem Node.js 22+ e consegue explicar onde a API key ficará.

Evidência final

O laboratório está concluído quando estes comandos terminarem com código zero:

npm run check:lab01
git status -sb

O primeiro executa lint, TypeScript, testes e build. O segundo deve mostrar somente sua branch, sem .env.local, .next, node_modules ou arquivos inesperados versionados.

Começar o Capítulo 1 →