# Speech-to-text per agenti IA e vibe coder

> Ti basta incollare un prompt nel tuo agente di codice per integrare la trascrizione nella tua app. Per l’API di KolWrite servono solo due chiamate HTTP e una chiave in una variabile d’ambiente. Paghi al secondo, a partire da 0,48 US$ per ora di audio.

Ultimo aggiornamento: 2026-10-18 · HTML: https://console.kolwrite.com/it/use-cases/ai-agents

## Il prompt da copiare

Puoi usarlo su Cursor, Claude Code, Codex, Windsurf, Lovable, Replit, Bolt e v0. Rimanda l’agente alla documentazione pensata per le macchine, così imposterà da solo i parametri e gli ID dei modelli corretti.

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

## Salvalo nel progetto

Inserisci questa riga in `AGENTS.md`, `CLAUDE.md`, `.cursorrules` o nelle regole di progetto del tuo strumento, così anche le sessioni successive useranno sempre lo stesso riferimento:

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

## Cosa farà l’agente

1. Prende l’URL del file, oppure carica un file locale con `POST /upload` e recupera il `fileUrl`.
2. Avvia la trascrizione con `POST /transcribe` e salva il `jobId`.
3. Controlla lo stato su `GET /transcribe/{jobId}` finché non passa a `COMPLETED`, oppure aspetta la chiamata del webhook.
4. Mostra il contenuto di `result.segments`, con il testo, i tempi di inizio e fine e i vari interlocutori.

La chiamata minima per iniziare (da nota vocale a testo semplice):

```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"}'
```

## Cosa possono fare gli agenti con l’API

- [Montare video con agenti IA](https://console.kolwrite.com/it/guides/video-editing-with-ai): si parte da una trascrizione con i timestamp parola per parola, l’agente sceglie i passaggi e si ottiene il taglio con ffmpeg.
- [API per sottotitoli SRT](https://console.kolwrite.com/it/guides/srt-subtitles-api): usa `output_format: "srt"` per ottenere sottotitoli anche tradotti, in formato WebVTT o impressi nel video con ffmpeg.
- [API di trascrizione delle riunioni](https://console.kolwrite.com/it/guides/meeting-transcription-api): trascrive le registrazioni distinguendo chi parla, così sono già pronte per estrarre verbali e attività da assegnare.
- [API dei timestamp per parola](https://console.kolwrite.com/it/guides/word-timestamps-api): restituisce l’istante di inizio e fine di ogni singola parola, utile per estrarre clip, creare jump cut e fare ricerche nell’audio.
- [Strumento di trascrizione per agenti IA](https://console.kolwrite.com/it/guides/transcription-tool-for-ai-agents): le definizioni del tool nei formati Anthropic e OpenAI, più la regola da inserire in `AGENTS.md`.

## Come ottenere la chiave API

Gli agenti non possono registrarsi da soli. Deve farlo una persona aprendo un account su [console.kolwrite.com/auth](https://console.kolwrite.com/auth?lang=it), acquistando i crediti e creando una chiave nella sezione dedicata. Salva poi la chiave nella variabile d’ambiente `KOLWRITE_API_KEY` o nel gestore dei segreti della tua piattaforma, ed esegui le chiamate API solo lato server o da funzioni serverless, mai direttamente dal browser.

## Quanto costa

| Lavoro | Modello | Costo |
| --- | --- | --- |
| 10 note vocali da un minuto | `oracle_mini` | 0,16 US$ |
| Una riunione di un’ora con riconoscimento degli interlocutori | `oracle` | 1,44 US$ |
| 100 ore di audio pulito | `base` | 48,00 US$ |

Paghi al secondo, senza costi minimi. Trovi il listino completo in [/llms/pricing.md](https://console.kolwrite.com/llms/pricing.md).

## Documentazione per le macchine

- [llms.txt](https://console.kolwrite.com/llms.txt): indica quale chiamata e quale modello scegliere in base al caso d’uso.
- [llms-full.txt](https://console.kolwrite.com/llms-full.txt): tutta la documentazione raccolta in un singolo file Markdown.
- [openapi.json](https://console.kolwrite.com/openapi.json): specifica OpenAPI 3.1 per generare codice e definire i tool.
- [agent-instructions.md](https://console.kolwrite.com/agent-instructions.md): contiene il prompt, gli ID dei modelli e gli errori comuni da evitare.
- Ogni pagina del sito è disponibile anche in formato Markdown, basta aggiungere `.md` alla fine dell’URL.

## Domande e risposte

### Un agente IA può creare un account o una chiave API di KolWrite?

No. La registrazione e la creazione della chiave devono essere fatte da una persona. L’agente si limita a leggere la chiave da una variabile d’ambiente.

### Quale modello dovrebbe usare di default un agente?

Conviene usare `oracle` per l’audio in produzione, `base` per spendere meno quando l’audio è pulito e `oracle_mini` se serve anche una traduzione a basso costo. Specifica sempre il parametro `model`, altrimenti viene usato di default il vecchio modello `core`.

### Un agente IA può montare video con KolWrite?

Sì, se l’agente ha la possibilità di eseguire comandi. Richiede all’API la trascrizione con i timestamp per parola, seleziona le parti da tenere ed esegue il taglio con ffmpeg. Trovi il codice pronto nella [guida dedicata](https://console.kolwrite.com/it/guides/video-editing-with-ai).

### Esiste un server MCP o un SDK?

Al momento della scrittura non sono pubblicati né un pacchetto SDK né un server MCP. Gli agenti chiamano l’API REST con curl o Python, oppure usano la [definizione di strumento](https://console.kolwrite.com/it/guides/transcription-tool-for-ai-agents); [openapi.json](https://console.kolwrite.com/openapi.json) funziona con i generatori di codice.

### Posso chiamare l’API da un’app solo front-end creata con Lovable, Bolt o v0?

Non esponendo la chiave nel browser. Passa dalle funzioni server o edge messe a disposizione dalla piattaforma per chiamare KolWrite e tenere la chiave al sicuro.

## Pagine correlate

- [Sviluppatori e team di prodotto](https://console.kolwrite.com/it/use-cases/developers)
- [Media, podcast e sottotitoli](https://console.kolwrite.com/it/use-cases/media)
- [Call center e chiamate di vendita](https://console.kolwrite.com/it/use-cases/call-centers)
- [Lingue supportate](https://console.kolwrite.com/it/languages/)

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