API voor videotranscriptie en notities

Snelstart

Deze stappen brengen een bestand van je schijf naar een transcriptie en notities. Je hebt een actief Basic- of Plus-abonnement nodig, een terminal en, voor de voorbeeldclient, Python 3.12 of nieuwer.

1. Maak een API-sleutel

Meld je aan op de website (bijvoorbeeld op de prijspagina), open API-sleutels in de accountbalk, geef de sleutel een naam en stel desgewenst een vervaldatum in. Kopieer het geheim zodra het verschijnt: het wordt maar één keer getoond. Er kunnen maximaal drie sleutels tegelijk actief zijn.

2. Bewaar de sleutel in een omgevingsvariabele

Houd de sleutel uit broncode, opdrachtregelargumenten en logs. De voorbeelden lezen de sleutel uit VTN_API_KEY en de basis-URL uit 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. Controleer je account

Deze aanroep bevestigt dat de sleutel werkt en geeft je abonnement, je resterende abonnementsseconden, de ondersteunde formaten en de huidige limieten terug.

# 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. Transcribeer een bestand

Download de Python-voorbeeldclient. Hij heeft alleen de standaardbibliotheek nodig. Hij uploadt het bestand in delen, start de taak, wacht tot die klaar is en slaat elke resultaatpagina op.

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

Wil je maar een deel van een opname verwerken, voeg dan --start en --end toe in seconden vanaf het begin van het bestand. --audio-language geeft een taalhint en --notes-language kiest de taal van de notities. Zonder deze opties wordt het hele bestand verwerkt en worden de talen automatisch herkend.

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

Het statusbestand bewaart de upload-ID en de identiteit van het verzoek, nooit de sleutel. Stopt de opdracht, voer haar dan opnieuw uit met hetzelfde statusbestand: ze vindt dezelfde taak terug en er wordt niets dubbel gerekend. Gebruik voor elke nieuwe taak een nieuw statusbestand.

5. Lees de resultaten

meeting.jsonl bevat één JSON-resultaatpagina per regel: transcriptietekst met tijden, notities in Markdown, hiaten en waarschuwingen. meeting-files bevat de downloads, zoals de transcriptie als TXT en de notities als Markdown, HTML en PDF. De client heeft ook deze opdrachten:

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

Liever curl? De Bash-snelstart voert dezelfde stappen voor upload, taak en resultaat uit met curl en jq.

bash quickstart.sh meeting.mp4

Zo werkt een taak

Elke integratie volgt dezelfde zes stappen. De API-referentie toont elke aanroep met een voorbeeldverzoek en een voorbeeldantwoord.

1. Controleer het account. GET /api/v1/account geeft je abonnement, de resterende seconden, de ondersteunde formaten en de limieten terug.
2. Maak een upload. POST /api/v1/uploads met de bestandsgrootte in bytes en de bestandsextensie. Het antwoord noemt de grootte van de delen en het aantal delen.
3. Upload de delen. Haal ondertekende URL’s op met POST /api/v1/uploads/{upload_id}/parts, stuur elk deel met een HTTP-PUT rechtstreeks naar de opslag, bewaar elke ETag en roep daarna POST /api/v1/uploads/{upload_id}/complete aan.
4. Start de taak. POST /api/v1/jobs met de upload-ID en een Idempotency-Key-header. De server controleert het echte bestand, plant het werk en reserveert de tijd in je abonnement.
5. Vraag de status op. GET /api/v1/jobs/{job_id} tot de status definitief is, en wacht tussen aanroepen minstens poll_after_seconds.
6. Lees het resultaat. GET /api/v1/jobs/{job_id}/result en volg next_cursor tot die null is. Download de bestanden in artifacts voordat hun links verlopen.

Een taak eindigt als completed, completed_with_gaps, interrupted, cancelled, failed of expired. charged_seconds toont hoeveel van je abonnement de taak heeft gebruikt.

Best practices

Deze gewoonten houden je sleutels veilig, voorkomen dubbele kosten en maken lange taken betrouwbaar.

Houd sleutels geheim

• Roep de API alleen aan vanaf een server of script dat je zelf beheert. Zet een sleutel nooit in browsercode, een mobiele app, een URL of versiebeheer.
• Laad de sleutel uit een omgevingsvariabele of een secretmanager en houd hem uit logs, foutrapporten en opdrachtregelargumenten.
• Gebruik één sleutel per integratie met een vervaldatum, zodat je een sleutel kunt vervangen of intrekken zonder de andere aan te raken.
• Om een sleutel te vervangen maak je de nieuwe, zet je die in gebruik en trek je daarna de oude in. Taken die al gestart zijn, lopen door.
• Kan een sleutel zijn uitgelekt, bijvoorbeeld in een chat, een ticket of een commit, trek hem dan meteen in via het paneel API-sleutels.

Maak het aanmaken van taken veilig herhaalbaar

• Genereer voor elke nieuwe taak een willekeurige Idempotency-Key, zoals een UUID, en sla die op met de upload-ID voordat je het verzoek verstuurt.
• Gaat het antwoord verloren, stuur dan hetzelfde verzoek met dezelfde sleutel opnieuw. Je krijgt de oorspronkelijke taak terug en betaalt niet dubbel.
• Gebruik een sleutel nooit opnieuw voor een ander bestand of andere opties: de API antwoordt dan met 409 IDEMPOTENCY_CONFLICT.

Vraag beleefd op en houd rekening met limieten

• Wacht minstens vijf seconden tussen statusaanroepen, en langer als poll_after_seconds daarom vraagt.
• Wacht bij 429 of 503 op de header Retry-After of error.retry_after_seconds en probeer het daarna opnieuw met een kleine willekeurige vertraging.
• Herhaal een verzoek alleen ongewijzigd als error.retryable true is. Pas anders eerst het verzoek aan.
• Een account voert één upload en één taak tegelijk uit. Zet je bestanden in een wachtrij en stuur het volgende als de huidige taak klaar is.

Houd je urenverbruik in de hand

• Controleer remaining_seconds voordat je uploadt. Een taak die meer tijd nodig heeft dan je hebt, mislukt met INSUFFICIENT_BALANCE; de API kort je selectie nooit in om haar te laten passen.
• Stuur een range mee als je maar een deel van een opname nodig hebt. Alleen de geselecteerde audio wordt gerekend.
• Annuleer taken die je niet meer nodig hebt. Voltooide delen blijven beschikbaar en gereserveerde tijd die niet is gebruikt, krijg je terug.
• Breek uploads af die je niet gaat gebruiken, zodat de volgende upload kan starten.

Verzamel volledige resultaten

• Volg next_cursor tot die null is. Een pagina bevat maximaal 32 items.
• Behandel gap-items als audio die niet verwerkt kon worden, niet als stilte, en controleer de warnings.
• Download de bestanden in artifacts zolang hun links geldig zijn (tot tien minuten); vraag de pagina opnieuw op voor nieuwe links.
• Bewaar wat je nodig hebt: resultaatbestanden worden ongeveer 24 uur bewaard en het herstel van de transcriptie ongeveer 48 uur.
• Lees de velden die je nodig hebt en negeer de rest.

Veelgestelde vragen

Bestanden en voorbeelden

De voorbeelden en contractbestanden worden met de website gepubliceerd en komen overeen met de live API.

• client.py: voorbeeldclient voor Python 3.12+, alleen de standaardbibliotheek
• quickstart.sh: Bash-voorbeeld met curl en jq
• openapi.json: OpenAPI 3.1-beschrijving van elk endpoint, met voorbeelden
• paid-api.schema.json: JSON Schema van elk verzoek en antwoord

Hulp

Iets onduidelijk of werkt het niet? Neem contact op en vermeld de request_id uit het foutantwoord, het tijdstip en het endpoint. Stuur ons nooit je API-sleutel.