# Build with AI

Duas formas de usar o Lero com IA. O MCP coloca a voz do Lero dentro do Claude, do Codex e do Cursor. O prompt faz o seu agente de código integrar a API no seu produto.

## MCP

O MCP coloca o Lero dentro do seu agente. Ele ganha 3 ferramentas e passa a gerar áudio direto da conversa, sem você escrever código. Rode o comando do seu agente, com a sua chave no lugar de `lero_sua_chave`:

Claude Code:

```bash
claude mcp add --env LERO_API_KEY=lero_sua_chave lero -- npx -y lero-mcp
```

Codex:

```bash
codex mcp add lero --env LERO_API_KEY=lero_sua_chave -- npx -y lero-mcp
```

Cursor:

```json
{
  "mcpServers": {
    "lero": {
      "command": "npx",
      "args": [
        "-y",
        "lero-mcp"
      ],
      "env": {
        "LERO_API_KEY": "lero_sua_chave"
      }
    }
  }
}
```

Claude Desktop:

```json
{
  "mcpServers": {
    "lero": {
      "command": "npx",
      "args": [
        "-y",
        "lero-mcp"
      ],
      "env": {
        "LERO_API_KEY": "lero_sua_chave"
      }
    }
  }
}
```

No Cursor, o JSON vai em `~/.cursor/mcp.json`. No Claude Desktop, em Settings > Developer > Edit Config. Precisa do Node 18 ou mais novo.

Depois é só pedir, por exemplo: *gera um áudio na voz de São Paulo dizendo "seu pedido saiu para entrega"*.

| ferramenta | o que faz | custo |
|---|---|---|
| `lero_fala` | Transforma o texto em fala e salva o MP3. Até 500 caracteres por chamada. | 1 crédito por caractere |
| `lero_vozes` | Lista as vozes. | grátis |
| `lero_saldo` | Mostra os créditos da conta e o plano. | grátis |

Os MP3 ficam em `~/Downloads/Lero`. Para mudar a pasta, adicione `LERO_PASTA` na config, do mesmo jeito que a chave. A chave fica só na config do seu agente, no seu computador, e vai direto para a API do Lero.

## O prompt

Quer o Lero no código do seu produto? Cole este prompt no seu agente de código (Claude Code, Codex, Cursor ou outro que leia a web). Ele lê a documentação e escreve a integração. O mesmo texto está em [prompt.md](https://lero.studio/docs/prompt.md).

```markdown
# Integrar a API do Lero

Você vai integrar a API de voz do Lero no meu projeto. Siga estas instruções.

## O que é o Lero

O Lero transforma texto em fala em português do Brasil, com sotaque. Você manda o texto e a voz e recebe um MP3. Vozes: `rio` (Rio de Janeiro), `sp` (São Paulo), `niteroi` (Niterói). Model: `Lero v1`.

O Lero também transcreve áudio em português do Brasil (Speech-to-Text): você manda o arquivo ou um link e recebe o texto, as frases com o tempo de cada uma ou a legenda pronta (SRT ou VTT).

## Leia antes de escrever código

1. https://lero.studio/docs/llms-full.txt: a referência completa em Markdown.
2. https://lero.studio/docs/openapi.json: o contrato OpenAPI 3.1 das rotas.

Siga o contrato. Não invente rota, campo nem código de erro.

## Conexão

- Base URL: https://app.lero.studio/api/v1
- Toda request leva o header `Authorization: Bearer <chave>`.
- Leia a chave da variável de ambiente `LERO_API_KEY`. Nunca escreva a chave no código.
- Chame a API só do servidor. Nunca do navegador nem de um app de celular: quem tiver a chave gasta os créditos.

## Rotas

1. `POST /v1/tts` com `{"texto": "...", "voz": "rio"}`: devolve o MP3 (`audio/mpeg`). Com `Accept: application/json` (sem `*/*`), devolve JSON com o áudio em base64 no campo `audio`.
2. `POST /v1/stt` com o arquivo no campo `audio` em `multipart/form-data` (até 4 MB), ou JSON com `url` (link https público, até 500 MB): devolve JSON com `texto` e `segmentos` (as frases com `inicio` e `fim` em segundos). Com `formato` `texto`, `srt` ou `vtt`, devolve o arquivo direto. Opcionais: `timestamps` (`palavra`), `palavras_chave`, `formatar`. Só se o pedido envolver transcrição, ditado ou legenda.
3. `GET /v1/voices`: a lista das vozes. Grátis.
4. `GET /v1/balance`: os créditos da conta e o plano. Grátis.
5. Conversational Agent (voz ao vivo por WebRTC): `GET /v1/agents` e `POST /v1/agents/conversation`. Só se o pedido for um agente de voz ao vivo; siga a seção "Conversational Agent: passo a passo" do llms-full.txt.

## Regras

- Fala: 1 crédito por caractere do texto, cobrado antes de gerar e devolvido se a geração falhar.
- Fala: até 500 caracteres por pedido. Para um texto maior, divida em frases (nunca no meio de uma palavra) e junte os MP3 na ordem.
- Transcrição: 150 créditos por minuto de áudio, cobrados só quando dá certo. Até 2 h por pedido. Arquivo maior que 4 MB vai por `url`.
- Até 60 pedidos por minuto por conta. Se vier `429` ou `503`, espere os segundos do header `Retry-After` e tente de novo.
- A fala leva alguns segundos e a transcrição, alguns minutos (1 h de áudio em uns 2 min): use timeout de 300 s.
- Trate os erros pelo campo `erro` (código fixo), nunca pelo texto da `mensagem`.
- Guarde o MP3 e a transcrição se for usar de novo: cada pedido gasta créditos, e o Lero não guarda o áudio nem o texto.
- Guarde o `X-Pedido-Id` nos logs, para o suporte.

## Entrega

- Um cliente da API com timeout, espera no `Retry-After` e tratamento de erro pelo `erro`.
- Testes com respostas simuladas a partir dos exemplos do `openapi.json`.
- Um resumo curto do que foi feito e de como rodar.
```

## Conversational Agent

Para o seu agente de código integrar o voice agent ao vivo (por exemplo, um entrevistador técnico que vê o code editor, ou um atendente com a sua base), cole este prompt com o seu objetivo:

```text
Integre o Lero Conversational Agent no meu projeto. Leia https://lero.studio/docs/llms-full.txt (seções Conversational Agent e "Conversational Agent: passo a passo") e https://lero.studio/docs/openapi.json (/agents e /agents/conversation). Regras: o client WebRTC cria o data channel "chat" antes da offer; o signaling passa pelo meu backend, que guarda LERO_API_KEY; versao, llm e voz vêm do GET /v1/agents; o meu system prompt vai em "instrucoes" e a minha base em "conhecimento"; o que o agente precisa ver durante a ligação vai por "lero-contexto". Objetivo: <descreva aqui>.
```

O contrato tem o request inteiro (`instrucoes`, `conhecimento`, `abertura`, `palavras`, `silencio_s`, `pesquisa`, `max_tokens`), os events e os erros. Para testes automáticos sem browser, o agente pode usar o client headless em Python da [rota de conversa](https://lero.studio/docs#conversa).

## Docs para agentes

O agente pode aprender a API sozinho, lendo estes arquivos. Nada precisa ser configurado.

- [llms.txt](https://lero.studio/docs/llms.txt): Índice curto da documentação, com um link por seção e por rota.
- [llms-full.txt](https://lero.studio/docs/llms-full.txt): A documentação inteira em um arquivo Markdown. É o melhor contexto para o agente.
- [openapi.json](https://lero.studio/docs/openapi.json): Contrato OpenAPI 3.1 com as rotas. Serve para gerar cliente e validar exemplos.
- [skill.md](https://lero.studio/docs/skill.md): Agent Skill `lero-api` para agentes de código, com as rotas e as regras.

## Instalar a skill

A skill `lero-api` ensina as rotas e as regras da API ao seu agente de código. No Claude Code, instale com um comando:

```bash
mkdir -p ~/.claude/skills/lero-api && curl -fsSL https://lero.studio/docs/skill.md -o ~/.claude/skills/lero-api/SKILL.md
```

Depois é só pedir, por exemplo: *integre a voz do Lero no meu backend*. A skill entra sozinha quando o pedido combina com ela. Em outros agentes, aponte para o [llms-full.txt](https://lero.studio/docs/llms-full.txt).

## Chave

Crie a chave em [app.lero.studio/desenvolvedores](https://app.lero.studio/desenvolvedores?aba=chaves), nos planos Creator e Dev. Ela aparece inteira uma vez só.

- Guarde a chave numa variável de ambiente (`LERO_API_KEY`) ou na config do MCP.
- Nunca cole a chave no prompt, no chat ou no código.
- Para o agente, crie uma chave só dele, com teto de créditos por mês e validade curta. Se vazar, revogue no app.