Speech-to-text per agenti IA e vibe coder

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.

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:

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

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: 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: usa output_format: "srt" per ottenere sottotitoli anche tradotti, in formato WebVTT o impressi nel video con ffmpeg.
• API di trascrizione delle riunioni: trascrive le registrazioni distinguendo chi parla, così sono già pronte per estrarre verbali e attività da assegnare.
• API dei timestamp per parola: 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: 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, 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

Paghi al secondo, senza costi minimi. Trovi il listino completo in /llms/pricing.md.

Documentazione per le macchine

• llms.txt: indica quale chiamata e quale modello scegliere in base al caso d’uso.
• llms-full.txt: tutta la documentazione raccolta in un singolo file Markdown.
• openapi.json: specifica OpenAPI 3.1 per generare codice e definire i tool.
• 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