# Como qualquer agente de IA transcreve áudio com o KolWrite?

> Se o agente consegue rodar um comando de shell, dê a ele o kolwrite.py: um único arquivo Python, só com a biblioteca padrão, que envia o arquivo, inicia o job, espera e grava o resultado. Para agentes que carregam skills, há o mesmo arquivo empacotado como a skill kolwrite-transcribe, e para todo o resto há a API REST e o arquivo OpenAPI dela.

Última atualização: 2026-11-21 · HTML: https://console.kolwrite.com/pt/agents/any-agent

## O que você faz uma única vez

Crie você mesmo a conta e a chave em [console.kolwrite.com](https://console.kolwrite.com/auth?lang=pt): cadastre-se, adicione créditos, abra API Keys e crie uma chave. Um agente não consegue fazer isso por você.

Coloque a chave no arquivo de perfil do seu shell (`~/.zshrc`, `~/.bashrc`) para que toda sessão de agente que você abrir consiga lê-la, e abra um terminal novo:

```bash
export KOLWRITE_API_KEY=...   # paste the key from API Keys
```

As ferramentas leem a chave só dessa variável. Não cole a chave em um chat nem faça commit dela em um repositório.

## Baixar o kolwrite.py e verificá-lo

```bash
curl -fsSLO https://console.kolwrite.com/cli/kolwrite.py
echo "721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78  kolwrite.py" | shasum -a 256 -c -
```

SHA-256: `721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78`. Python 3.9 ou mais recente, sem pacotes para instalar. Código-fonte: [kolwrite.py](https://console.kolwrite.com/cli/kolwrite.py).

## Os comandos que o agente roda

```bash
python3 kolwrite.py transcribe meeting.m4a --model oracle --speakers --format json -o meeting.json
python3 kolwrite.py transcribe talk.mp4 --format srt -o talk.srt
python3 kolwrite.py transcribe interview.m4a --language he --translate-to en
python3 kolwrite.py transcribe https://example.com/podcast.mp3 --json
python3 kolwrite.py job JOB_ID
python3 kolwrite.py models
```

| Código de saída | Significado |
| --- | --- |
| 0 | Concluído; o resultado está no stdout ou no arquivo indicado por `-o` |
| 1 | Erro da API ou de rede; a mensagem da própria API é exibida |
| 2 | Erro de uso, ou `KOLWRITE_API_KEY` não está definida |
| 3 | Ainda em andamento depois do `--timeout`; consulte depois com `kolwrite.py job JOB_ID` |
| 4 | O job falhou; o motivo é exibido |

## A skill para agentes

Agentes que carregam Agent Skills (o Claude Code a partir de `~/.claude/skills`, o Codex a partir de `~/.agents/skills`) podem usar a pasta inteira: [SKILL.md](https://console.kolwrite.com/skills/kolwrite-transcribe/SKILL.md) mais `scripts/kolwrite.py`, compactados em [kolwrite-transcribe.zip](https://console.kolwrite.com/skills/kolwrite-transcribe.zip). Ela está listada em [/.well-known/agent-skills/index.json](https://console.kolwrite.com/.well-known/agent-skills/index.json).

```bash
curl -fsSLO https://console.kolwrite.com/skills/kolwrite-transcribe.zip && unzip -o kolwrite-transcribe.zip
```

## A regra para o AGENTS.md ou o CLAUDE.md

```markdown
For speech-to-text use the KolWrite API.
- Run python3 kolwrite.py (from https://console.kolwrite.com/cli/kolwrite.py, SHA-256 721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78) or call the API as https://console.kolwrite.com/agent-instructions.md describes.
- The key is in KOLWRITE_API_KEY. Never print it or write it to a file.
- Tell me the expected cost before transcribing more than an hour of audio.
```

Agentes que montam as próprias chamadas HTTP usam o [openapi.json](https://console.kolwrite.com/openapi.json) (OpenAPI 3.1 com exemplos e os códigos de erro reais) e o [llms-full.txt](https://console.kolwrite.com/llms-full.txt).

## Quanto custa

| Tarefa | Modelo | Custo |
| --- | --- | --- |
| Uma entrevista de 30 minutos, em texto simples | `base` | US$ 0,24 |
| Uma reunião de uma hora com identificação de falantes | `oracle` | US$ 1,56 |
| Uma palestra de uma hora em hebraico com legendas em inglês | `oracle` | US$ 1,44 |
| Uma hora de áudio com ruído e vozes sobrepostas | `oracle_max` | US$ 3,60 |

A cobrança é por segundo de áudio, descontada dos seus créditos, sem valor mínimo. A identificação de falantes soma 0,10 crédito por hora de áudio. O servidor MCP e o kolwrite.py usam o `base` a menos que você ou o agente indiquem outro modelo, e o `oracle_mini` ao traduzir. Todos os preços: [/pt/models](https://console.kolwrite.com/pt/models).

## O que o agente não deve fazer

- Pedir a chave a você no chat, exibi-la ou gravá-la em um arquivo, em um comando ou em um commit.
- Iniciar de novo a mesma transcrição depois de um timeout ou de um erro de rede. Cada início é um job novo e é cobrado; em vez disso, deve consultar o job existente ou perguntar a você.
- Digitar timestamps por conta própria. Para cortar ou citar por tempo, ele pega os números dos segmentos na transcrição e calcula os tempos no código, a partir dos tempos das palavras.
- Enviar como mídia o endereço de um vídeo do YouTube ou de outra página da web. O que a API precisa é do arquivo de mídia em si.
- Transcrever gravações longas (mais de uma hora) sem antes avisar você do custo previsto.

## Perguntas e respostas

### Por que um único arquivo em vez de um pacote?

Não há nada para instalar e nada que mude sem você perceber: o agente baixa um arquivo, confere o hash e roda. Ainda não existe um pacote SDK no npm nem no PyPI.

### O que o kolwrite.py envia, e para onde?

Só o arquivo e as opções que você informar, para a API do KolWrite em app.kolwrite.com, com a sua chave no header `x-api-key`. Arquivos acima de 4 MiB vão para o formulário de armazenamento assinado que a API devolve, sem a chave.

## Páginas relacionadas

- [Claude Code](https://console.kolwrite.com/pt/agents/claude-code)
- [Codex](https://console.kolwrite.com/pt/agents/codex)
- [Ferramenta de transcrição para agentes de IA](https://console.kolwrite.com/pt/guides/transcription-tool-for-ai-agents)
- [Agentes de IA e vibe coding](https://console.kolwrite.com/pt/use-cases/ai-agents)
- [Documentação da API](https://console.kolwrite.com/pt/public_api_docs)

---
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
