# Build with AI

Two ways to use Lero with AI. The MCP puts Lero's voice inside Claude, Codex and Cursor. The prompt makes your coding agent integrate the API into your product.

## MCP

The MCP puts Lero inside your agent. It gets 3 tools and starts generating audio straight from the chat, without you writing code. Run your agent's command, with your key in place of `lero_your_key`:

Claude Code:

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

Codex:

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

Cursor:

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

Claude Desktop:

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

In Cursor, the JSON goes in `~/.cursor/mcp.json`. In Claude Desktop, in Settings > Developer > Edit Config. Needs Node 18 or newer.

Then just ask, for example: *make an audio in the São Paulo voice saying "seu pedido saiu para entrega"*.

| tool | what it does | cost |
|---|---|---|
| `lero_fala` | Turns text into speech and saves the MP3. Up to 500 characters per call. | 1 credit per character |
| `lero_vozes` | Lists the voices. | free |
| `lero_saldo` | Shows the account credits and the plan. | free |

The MP3s go to `~/Downloads/Lero`. To change the folder, add `LERO_PASTA` to the config, the same way as the key. The key stays only in your agent's config, on your computer, and goes straight to the Lero API.

## The prompt

Want Lero in your product's code? Paste this prompt into your coding agent (Claude Code, Codex, Cursor or another one that reads the web). It reads the docs and writes the integration. The same text is in [prompt.md](https://lero.studio/docs/en/prompt.md).

```markdown
# Integrate the Lero API

You will integrate the Lero voice API into my project. Follow these instructions.

## What Lero is

Lero turns text into speech in Brazilian Portuguese, with a regional accent. You send the text and the voice and get back an MP3. Voices: `rio` (Rio de Janeiro), `sp` (São Paulo), `niteroi` (Niterói). Model: `Lero v1`.

Lero also transcribes Brazilian Portuguese audio (Speech-to-Text): you send the file or a link and get back the text, the sentences with their timestamps, or ready subtitles (SRT or VTT).

## Read before writing code

1. https://lero.studio/docs/en/llms-full.txt: the complete reference in Markdown.
2. https://lero.studio/docs/en/openapi.json: the OpenAPI 3.1 contract of the routes.

Follow the contract. Do not invent routes, fields or error codes.

## Connection

- Base URL: https://app.lero.studio/api/v1
- Every request carries the header `Authorization: Bearer <key>`.
- Read the key from the `LERO_API_KEY` environment variable. Never write the key in the code.
- Call the API only from the server. Never from the browser or a mobile app: whoever has the key spends the credits.

## Routes

1. `POST /v1/tts` with `{"texto": "...", "voz": "rio"}`: returns the MP3 (`audio/mpeg`). With `Accept: application/json` (without `*/*`), returns JSON with the audio as base64 in the `audio` field.
2. `POST /v1/stt` with the file in the `audio` field as `multipart/form-data` (up to 4 MB), or JSON with `url` (public https link, up to 500 MB): returns JSON with `texto` and `segmentos` (the sentences with `inicio` and `fim` in seconds). With `formato` `texto`, `srt` or `vtt`, returns the file itself. Optional: `timestamps` (`palavra`), `palavras_chave`, `formatar`. Only if the request involves transcription, dictation or subtitles.
3. `GET /v1/voices`: the list of voices. Free.
4. `GET /v1/balance`: the account credits and the plan. Free.
5. Conversational Agent (live voice over WebRTC): `GET /v1/agents` and `POST /v1/agents/conversation`. Only if the request is a live voice agent; follow the "Conversational Agent: step by step" section of llms-full.txt.

## Rules

- Speech: 1 credit per character of the text, charged before generating and refunded if generation fails.
- Speech: up to 500 characters per request. For longer text, split it into sentences (never mid-word) and join the MP3s in order.
- Transcription: 150 credits per minute of audio, charged only on success. Up to 2 h per request. Files over 4 MB go by `url`.
- Up to 60 requests per minute per account. On `429` or `503`, wait the seconds in the `Retry-After` header and try again.
- Speech takes a few seconds and transcription a few minutes (1 h of audio in about 2 min): use a 300 s timeout.
- Handle errors by the `erro` field (stable code), never by the `mensagem` text.
- Keep the MP3 and the transcript if you will use them again: each request spends credits, and Lero does not keep the audio or the text.
- Log the `X-Pedido-Id`, for support.

## Deliverables

- An API client with a timeout, waits on `Retry-After` and error handling by `erro`.
- Tests with mocked responses built from the `openapi.json` examples.
- A short summary of what was done and how to run it.
```

## Conversational Agent

For your coding agent to integrate the live voice agent (for example, a technical interviewer that sees the code editor, or a support agent with your knowledge base), paste this prompt with your goal:

```text
Integrate the Lero Conversational Agent into my project. Read https://lero.studio/docs/en/llms-full.txt (sections Conversational Agent and "Conversational Agent: step by step") and https://lero.studio/docs/en/openapi.json (/agents and /agents/conversation). Rules: the WebRTC client creates the "chat" data channel before the offer; signaling goes through my backend, which keeps LERO_API_KEY; versao, llm and voz come from GET /v1/agents; my system prompt goes in "instrucoes" and my knowledge base in "conhecimento"; what the agent must see during the call goes through "lero-contexto". Goal: <describe here>.
```

The contract has the full request (`instrucoes`, `conhecimento`, `abertura`, `palavras`, `silencio_s`, `pesquisa`, `max_tokens`), the events and the errors. For automated tests without a browser, the agent can use the headless Python client of the [call route](https://lero.studio/docs/en#conversa).

## Docs for agents

The agent can learn the API on its own by reading these files. Nothing to set up.

- [llms.txt](https://lero.studio/docs/en/llms.txt): Short index of the docs, with one link per section and per route.
- [llms-full.txt](https://lero.studio/docs/en/llms-full.txt): All the docs in one Markdown file. It is the best context for the agent.
- [openapi.json](https://lero.studio/docs/en/openapi.json): OpenAPI 3.1 contract with the routes. Use it to generate a client and check examples.
- [skill.md](https://lero.studio/docs/en/skill.md): The `lero-api` Agent Skill for coding agents, with the routes and the rules.

## Install the skill

The `lero-api` skill teaches the API routes and rules to your coding agent. In Claude Code, install it with one command:

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

Then just ask, for example: *add the Lero voice to my backend*. The skill kicks in on its own when the request matches it. In other agents, point to [llms-full.txt](https://lero.studio/docs/en/llms-full.txt).

## Key

Create the key at [app.lero.studio/desenvolvedores](https://app.lero.studio/desenvolvedores?aba=chaves), on the Creator and Dev plans. It shows in full only once.

- Keep the key in an environment variable (`LERO_API_KEY`) or in the MCP config.
- Never paste the key into the prompt, the chat or the code.
- For the agent, create a key just for it, with a monthly credit cap and a short expiry. If it leaks, revoke it in the app.