API di trascrizione video e appunti

Avvio rapido

Questi passaggi portano un file dal tuo disco a una trascrizione e agli appunti. Ti servono un piano Basic o Plus attivo, un terminale e, per il client di esempio, Python 3.12 o successivo.

1. Crea una chiave API

Accedi al sito (per esempio dalla pagina dei prezzi), apri Chiavi API nella barra dell’account, dai un nome alla chiave e, se vuoi, una data di scadenza. Copia il segreto appena compare: viene mostrato una sola volta. Possono essere attive fino a tre chiavi alla volta.

2. Salva la chiave in una variabile d’ambiente

Tieni la chiave fuori dal codice sorgente, dagli argomenti della riga di comando e dai log. Gli esempi leggono la chiave da VTN_API_KEY e l’URL di base da VTN_API_BASE.

export VTN_API_BASE="https://api.video-to-notes.com"
read -rs VTN_API_KEY && export VTN_API_KEY   # paste the key, press Enter

$env:VTN_API_BASE = "https://api.video-to-notes.com"
$env:VTN_API_KEY = Read-Host "API key" -MaskInput

3. Controlla il tuo account

Questa chiamata conferma che la chiave funziona e restituisce il tuo piano, i secondi rimanenti del piano, i formati supportati e i limiti attuali.

# Sends the key through stdin, so it never appears in the process list.
vtn() {
  printf 'header = "Authorization: Bearer %s"\n' "$VTN_API_KEY" |
    curl -s --config - "$@"
}

vtn "$VTN_API_BASE/api/v1/account"

$headers = @{ Authorization = "Bearer $env:VTN_API_KEY" }
Invoke-RestMethod "$env:VTN_API_BASE/api/v1/account" -Headers $headers |
  ConvertTo-Json -Depth 5

4. Trascrivi un file

Scarica il client di esempio in Python. Usa solo la libreria standard. Carica il file in più parti, avvia il processo, ne attende la fine e salva ogni pagina di risultati.

python client.py run meeting.mp4 --state meeting.state.json \
  --output meeting.jsonl --download meeting-files

Per elaborare solo una parte di una registrazione, aggiungi --start e --end in secondi dall’inizio del file. --audio-language fornisce un’indicazione sulla lingua e --notes-language sceglie la lingua degli appunti. Senza queste opzioni viene elaborato l’intero file e le lingue vengono rilevate automaticamente.

python client.py run lecture.webm --state lecture.state.json \
  --start 30 --end 3630 --audio-language ru --notes-language en

Il file di stato conserva l’ID del caricamento e l’identità della richiesta, mai la chiave. Se il comando si interrompe, rieseguilo con lo stesso file di stato: ritrova lo stesso processo e non ti viene addebitato nulla due volte. Usa un nuovo file di stato per ogni nuovo processo.

5. Leggi i risultati

meeting.jsonl contiene una pagina di risultati JSON per riga: testo della trascrizione con tempi, appunti in Markdown, lacune e avvisi. meeting-files contiene i download, come la trascrizione in TXT e gli appunti in Markdown, HTML e PDF. Il client ha anche questi comandi:

python client.py account
python client.py status JOB_ID
python client.py result JOB_ID --output results.jsonl --download files
python client.py cancel JOB_ID
python client.py resume JOB_ID

Preferisci curl? L’avvio rapido in Bash esegue gli stessi passaggi di caricamento, processo e risultato con curl e jq.

bash quickstart.sh meeting.mp4

Come funziona un processo

Ogni integrazione segue gli stessi sei passaggi. Il riferimento API mostra ogni chiamata con un esempio di richiesta e di risposta.

1. Controlla l’account. GET /api/v1/account restituisce il tuo piano, i secondi rimanenti, i formati supportati e i limiti.
2. Crea un caricamento. POST /api/v1/uploads con la dimensione del file in byte e la sua estensione. La risposta indica la dimensione delle parti e il loro numero.
3. Carica le parti. Ottieni URL firmati con POST /api/v1/uploads/{upload_id}/parts, invia ogni parte con un PUT HTTP direttamente nello storage, conserva ogni ETag e poi chiama POST /api/v1/uploads/{upload_id}/complete.
4. Avvia il processo. POST /api/v1/jobs con l’ID del caricamento e un’intestazione Idempotency-Key. Il server controlla il file reale, pianifica il lavoro e riserva il tempo del tuo piano.
5. Controlla lo stato. GET /api/v1/jobs/{job_id} finché lo stato è definitivo, aspettando almeno poll_after_seconds tra una chiamata e l’altra.
6. Leggi il risultato. GET /api/v1/jobs/{job_id}/result e segui next_cursor finché è null. Scarica i file elencati in artifacts prima che i loro link scadano.

Un processo termina come completed, completed_with_gaps, interrupted, cancelled, failed o expired. charged_seconds indica quanto del tuo piano ha usato il processo.

Buone pratiche

Queste abitudini proteggono le tue chiavi, evitano addebiti doppi e rendono affidabili i processi lunghi.

Tieni segrete le chiavi

• Chiama l’API solo da un server o da uno script che controlli. Non mettere mai una chiave nel codice del browser, in un’app mobile, in un URL o nel controllo di versione.
• Carica la chiave da una variabile d’ambiente o da un gestore di segreti e tienila fuori da log, segnalazioni di errore e argomenti della riga di comando.
• Usa una chiave per integrazione con una data di scadenza, così puoi sostituire o revocare una chiave senza toccare le altre.
• Per sostituire una chiave, crea quella nuova, distribuiscila e poi revoca quella vecchia. I processi già avviati continuano.
• Se una chiave potrebbe essere trapelata, per esempio in una chat, in un ticket o in un commit, revocala subito nel pannello Chiavi API.

Rendi sicura la ripetizione della creazione dei processi

• Genera una Idempotency-Key casuale, per esempio un UUID, per ogni nuovo processo e salvala con l’ID del caricamento prima di inviare la richiesta.
• Se la risposta va persa, invia di nuovo la stessa richiesta con la stessa chiave. Ricevi il processo originale e non paghi due volte.
• Non riutilizzare mai una chiave per un altro file o altre opzioni: l’API risponde con 409 IDEMPOTENCY_CONFLICT.

Interroga con moderazione e rispetta i limiti

• Aspetta almeno cinque secondi tra le richieste di stato, e di più se poll_after_seconds lo chiede.
• Con 429 o 503, aspetta quanto indicato dall’intestazione Retry-After o da error.retry_after_seconds, poi riprova con un piccolo ritardo casuale.
• Ripeti una richiesta invariata solo se error.retryable è true. Altrimenti correggi prima la richiesta.
• Un account esegue un caricamento e un processo alla volta. Metti i file in coda e invia il successivo quando il processo in corso è terminato.

Controlla le ore che usi

• Controlla remaining_seconds prima di caricare. Un processo che richiede più tempo di quello disponibile fallisce con INSUFFICIENT_BALANCE; l’API non accorcia mai la tua selezione per farla rientrare.
• Invia un range quando ti serve solo una parte di una registrazione. Viene addebitato solo l’audio selezionato.
• Annulla i processi che non ti servono più. Le parti completate restano disponibili e il tempo riservato non usato viene restituito.
• Interrompi i caricamenti che non userai, così può partire quello successivo.

Raccogli risultati completi

• Segui next_cursor finché è null. Una pagina contiene al massimo 32 elementi.
• Tratta gli elementi gap come audio che non è stato possibile elaborare, non come silenzio, e controlla i warnings.
• Scarica i file in artifacts finché i loro link sono validi (fino a dieci minuti); richiedi di nuovo la pagina per avere link nuovi.
• Salva ciò che ti serve: i file dei risultati vengono conservati per circa 24 ore e il recupero della trascrizione per circa 48 ore.
• Leggi i campi che ti servono e ignora gli altri.

Domande frequenti

File ed esempi

Gli esempi e i file del contratto vengono pubblicati con il sito e corrispondono all’API in produzione.

• client.py: client di esempio per Python 3.12+, solo libreria standard
• quickstart.sh: esempio in Bash con curl e jq
• openapi.json: descrizione OpenAPI 3.1 di ogni endpoint, con esempi
• paid-api.schema.json: JSON Schema di ogni richiesta e risposta

Assistenza

Qualcosa non è chiaro o non funziona? Contattaci indicando il request_id della risposta di errore, l’ora e l’endpoint. Non inviarci mai la tua chiave API.