API til videotransskription og noter

Kom hurtigt i gang

Disse trin fører en fil fra din disk til en transskription og noter. Du skal bruge et aktivt Basic- eller Plus-abonnement, en terminal og, til eksempelklienten, Python 3.12 eller nyere.

1. Opret en API-nøgle

Log ind på webstedet (for eksempel på prissiden), åbn API-nøgler i kontolinjen, giv nøglen et navn og angiv eventuelt en udløbsdato. Kopiér hemmeligheden, når den vises: den vises kun én gang. Op til tre nøgler kan være aktive ad gangen.

2. Gem nøglen i en miljøvariabel

Hold nøglen ude af kildekode, kommandolinjeargumenter og logfiler. Eksemplerne læser nøglen fra VTN_API_KEY og basis-URL’en fra 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. Tjek din konto

Dette kald bekræfter, at nøglen virker, og returnerer dit abonnement, dine resterende abonnementssekunder, de understøttede formater og de aktuelle grænser.

# 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. Transskribér en fil

Download eksempelklienten i Python. Den kræver kun standardbiblioteket. Den uploader filen i dele, starter jobbet, venter på det og gemmer hver resultatside.

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

Vil du kun behandle en del af en optagelse, tilføjer du --start og --end i sekunder fra filens begyndelse. --audio-language giver et sproghint, og --notes-language vælger notesproget. Uden disse indstillinger behandles hele filen, og sprogene genkendes automatisk.

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

Statusfilen gemmer upload-id’et og anmodningens identitet, aldrig nøglen. Hvis kommandoen stopper, kører du den igen med den samme statusfil: den finder det samme job, og du bliver ikke opkrævet to gange. Brug en ny statusfil til hvert nyt job.

5. Læs resultaterne

meeting.jsonl indeholder én JSON-resultatside pr. linje: transskriptionstekst med tider, noter i Markdown, huller og advarsler. meeting-files indeholder downloadene, for eksempel transskriptionen som TXT og noterne som Markdown, HTML og PDF. Klienten har også disse kommandoer:

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

Foretrækker du curl? Bash-lynstarten kører de samme trin for upload, job og resultat med curl og jq.

bash quickstart.sh meeting.mp4

Sådan fungerer et job

Alle integrationer følger de samme seks trin. API-referencen viser hvert kald med et eksempel på en anmodning og et svar.

1. Tjek kontoen. GET /api/v1/account returnerer dit abonnement, de resterende sekunder, de understøttede formater og grænserne.
2. Opret en upload. POST /api/v1/uploads med filstørrelsen i byte og filtypenavnet. Svaret angiver størrelsen på delene og antallet af dele.
3. Upload delene. Hent signerede URL’er med POST /api/v1/uploads/{upload_id}/parts, send hver del med en HTTP-PUT direkte til lageret, gem hvert ETag, og kald derefter POST /api/v1/uploads/{upload_id}/complete.
4. Start jobbet. POST /api/v1/jobs med upload-id’et og en Idempotency-Key-header. Serveren tjekker den faktiske fil, planlægger arbejdet og reserverer tiden i dit abonnement.
5. Spørg efter status. GET /api/v1/jobs/{job_id}, indtil tilstanden er endelig, og vent mindst poll_after_seconds mellem kaldene.
6. Læs resultatet. GET /api/v1/jobs/{job_id}/result, og følg next_cursor, indtil den er null. Download filerne i artifacts, før deres links udløber.

Et job ender som completed, completed_with_gaps, interrupted, cancelled, failed eller expired. charged_seconds viser, hvor meget af dit abonnement jobbet har brugt.

God praksis

Disse vaner beskytter dine nøgler, forhindrer dobbeltopkrævning og gør lange job pålidelige.

Hold nøglerne hemmelige

• Kald kun API’et fra en server eller et script, du selv styrer. Læg aldrig en nøgle i browserkode, en mobilapp, en URL eller versionsstyring.
• Indlæs nøglen fra en miljøvariabel eller en hemmelighedsmanager, og hold den ude af logfiler, fejlrapporter og kommandolinjeargumenter.
• Brug én nøgle pr. integration med en udløbsdato, så du kan udskifte eller tilbagekalde én nøgle uden at røre de andre.
• For at udskifte en nøgle opretter du den nye, tager den i brug og tilbagekalder derefter den gamle. Job, der allerede er startet, kører videre.
• Hvis en nøgle kan være lækket, for eksempel i en chat, en sag eller et commit, så tilbagekald den straks i panelet API-nøgler.

Gør oprettelse af job sikker at gentage

• Generér en tilfældig Idempotency-Key, for eksempel et UUID, til hvert nyt job, og gem den sammen med upload-id’et, før du sender anmodningen.
• Hvis svaret går tabt, sender du den samme anmodning med den samme nøgle igen. Du får det oprindelige job tilbage og betaler ikke to gange.
• Genbrug aldrig en nøgle til en anden fil eller andre indstillinger: API’et svarer så med 409 IDEMPOTENCY_CONFLICT.

Spørg med måde og håndtér grænser

• Vent mindst fem sekunder mellem statuskald, og længere, når poll_after_seconds beder om det.
• Ved 429 eller 503 venter du som angivet i headeren Retry-After eller i error.retry_after_seconds og prøver derefter igen med en lille tilfældig forsinkelse.
• Gentag kun en anmodning uændret, når error.retryable er true. Ellers skal du rette anmodningen først.
• En konto kører én upload og ét job ad gangen. Sæt dine filer i kø, og send den næste, når det aktuelle job er færdigt.

Styr, hvor mange timer du bruger

• Tjek remaining_seconds, før du uploader. Et job, der kræver mere tid, end du har, mislykkes med INSUFFICIENT_BALANCE; API’et forkorter aldrig dit udvalg, så det passer.
• Send et range, når du kun skal bruge en del af en optagelse. Kun den valgte lyd opkræves.
• Annullér job, du ikke længere har brug for. Færdige dele forbliver tilgængelige, og reserveret tid, der ikke blev brugt, gives tilbage.
• Afbryd uploads, du ikke vil bruge, så den næste upload kan starte.

Hent fuldstændige resultater

• Følg next_cursor, indtil den er null. En side indeholder højst 32 elementer.
• Behandl gap-elementer som lyd, der ikke kunne behandles, ikke som stilhed, og tjek warnings.
• Download filerne i artifacts, mens deres links er gyldige (op til ti minutter); hent siden igen for at få nye links.
• Gem det, du har brug for: resultatfiler opbevares i cirka 24 timer og gendannelse af transskriptionen i cirka 48 timer.
• Læs de felter, du har brug for, og ignorér resten.

Ofte stillede spørgsmål

Filer og eksempler

Eksemplerne og kontraktfilerne udgives sammen med webstedet og svarer til API’et i drift.

• client.py: eksempelklient til Python 3.12+, kun standardbiblioteket
• quickstart.sh: Bash-eksempel med curl og jq
• openapi.json: OpenAPI 3.1-beskrivelse af hvert endpoint, med eksempler
• paid-api.schema.json: JSON Schema for hver anmodning og hvert svar

Hjælp

Er noget uklart, eller virker det ikke? Kontakt os, og angiv request_id fra fejlsvaret, tidspunktet og endpointet. Send aldrig din API-nøgle til os.