# Come trascrive audio con KolWrite qualsiasi agente IA?

> Se l’agente può eseguire un comando di shell, dagli kolwrite.py: un unico file Python, solo con la libreria standard, che carica il file, avvia il job, aspetta e scrive il risultato. Per gli agenti che caricano skill c’è lo stesso file impacchettato come skill kolwrite-transcribe, e per tutto il resto ci sono l’API REST e il suo file OpenAPI.

Ultimo aggiornamento: 2026-11-21 · HTML: https://console.kolwrite.com/it/agents/any-agent

## Cosa fai una volta sola

Crea tu l’account e la chiave su [console.kolwrite.com](https://console.kolwrite.com/auth?lang=it): registrati, aggiungi crediti, apri API Keys e crea una chiave. Un agente non può farlo al posto tuo.

Metti la chiave nel file di profilo della tua shell (`~/.zshrc`, `~/.bashrc`) in modo che ogni sessione di agente che avvii possa leggerla, poi apri un nuovo terminale:

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

Gli strumenti leggono la chiave solo da questa variabile. Non incollarla in una chat e non farne il commit in un repository.

## Scaricare kolwrite.py e verificarlo

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

SHA-256: `721055e7e1af698755f88da45b98d56541dc278228f3b9bcf6bdd87fe4e15b78`. Serve Python 3.9 o successivo, nessun pacchetto da installare. Sorgente: [kolwrite.py](https://console.kolwrite.com/cli/kolwrite.py).

## I comandi che l’agente esegue

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

| Codice di uscita | Significato |
| --- | --- |
| 0 | Fatto; il risultato è su stdout o nel file indicato con `-o` |
| 1 | Errore dell’API o di rete; viene stampato il messaggio dell’API |
| 2 | Errore d’uso, oppure `KOLWRITE_API_KEY` non è impostata |
| 3 | Ancora in corso dopo `--timeout`; controlla più tardi con `kolwrite.py job JOB_ID` |
| 4 | Il job è fallito; viene stampato il motivo |

## La skill per agenti

Gli agenti che caricano Agent Skills (Claude Code da `~/.claude/skills`, Codex da `~/.agents/skills`) possono usare l’intera cartella: [SKILL.md](https://console.kolwrite.com/skills/kolwrite-transcribe/SKILL.md) più `scripts/kolwrite.py`, compressi in [kolwrite-transcribe.zip](https://console.kolwrite.com/skills/kolwrite-transcribe.zip). È elencata in [/.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
```

## La regola per AGENTS.md 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.
```

Gli agenti che costruiscono da soli le chiamate HTTP usano [openapi.json](https://console.kolwrite.com/openapi.json) (OpenAPI 3.1 con esempi e i codici di errore effettivi) e [llms-full.txt](https://console.kolwrite.com/llms-full.txt).

## Quanto costa

| Operazione | Modello | Costo |
| --- | --- | --- |
| Un’intervista di 30 minuti, solo testo | `base` | 0,24 US$ |
| Una riunione di un’ora con riconoscimento degli interlocutori | `oracle` | 1,56 US$ |
| Un intervento di un’ora in ebraico con sottotitoli in inglese | `oracle` | 1,44 US$ |
| Un’ora di audio rumoroso con voci sovrapposte | `oracle_max` | 3,60 US$ |

Si paga al secondo di audio, dai tuoi crediti, senza minimo. Il riconoscimento degli interlocutori aggiunge 0,10 crediti per ora di audio. Il server MCP e kolwrite.py usano `base` se tu o l’agente non indicate un altro modello, e `oracle_mini` per tradurre. Tutte le tariffe: [/it/models](https://console.kolwrite.com/it/models).

## Cosa l’agente non deve fare

- Chiederti la chiave nella chat, stamparla o scriverla in un file, in un comando o in un commit.
- Riavviare la stessa trascrizione dopo un timeout o un errore di rete. Ogni avvio è un nuovo job e viene fatturato; deve invece controllare il job esistente o chiedere a te.
- Scrivere i timestamp da solo. Per tagliare o citare in base al minutaggio, prende i numeri dei segmenti dalla trascrizione e calcola i tempi via codice a partire dai timestamp delle parole.
- Inviare come file multimediale l’indirizzo di un video di YouTube o di un’altra pagina web. Serve il file multimediale vero e proprio.
- Trascrivere registrazioni lunghe (oltre un’ora) senza dirti prima il costo previsto.

## Domande e risposte

### Perché un solo file invece di un pacchetto?

Non c’è niente da installare e niente che cambi senza che tu lo sappia: l’agente scarica un file, ne controlla l’hash e lo esegue. Non esiste ancora un pacchetto SDK su npm o PyPI.

### Cosa invia kolwrite.py, e dove?

Solo il file e le opzioni che gli dai, all’API di KolWrite su app.kolwrite.com, con la tua chiave nell’header `x-api-key`. I file oltre i 4 MiB vengono caricati tramite il form firmato dello storage restituito dall’API, senza la chiave.

## Pagine correlate

- [Claude Code](https://console.kolwrite.com/it/agents/claude-code)
- [Codex](https://console.kolwrite.com/it/agents/codex)
- [Strumento di trascrizione per agenti IA](https://console.kolwrite.com/it/guides/transcription-tool-for-ai-agents)
- [Agenti IA e vibe coding](https://console.kolwrite.com/it/use-cases/ai-agents)
- [Documentazione dell’API](https://console.kolwrite.com/it/public_api_docs)

---
Ottieni una chiave API: https://console.kolwrite.com/auth?lang=it · Documentazione dell’API: https://console.kolwrite.com/it/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt
