API for videotranskripsjon og notater

Hurtigstart

Disse trinnene tar en fil fra disken din til en transkripsjon og notater. Du trenger et aktivt Basic- eller Plus-abonnement, en terminal og, for eksempelklienten, Python 3.12 eller nyere.

1. Opprett en API-nøkkel

Logg inn på nettstedet (for eksempel på prissiden), åpne API-nøkler i kontolinjen, gi nøkkelen et navn og angi eventuelt en utløpsdato. Kopier hemmeligheten når den vises: den vises bare én gang. Opptil tre nøkler kan være aktive samtidig.

2. Lagre nøkkelen i en miljøvariabel

Hold nøkkelen unna kildekode, kommandolinjeargumenter og logger. Eksemplene leser nøkkelen 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. Sjekk kontoen din

Dette kallet bekrefter at nøkkelen virker, og returnerer abonnementet ditt, de gjenværende abonnementssekundene, de støttede formatene og de gjeldende grensene.

# 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. Transkriber en fil

Last ned eksempelklienten i Python. Den trenger bare standardbiblioteket. Den laster opp filen i deler, starter jobben, venter på den og lagrer hver resultatside.

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

Vil du bare behandle en del av et opptak, legger du til --start og --end i sekunder fra starten av filen. --audio-language gir et språkhint, og --notes-language velger språket for notatene. Uten disse valgene behandles hele filen, og språkene gjenkjennes automatisk.

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

Tilstandsfilen lagrer opplastings-ID-en og identiteten til forespørselen, aldri nøkkelen. Hvis kommandoen stopper, kjører du den på nytt med den samme tilstandsfilen: den finner den samme jobben, og du blir ikke belastet to ganger. Bruk en ny tilstandsfil for hver nye jobb.

5. Les resultatene

meeting.jsonl inneholder én JSON-resultatside per linje: transkripsjonstekst med tider, notater i Markdown, hull og advarsler. meeting-files inneholder nedlastingene, for eksempel transkripsjonen som TXT og notatene som Markdown, HTML og PDF. Klienten har også disse kommandoene:

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

Foretrekker du curl? Bash-hurtigstarten kjører de samme trinnene for opplasting, jobb og resultat med curl og jq.

bash quickstart.sh meeting.mp4

Slik fungerer en jobb

Alle integrasjoner følger de samme seks trinnene. API-referansen viser hvert kall med et eksempel på forespørsel og svar.

1. Sjekk kontoen. GET /api/v1/account returnerer abonnementet ditt, gjenværende sekunder, støttede formater og grenser.
2. Opprett en opplasting. POST /api/v1/uploads med filstørrelsen i byte og filtypen. Svaret oppgir størrelsen på delene og antall deler.
3. Last opp delene. Hent signerte URL-er med POST /api/v1/uploads/{upload_id}/parts, send hver del med en HTTP-PUT rett til lagringen, ta vare på hver ETag og kall deretter POST /api/v1/uploads/{upload_id}/complete.
4. Start jobben. POST /api/v1/jobs med opplastings-ID-en og en Idempotency-Key-header. Serveren sjekker den faktiske filen, planlegger arbeidet og reserverer tiden i abonnementet ditt.
5. Spør etter status. GET /api/v1/jobs/{job_id} til tilstanden er endelig, og vent minst poll_after_seconds mellom kallene.
6. Les resultatet. GET /api/v1/jobs/{job_id}/result, og følg next_cursor til den er null. Last ned filene i artifacts før lenkene deres utløper.

En jobb ender som completed, completed_with_gaps, interrupted, cancelled, failed eller expired. charged_seconds viser hvor mye av abonnementet ditt jobben brukte.

God praksis

Disse vanene beskytter nøklene dine, hindrer dobbel belastning og gjør lange jobber pålitelige.

Hold nøklene hemmelige

• Kall API-et bare fra en server eller et skript du selv kontrollerer. Legg aldri en nøkkel i nettleserkode, en mobilapp, en URL eller versjonskontroll.
• Last inn nøkkelen fra en miljøvariabel eller en hemmelighetsbehandler, og hold den unna logger, feilrapporter og kommandolinjeargumenter.
• Bruk én nøkkel per integrasjon med en utløpsdato, slik at du kan bytte ut eller tilbakekalle én nøkkel uten å røre de andre.
• For å bytte nøkkel oppretter du den nye, tar den i bruk og tilbakekaller deretter den gamle. Jobber som allerede har startet, fortsetter.
• Hvis en nøkkel kan ha lekket, for eksempel i en chat, en sak eller en commit, tilbakekaller du den straks i panelet API-nøkler.

Gjør det trygt å gjenta oppretting av jobber

• Generer en tilfeldig Idempotency-Key, for eksempel en UUID, for hver nye jobb, og lagre den sammen med opplastings-ID-en før du sender forespørselen.
• Hvis svaret går tapt, sender du den samme forespørselen med den samme nøkkelen på nytt. Du får den opprinnelige jobben tilbake og betaler ikke to ganger.
• Bruk aldri en nøkkel på nytt for en annen fil eller andre valg: API-et svarer da med 409 IDEMPOTENCY_CONFLICT.

Spør med måte og håndter grenser

• Vent minst fem sekunder mellom statuskall, og lenger når poll_after_seconds ber om det.
• Ved 429 eller 503 venter du som angitt i headeren Retry-After eller i error.retry_after_seconds, og prøver så igjen med en liten tilfeldig forsinkelse.
• Gjenta en forespørsel uendret bare når error.retryable er true. Ellers retter du forespørselen først.
• En konto kjører én opplasting og én jobb om gangen. Sett filene dine i kø, og send den neste når den gjeldende jobben er ferdig.

Styr hvor mange timer du bruker

• Sjekk remaining_seconds før du laster opp. En jobb som trenger mer tid enn du har, mislykkes med INSUFFICIENT_BALANCE; API-et forkorter aldri utvalget ditt for at det skal passe.
• Send et range når du bare trenger en del av et opptak. Bare den valgte lyden belastes.
• Avbryt jobber du ikke lenger trenger. Ferdige deler forblir tilgjengelige, og reservert tid som ikke ble brukt, gis tilbake.
• Avbryt opplastinger du ikke kommer til å bruke, slik at den neste opplastingen kan starte.

Hent komplette resultater

• Følg next_cursor til den er null. En side inneholder maksimalt 32 elementer.
• Behandle gap-elementer som lyd som ikke kunne behandles, ikke som stillhet, og sjekk warnings.
• Last ned filene i artifacts mens lenkene er gyldige (opptil ti minutter); hent siden på nytt for å få nye lenker.
• Lagre det du trenger: resultatfiler oppbevares i omtrent 24 timer og gjenoppretting av transkripsjonen i omtrent 48 timer.
• Les feltene du trenger, og ignorer resten.

Vanlige spørsmål

Filer og eksempler

Eksemplene og kontraktfilene publiseres sammen med nettstedet og samsvarer med API-et i drift.

• client.py: eksempelklient for Python 3.12+, bare standardbiblioteket
• quickstart.sh: Bash-eksempel med curl og jq
• openapi.json: OpenAPI 3.1-beskrivelse av hvert endepunkt, med eksempler
• paid-api.schema.json: JSON Schema for hver forespørsel og hvert svar

Hjelp

Er noe uklart, eller virker det ikke? Kontakt oss, og oppgi request_id fra feilsvaret, tidspunktet og endepunktet. Send aldri API-nøkkelen din til oss.