API Grok STT e TTS: trascrivi, narra e scarica

Usa Grok STT per trascrivere una registrazione esistente e Grok TTS per far leggere un copione a una voce predefinita. Prova prima entrambi nel Playground di SpicyAPI, poi richiamali da codice o da un agente. È un flusso basato su file salvati; per una conversazione vocale in tempo reale serve un trasporto realtime. STT costa circa 0,002 $ al minuto di audio; TTS 0,018 $ ogni 1.000 caratteri. Secondo i nostri test di settembre 2026, entrambe le route elaborano registrazioni e copioni per adulti così come sono scritti, senza rifiuti, mascheramenti o clip troncate.

Prezzi, limiti e cosa restituisce ogni route

Una registrazione più lunga o più grande richiede un URL pubblico. Un URL può anche puntare a M4A, FLAC, OGG, Opus, AAC, MP4 o MKV, ma deve restituire il file audio stesso, non un player né una pagina di condivisione. STT non accetta PCM, μ-law e A-law privi di intestazione.

Un'ora di audio costa circa 0,12 $ e una registrazione di 90 secondi circa 0,003 $. Il task trattiene prima il massimo di due ore, circa 0,24 $, e libera la differenza quando è nota la durata reale. Un copione di 1.800 caratteri costa 0,0324 $; due take completi più una ripresa da 240 caratteri costano 0,06912 $. Spazi, punteggiatura e tag di dizione contano come caratteri, e il preventivo mostrato prima di un'esecuzione TTS è l'addebito finale.

Prova prima nel Playground

Trascrivere. Apri la pagina di Grok STT e resta nella scheda Playground.

1. In Input audio carica il tuo MP3 o WAV (fino a 90 MB) oppure passa a Asset URL e premi Add URL per una registrazione ospitata altrove.
2. Apri Advanced parameters solo se ti servono Language, Normalize text, Key terms, Keep filler words o Transcribe channels separately.
3. Controlla la stima del prezzo, accedi ed esegui. La trascrizione compare nel pannello Output, con una vista JSON per i tempi delle parole.

Narrare. Apri la pagina di Grok TTS.

1. Incolla o modifica il copione in Text (il pulsante Sample script inserisce un esempio), con gli eventuali tag di dizione.
2. Scegli una Voice; il menu indica di ciascuna nome, genere e lingua. In Advanced parameters trovi Speed, Output format, Bitrate e Language.
3. Esegui, ascolta il take nel pannello Output e usa Download per conservarlo.

Prova qui il tuo nome o la tua frase più difficile prima di scrivere uno script per un'intera narrazione; ciò che nel Playground suona male suonerà male anche dall'API.

Opzioni di trascrizione che cambiano il risultato

Language (language) può essere omesso per il rilevamento automatico. Normalize text (text_normalization) scrive numeri, prezzi e date in cifre («March 14», «$1,250») e richiede language; lascialo disattivato se ti servono le parole esattamente come pronunciate.

Keep filler words (filler_words: true) mantiene gli «ehm» e «uhm», che per impostazione predefinita vengono eliminati. Key terms (keyterms) orientano l'ortografia verso nomi inventati e marchi, fino a 100 termini di 50 caratteri. Inviali come oggetti, [{"term":"Mara"},{"term":"Jon"}], non come semplici stringhe.

Transcribe channels separately (multichannel: true) trascrive separatamente ogni canale di un file, fino a otto. Con l'opzione disattivata, una registrazione stereo con un parlante diverso per lato può tornare senza uno di loro. Leggi output.transcript.channels per parole e tempi di ciascun lato; il testo combinato è una riga per canale, non un dialogo finito. Non separa due persone mixate in un unico canale mono, e la route non restituisce etichette dei parlanti: per interviste mono usa canali registrati separatamente o uno strumento di diarizzazione.

Poi richiamalo da codice

Installa l'SDK Python (pip install spicyapi, Python 3.11+), imposta SPICY_API_KEY ed esegui questo flusso dalla trascrizione alla narrazione. Sostituisci il percorso del file con una registrazione che hai il diritto di usare.

import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

# 1. Transcribe a local recording (uploads are free and kept for one day)
source = client.upload_file("./interview.mp3")
stt = client.create_task(
    model="xai/grok-stt/speech-to-text",
    input_data={"audio_url": source["uri"], "multichannel": True},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
done = client.wait_for_terminal(stt["taskId"])
if done["state"] != "succeeded":
    raise RuntimeError(f"STT task {stt['taskId']} ended as {done['state']}")
print(done["output"]["text"])  # edit this into your script

# 2. Narrate the edited script
script = "Chapter Three. The storm kept them in the cabin. [breath] <slow>Neither of them pretended to be reading.</slow>"
tts = client.create_task(
    model="xai/grok-tts/text-to-speech",
    input_data={"text": script, "voice_id": "rex", "language": "en", "speed": 0.9},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
final = client.wait_for_terminal(tts["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"TTS task {tts['taskId']} ended as {final['state']}")

# 3. Copy the MP3 link to your own storage now; generated audio is kept for 14 days
print(output_assets(final)[0]["url"])

Riutilizza una chiave di idempotenza solo per ritentare la stessa richiesta dopo una risposta persa. Upload, attesa, errori, nuovi tentativi e rinnovo di un link di download scaduto sono descritti nel riferimento dell'SDK Python e nella guida ai task.

Oppure lascia fare a un agente

Se vuoi che sia un assistente a trascrivere e narrare, dagli la CLI o il server MCP. Entrambi mostrano il prezzo e chiedono la tua conferma prima di una chiamata a pagamento. La Skill aggiunge istruzioni sopra l'uno o l'altro.

• CLI. spicyapi esegue un task dal terminale (npx @spicyapi/cli funziona senza installazione):

``bash spicyapi files upload ./interview.mp3 # prints a spicy:// URI spicyapi tasks create --model xai/grok-stt/speech-to-text \ --input-json '{"audio_url": "spicy://YOUR-UPLOAD-URI", "multichannel": true}' --wait ``

• Server MCP. Aggiungi il server MCP al tuo assistente, poi chiedi: «Transcribe ./interview.mp3 with Grok STT, with each channel separate.» Chiama spicyapi_upload_file, poi spicyapi_task_create (che si ferma per la tua conferma del prezzo) e infine spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill installa l'Agent Skill, che insegna a un assistente di programmazione a leggere lo schema aggiornato e a riutilizzare le chiavi di idempotenza. Da sola non può eseguire task: usala insieme alla CLI o a MCP.

Dalla trascrizione al copione alla voce

Modifica la trascrizione prima della sintesi: correggi nomi, punteggiatura e tutto ciò che vuoi far leggere diversamente. Una breve lista di key term vale la pena per i nomi inventati, ma la trascrizione riflette comunque ciò che dice la registrazione, quindi verifica i nomi sull'audio.

TTS offre 71 voci predefinite. eve è quella predefinita; eve, ara, leo, rex e sal parlano tutte le lingue supportate, mentre le altre 66 sono tarate su una sola lingua e nell'API compaiono come ID opachi. Sceglile dal menu delle voci nella pagina del modello Grok TTS, che indica di ciascuna nome, genere e lingua. Prova un breve passaggio con il tuo nome più difficile prima di sintetizzare un'intera narrazione.

La dizione si scrive nel copione. I tag inline producono un suono dove li inserisci: [pause], [long-pause], [breath], [inhale], [exhale], [sigh], [laugh], [chuckle], [giggle], [cry]. I tag che racchiudono il testo cambiano il modo in cui vengono lette le parole al loro interno: <whisper>, <soft>, <slow>, <loud>, <build-intensity> e altri. I tag vengono eseguiti, non letti ad alta voce, ma contano nel prezzo. Per esempio:

{"text": "Chapter Three. The storm kept them in the cabin for two more days. [breath] By the second night, <slow>neither of them pretended to be reading anymore.</slow>", "voice_id": "rex", "speed": 0.9, "language": "en"}

speed va da 0,7 a 1,5. bitrate vale solo per MP3. Usa MP3 per la riproduzione e WAV per il montaggio; i formati grezzi pcm, mulaw e alaw a 8 kHz sono pensati per i sistemi telefonici e non si riproducono nel browser. SSML non è supportato; usa i tag sopra.

Per una scena con due personaggi, sintetizza separatamente le battute di ciascun parlante con voci diverse e montale insieme; una richiesta legge una sola voce. Lascia pause naturali nei punti di giunzione invece di ridurle a zero.

Per controllare un take, ripassa l'audio generato attraverso STT e confrontalo con il copione: parole mancanti o cambiate, una fine troncata o un tag pronunciato ad alta voce di solito emergono, e una clip breve costa una frazione di centesimo. Poi ascolta l'inizio, la fine e ogni riga segnalata. Se le voci predefinite di Grok non bastano, nel catalogo dei modelli trovi altre opzioni vocali; il confronto «Uncensored text-to-speech APIs compared» per ora esiste solo in inglese.

Problemi comuni e soluzioni

I timestamp delle parole di STT appartengono alla registrazione originale. TTS restituisce audio senza tempi per parola, quindi cambiare testo o velocità invalida i vecchi timestamp; allinea i sottotitoli al take sintetizzato finale.