# Fala para texto para agentes de IA e vibe coders

> Basta colar um prompt no seu agente de código para colocar transcrição no app. A API do KolWrite usa só duas chamadas HTTP e uma chave em variável de ambiente, com cobrança por segundo a partir de US$ 0,48 por hora de áudio.

Última atualização: 2026-10-18 · HTML: https://console.kolwrite.com/pt/use-cases/ai-agents

## Prompt pronto para copiar

Funciona com Cursor, Claude Code, Codex, Windsurf, Lovable, Replit, Bolt e v0. Esse prompt direciona o agente para a documentação feita para máquinas, garantindo o uso dos IDs de modelo e parâmetros certos.

```text
Add speech-to-text to this app with the KolWrite API.
Read https://console.kolwrite.com/agent-instructions.md first.
- Key: process.env.KOLWRITE_API_KEY, sent as the x-api-key header (server side only).
- POST https://app.kolwrite.com/transcribe {"audio_url", "model": "oracle", "language": "auto", "output_format": "json"}
- Local files: POST /upload first, then use fileUrl as audio_url.
- Poll GET /transcribe/{jobId} every 5 s until COMPLETED or FAILED.
- Show result.segments (start, end, speaker, text).
```

## Deixe salvo no projeto

Coloque esta linha no `AGENTS.md`, `CLAUDE.md`, `.cursorrules` ou nas regras de projeto da sua ferramenta. Assim, as próximas sessões já partem da mesma referência:

```text
For speech-to-text, use the KolWrite API. Read https://console.kolwrite.com/agent-instructions.md and https://console.kolwrite.com/llms-full.txt before writing any code.
```

## O que o agente vai fazer

1. Pegar a URL do arquivo (ou subir um arquivo local via `POST /upload` e usar o `fileUrl`).
2. Criar a tarefa com `POST /transcribe` e salvar o `jobId`.
3. Consultar `GET /transcribe/{jobId}` até o status mudar para `COMPLETED`, ou aguardar um webhook.
4. Mostrar o conteúdo de `result.segments`, que traz o texto, os tempos de início e fim e a identificação de quem está falando.

Exemplo da requisição mais simples possível (transformando uma nota de voz em texto puro):

```bash
curl https://app.kolwrite.com/transcribe \
  -H "x-api-key: $KOLWRITE_API_KEY" -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/voice-note.m4a", "model": "oracle_mini", "output_format": "txt"}'
```

## O que dá para criar com os agentes

- [Editar vídeo com agentes de IA](https://console.kolwrite.com/pt/guides/video-editing-with-ai): você passa a transcrição com a marcação de tempo de cada palavra, o agente escolhe os trechos e o ffmpeg devolve o corte pronto.
- [API de legendas SRT](https://console.kolwrite.com/pt/guides/srt-subtitles-api): gere arquivos com `output_format: "srt"`, traduza legendas, use WebVTT ou queime a legenda direto no vídeo com o ffmpeg.
- [API de transcrição de reuniões](https://console.kolwrite.com/pt/guides/meeting-transcription-api): gravações com separação por participante, prontas para virar ata e lista de tarefas.
- [API de carimbos de tempo por palavra](https://console.kolwrite.com/pt/guides/word-timestamps-api): o segundo exato em que cada palavra começa e termina, ideal para criar clipes, fazer cortes e buscar termos.
- [Ferramenta de transcrição para agentes de IA](https://console.kolwrite.com/pt/guides/transcription-tool-for-ai-agents): definições prontas de ferramentas nos formatos da Anthropic e da OpenAI, além da regra para colocar no `AGENTS.md`.

## Como gerar a chave de API

Agentes não conseguem criar conta sozinhos. Uma pessoa precisa acessar [console.kolwrite.com/auth](https://console.kolwrite.com/auth?lang=pt), abrir a conta, comprar créditos e gerar a chave na página de chaves de API. Depois, salve essa chave em uma variável de ambiente (`KOLWRITE_API_KEY`) ou no gerenciador de segredos da sua plataforma. Faça as chamadas à API sempre pelo backend ou por funções serverless, nunca direto do navegador.

## Quanto custa

| Trabalho | Modelo | Custo |
| --- | --- | --- |
| 10 notas de voz de um minuto | `oracle_mini` | US$ 0,16 |
| Uma reunião de uma hora identificando quem fala | `oracle` | US$ 1,44 |
| 100 horas de áudio limpo | `base` | US$ 48,00 |

Cobramos por segundo, sem valor mínimo. Confira a tabela completa de preços em [/llms/pricing.md](https://console.kolwrite.com/llms/pricing.md).

## Documentação para leitura por máquina

- [llms.txt](https://console.kolwrite.com/llms.txt): indica qual chamada fazer e qual modelo escolher para cada tipo de tarefa.
- [llms-full.txt](https://console.kolwrite.com/llms-full.txt): toda a documentação reunida em um único arquivo Markdown.
- [openapi.json](https://console.kolwrite.com/openapi.json): especificação OpenAPI 3.1 para geradores de código e definição de ferramentas.
- [agent-instructions.md](https://console.kolwrite.com/agent-instructions.md): traz o prompt, os IDs dos modelos e os erros mais comuns para evitar.
- Qualquer página deste site também pode ser lida em Markdown. Basta colocar `.md` no final do endereço.

## Perguntas e respostas

### Um agente de IA consegue criar uma conta ou gerar uma chave de API do KolWrite?

Não. Uma pessoa precisa fazer o cadastro e gerar a chave. O agente apenas lê essa chave a partir de uma variável de ambiente.

### Qual modelo o agente deve usar por padrão?

Use `oracle` para áudio de produção, `base` se o áudio for limpo e você quiser o menor custo, ou `oracle_mini` quando precisar também de tradução barata. Sempre envie o parâmetro `model`, já que o padrão ainda é o modelo antigo `core`.

### Um agente de IA consegue editar vídeos com o KolWrite?

Sim, desde que o agente possa rodar comandos no sistema. Ele pede à API a transcrição com os tempos de cada palavra, decide quais partes manter e usa o ffmpeg para fazer os cortes. Veja o código no nosso [guia](https://console.kolwrite.com/pt/guides/video-editing-with-ai).

### Vocês têm servidor MCP ou SDK?

No momento da escrita, não há pacote SDK nem servidor MCP publicados. Os agentes chamam a API REST com curl ou Python, ou usam a [definição de ferramenta](https://console.kolwrite.com/pt/guides/transcription-tool-for-ai-agents); o [openapi.json](https://console.kolwrite.com/openapi.json) funciona com geradores de código.

### Posso chamar a API direto de um app só de front-end feito no Lovable, Bolt ou v0?

Expondo a chave no navegador, não. Use as funções de backend ou edge da própria plataforma para chamar o KolWrite sem revelar sua chave.

## Páginas relacionadas

- [Desenvolvedores e times de produto](https://console.kolwrite.com/pt/use-cases/developers)
- [Mídia, podcasts e legendas](https://console.kolwrite.com/pt/use-cases/media)
- [Centrais de atendimento e chamadas de vendas](https://console.kolwrite.com/pt/use-cases/call-centers)
- [Idiomas suportados](https://console.kolwrite.com/pt/languages/)

---
Obter uma chave de API: https://console.kolwrite.com/auth?lang=pt · Documentação da API: https://console.kolwrite.com/pt/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt