Trascrizione automatica per agenti e script

La trascrizione automatica in Hushscript trasforma una registrazione audio esistente in una trascrizione modificabile. Nell’app per browser puoi anche partire da un video locale: Hushscript prepara l’audio sul tuo dispositivo e invia solo quello per il riconoscimento online. Rivedi e correggi il risultato tu stesso: il servizio non fornisce trascrizioni revisionate da una persona o certificate.

Come funziona la trascrizione automatica

1. Prepara la registrazione. Usa un file audio, importa un link audio compatibile o registra la tua voce nell’app per browser. Per le registrazioni video, scegli un file locale affinché l’app possa preparare l’audio sul tuo dispositivo.
2. Invia e attendi la trascrizione. L’app gestisce il caricamento e lo stato. Un agente può caricare l’audio preparato in parti tramite REST API oppure usare gli strumenti MCP con gli scope necessari, poi controllare il processo finché la trascrizione non è pronta.
3. Rivedi ed esporta. Modifica la trascrizione e le etichette dei parlanti nell’app oppure recupera il testo tramite API. Il token di un agente può anche esportare la trascrizione nei limiti degli scope concessi.

Software di trascrizione automatica per audio e video

Il software di trascrizione automatica di Hushscript trasforma il parlato registrato in testo che puoi cercare, modificare ed esportare. La funzione di registrazione nell’app permette anche di registrare la voce prima della trascrizione. Per ottenere un file registrato senza trascrizione, usa il registratore vocale gratuito.

La trascrizione automatica dei video segue lo stesso flusso di lavoro sul testo dopo che l’app ha estratto o convertito l’audio sul dispositivo. L’esempio di caricamento REST qui sotto parte da audio preparato; per fornire invece all’app un file video locale, usa il flusso nel browser descritto in Da video a testo.

Posso provare la trascrizione automatica gratuitamente?

Sì. L’anteprima pubblica trascrive fino a cinque minuti da un file, un link audio compatibile o una registrazione nel browser prima dell’accesso; anche un video locale funziona una volta che il browser ne ha preparato l’audio. La trascrizione completa richiede un account: un account personale idoneo riceve 30 minuti gratuiti dopo la verifica della carta (vedi Prezzi per sapere come funziona), mentre un account macchina non riceve i minuti di benvenuto e parte dal pacchetto acquistato alla registrazione.

Automatizza le trascrizioni con API o MCP

L’app per browser serve a lavorare direttamente con le registrazioni. Per automatizzare le trascrizioni, la REST API e il server MCP consentono a un agente di caricare audio preparato, controllare i processi, recuperare le trascrizioni ed esportare i risultati. Un agente può aprire il proprio account con un flusso che inizia dal pagamento, senza un titolare umano; il checkout ospitato richiede comunque un browser e l’emittente della carta può richiedere un passaggio di autenticazione. Una persona può invece creare nell’app un token con scope specifici da un account esistente. Questa guida segue l’account macchina dalla registrazione alla rotazione delle credenziali.

Registrati

POST /v1/agent/accounts avvia una registrazione headless. Non esiste ancora nessun account, nessun cookie e nessun token: solo un acquisto in sospeso.

curl -X POST https://api.hushscript.com/v1/agent/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "ops@example-agent.dev",
    "pack_id": "300min",
    "accept_terms_version": "2026-10-20",
    "agent": {
      "name": "research-crawler",
      "platform": "langgraph",
      "contact_url": "https://example-agent.dev/bots/research-crawler"
    }
  }'

{
  "signup_id": "hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061",
  "claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6",
  "pack": "300min",
  "amount": 599,
  "currency": "usd",
  "expires_at": 1789112400
}

contact_email serve solo per ricevute e avvisi, mai per l’accesso. pack_id è uno tra 45min, 300min, 900min, 1800min, 6000min; non inviare mai tu stesso amount o currency, entrambi sono derivati dal pacchetto lato server. Solo i due pacchetti più piccoli, 45min e 300min, possono essere acquistati in fase di registrazione. Un pack_id più grande viene rifiutato, e il rifiuto include details.allowed_packs, che elenca cosa questo account può acquistare in questo momento, così chi chiama può riprovare senza procedere per tentativi. Gli altri pacchetti si sbloccano con l’anzianità, non con il volume degli acquisti: vedi Cosa può acquistare un account nuovo più sotto. accept_terms_version deve corrispondere esattamente alla versione attuale delle policy del server, altrimenti la chiamata fallisce con policy_version_stale, che indica il valore attuale nel corpo della risposta. Un suggerimento opzionale data_region viene rispettato solo se concorda con la regione già implicata dalla tua posizione di rete. Un dry_run: true opzionale convalida tutto senza creare una sessione Stripe e senza addebiti; il suo signup_id ha il prefisso dry_ e non può mai essere attivato.

claim_secret viene mostrato esattamente una volta, in questa risposta. Hushscript ne conserva solo l’hash. Perderlo prima della chiamata di attivazione significa perdere la registrazione: non esiste una procedura di recupero per questo segreto. Una registrazione pagata ma non attivata entra nel processo di rimborso descritto più sotto; non può essere recuperata tramite una ricerca.

Completa il pagamento nel tuo browser

checkout_url è una pagina ospitata di Stripe Checkout. La registrazione richiede un browser per questo passaggio, che non deve necessariamente appartenere a una persona: un agente può gestirlo con la propria automazione (compilare i campi della carta, inviare e seguire il redirect). Hushscript non vede mai i dati della carta; li vede Stripe. Hai 30 minuti per completare il pagamento e poi attivare l’account, come indica il valore expires_at riportato sopra.

Una procedura oraria controlla le registrazioni pagate ma non attivate dopo la finestra di attivazione di 30 minuti e un’ulteriore ora di tolleranza. Tenta un rimborso completo, perché i minuti vengono accreditati solo all’attivazione. I tentativi di rimborso non riusciti vengono ripetuti e possono richiedere un intervento manuale; il rimborso non è garantito entro un momento preciso.

Attiva l’account

POST /v1/agent/accounts/{signup_id}/claim trasforma una registrazione pagata e non attivata in un account vero, con un’unica chiamata.

curl -X POST https://api.hushscript.com/v1/agent/accounts/hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d"}'

{
  "user_id": "usr_7d1a2b3c4d5e6f708192a3b4c5d6e7f8",
  "pat": "hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "balance_seconds": 18000
}

L’attivazione crea esattamente un account, associato internamente a un’identità di accesso sintetica e non risolvibile, e accredita il pacchetto pagato esattamente una volta, per quante volte venga ripetuta la richiesta. Genera un PAT: il valore pat mostrato sopra.

Se la risposta va persa, ripeti la chiamata con lo stesso claim_secret. Entro un’ora dall’attivazione, e finché il token emesso non è mai stato usato, la ripetizione restituisce 201 per lo stesso account, con la stessa forma di risposta e un pat nuovo. Il token perso smette di funzionare. Dopo il primo uso del token, o dopo quell’ora, una ripetizione risponde agent_claim_invalid. Una ripetizione che si sovrappone a un’attivazione ancora in corso può ricevere 429 rate_limited con un header Retry-After; riprova dopo quel ritardo.

Il primo token può trascrivere, leggere e modificare trascrizioni, esportare, leggere il saldo dell’account, acquistare minuti e ruotare sé stesso. Non concede scope per Insights, contesto, organizzazioni o scrittura delle impostazioni. Il server MCP offre solo gli strumenti coperti dagli scope del token.

Un segreto errato, un signup_id sconosciuto, una registrazione rimborsata, una scaduta e un’attivazione ripetuta il cui token è già stato usato o la cui ora è trascorsa rispondono tutti con lo stesso errore agent_claim_invalid. Non c’è modo per chi chiama di distinguerle dalla risposta, di proposito. Solo una volta che il segreto stesso risulta valido entra in gioco lo stato del pagamento: una Checkout Session non ancora liquidata risponde invece con wrong_state.

Il balance_seconds mostrato sopra è l’intero saldo iniziale. Gli account agente non ricevono alcun bonus di benvenuto né minuti gratuiti dalla verifica della carta come invece accade per il primo account di una persona; partono solo dal pacchetto che hanno pagato. È una scelta deliberata, non una lacuna: l’account era già stato pagato prima ancora di esistere.

Acquista altri minuti

Da qui in poi l’account usa l’interfaccia /v1/ che /developers documenta per intero.

curl -X POST https://api.hushscript.com/v1/billing/purchase \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "pack": "300min",
    "quick_payment_method_id": "pm_1PqR2sT3uV4wX5yZ",
    "idempotency_key": "purchase-2026-09-11-01"
  }'

{
  "balance_seconds": 36000
}

Serve lo scope billing, già concesso dalla risposta di attivazione mostrata sopra. L’attivazione abilita anche la fatturazione sul token e sull’account; un token creato da una persona richiede lo scope billing e l’abilitazione di entrambe le impostazioni di fatturazione. Le chiamate di fatturazione con PAT condividono un limite più stretto di 60 richieste al minuto per account tra le rotte di fatturazione che contattano Stripe, prima di effettuare le richieste a Stripe.

Cosa può acquistare un account nuovo

La dimensione dei pacchetti si sblocca in base all’anzianità dei pagamenti liquidati, non in base a quanto spende un account. Un acquisto conta per il livello successivo solo una volta trascorsi 7 giorni dalla propria data di pagamento, quindi un account appena creato non può raggiungere i pacchetti più grandi acquistando in fretta.

Un acquisto rifiutato indica l’insieme attuale in details.allowed_packs invece di fallire alla cieca. La chiamata di registrazione applica la prima riga di quella tabella, motivo per cui la guida qui sopra acquista 300min e non qualcosa di più grande. Separatamente da questi livelli, un limite di consumo su una finestra mobile di 24 ore limita quanto velocemente può essere speso il saldo che non ha ancora superato la finestra di contestazione. L’acquisto alla registrazione conta tra i tre tentativi di acquisto dell’account in una finestra mobile di 24 ore; contano anche i tentativi rifiutati dopo la prenotazione.

Trascrivi

Caricare e trascrivere seguono lo stesso flusso multipart di qualsiasi altro account. L’esempio API invia audio preparato; non carica il file originale di un video locale.

curl -X POST https://api.hushscript.com/v1/uploads \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 48213504,
    "duration_seconds": 1860,
    "title": "weekly-standup-2026-09-11",
    "idempotency_key": "upload-2026-09-11-01"
  }'

{
  "job_id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "part_urls": [
    { "n": 1, "url": "https://r2.hushscript.com/uploads/job_3a2b1c0d.../part-1?X-Amz-Signature=..." }
  ]
}

Esegui PUT di ogni parte sul suo URL prefirmato, poi esegui POST su /complete dello stesso job con n ed etag di ogni parte inviata in questo modo. Poi interroga periodicamente il job:

curl https://api.hushscript.com/v1/jobs/job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "state": "done",
  "transcript_id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180"
}

curl https://api.hushscript.com/v1/transcripts/trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180 \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180",
  "language": "en",
  "duration_seconds": 1860,
  "body": "..."
}

Ruota la credenziale

Un account macchina non ha password né una casella email utilizzabile, quindi non esiste un percorso di “password dimenticata” se un PAT trapela o deve semplicemente essere sostituito. La rotazione è quel percorso.

curl -X POST https://api.hushscript.com/v1/agent/credentials/rotate \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "pat": "hsr1:eu:pat.p9q8r7.1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "pat_id": "p9q8r7",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "expires_at": null
}

La chiamata non richiede un corpo. Genera un successore per il token che ha autenticato la richiesta. Il successore mantiene gli scope, il permesso di fatturazione, il nome, l’etichetta client e la policy di scadenza del predecessore. Questa rotta tocca solo il token di chi chiama: non può elencare, generare o revocare nessun’altra credenziale sull’account. È l’unico percorso di recupero delle credenziali che un account macchina possiede, quindi ruota prima che il vecchio token venga scartato, non dopo.

Il vecchio token non viene revocato subito. Dopo la rotazione funziona per una sola cosa: chiamare di nuovo rotate. Vale finché il nuovo token non effettua la sua prima richiesta riuscita o finché non trascorre un’ora, a seconda di quale evento arrivi prima. Su ogni altra rotta il vecchio token risponde 401 subito.

Se la risposta con il nuovo token va persa, richiama rotate con il vecchio token finché il nuovo non è stato usato. Ottieni un segreto nuovo per lo stesso pat_id, e il precedente nuovo segreto smette di funzionare.

Tieni il vecchio token finché il nuovo non ha funzionato una volta. Poi fai subito una chiamata con il nuovo token, per esempio GET /v1/account. Quella prima richiesta riuscita ritira il vecchio token per sempre.

Errori

Questi errori riguardano la registrazione degli agenti e i controlli sugli acquisti. Il limite di acquisto si applica anche agli acquisti con PAT su un account umano; un acquisto tramite una sessione umana è esente.

Una volta che il segreto di attivazione risulta valido, una Checkout Session non pagata risponde con wrong_state (4001) invece che con agent_claim_invalid. Il catalogo completo è il documento OpenAPI.

Limiti

Le chiamate sono limitate a 1.200 al minuto. Per un account agente quel budget appartiene all’account, non al singolo token: ogni credenziale nella catena di rotazione attinge dallo stesso budget, quindi ruotare un PAT non assegna al successore un’allocazione nuova. Le chiamate di fatturazione con PAT che raggiungono Stripe condividono un limite più stretto di 60 al minuto per account. Questo include configurazione e acquisto, modifiche della carta predefinita e rimozione, e richieste dell’elenco carte non servite dalla cache; il controllo precede la chiamata a Stripe. Il limite di acquisto di 24 ore visto sopra viene conteggiato allo stesso modo, per account e non per credenziale.

Per saperne di più

Questa pagina copre il ciclo di vita dell’account: aprirlo, finanziarlo e mantenere valida la credenziale. Per tutto quello che l’account può fare in seguito, vedi la REST API, incluso il documento OpenAPI completo, oppure il server MCP per lo stesso account tramite strumenti invece che HTTP grezzo.