API för videotranskribering och anteckningar

Snabbstart

De här stegen tar en fil från din disk till en transkription och anteckningar. Du behöver ett aktivt Basic- eller Plus-abonnemang, en terminal och, för exempelklienten, Python 3.12 eller senare.

1. Skapa en API-nyckel

Logga in på webbplatsen (till exempel på prissidan), öppna API-nycklar i kontofältet, namnge nyckeln och ange ett utgångsdatum om du vill. Kopiera hemligheten när den visas: den visas bara en gång. Upp till tre nycklar kan vara aktiva samtidigt.

2. Spara nyckeln i en miljövariabel

Håll nyckeln borta från källkod, kommandoradsargument och loggar. Exemplen läser nyckeln från VTN_API_KEY och bas-URL:en från 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. Kontrollera ditt konto

Det här anropet bekräftar att nyckeln fungerar och returnerar ditt abonnemang, dina återstående abonnemangssekunder, de format som stöds och de aktuella gränserna.

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

Ladda ned exempelklienten i Python. Den behöver bara standardbiblioteket. Den laddar upp filen i delar, startar jobbet, väntar på det och sparar varje resultatsida.

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

Vill du bara bearbeta en del av en inspelning lägger du till --start och --end i sekunder från filens början. --audio-language ger en språkhint och --notes-language väljer anteckningarnas språk. Utan de här alternativen bearbetas hela filen och språken identifieras automatiskt.

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

Tillståndsfilen sparar uppladdnings-ID:t och begärans identitet, aldrig nyckeln. Om kommandot avbryts kör du det igen med samma tillståndsfil: det hittar samma jobb och du debiteras inte två gånger. Använd en ny tillståndsfil för varje nytt jobb.

5. Läs resultaten

meeting.jsonl innehåller en JSON-resultatsida per rad: transkriptionstext med tider, anteckningar i Markdown, luckor och varningar. meeting-files innehåller nedladdningarna, till exempel transkriptionen som TXT och anteckningarna som Markdown, HTML och PDF. Klienten har även de här kommandona:

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

Föredrar du curl? Bash-snabbstarten kör samma steg för uppladdning, jobb och resultat med curl och jq.

bash quickstart.sh meeting.mp4

Så fungerar ett jobb

Varje integration följer samma sex steg. API-referensen visar varje anrop med ett exempel på begäran och svar.

1. Kontrollera kontot. GET /api/v1/account returnerar ditt abonnemang, återstående sekunder, format som stöds och gränser.
2. Skapa en uppladdning. POST /api/v1/uploads med filstorleken i byte och filändelsen. Svaret anger delstorleken och antalet delar.
3. Ladda upp delarna. Hämta signerade URL:er med POST /api/v1/uploads/{upload_id}/parts, skicka varje del med en HTTP-PUT direkt till lagringen, spara varje ETag och anropa sedan POST /api/v1/uploads/{upload_id}/complete.
4. Starta jobbet. POST /api/v1/jobs med uppladdnings-ID:t och en Idempotency-Key-header. Servern kontrollerar den faktiska filen, planerar arbetet och reserverar tiden i ditt abonnemang.
5. Fråga efter status. GET /api/v1/jobs/{job_id} tills tillståndet är slutgiltigt, och vänta minst poll_after_seconds mellan anropen.
6. Läs resultatet. GET /api/v1/jobs/{job_id}/result och följ next_cursor tills den är null. Ladda ned filerna i artifacts innan länkarna upphör att gälla.

Ett jobb slutar som completed, completed_with_gaps, interrupted, cancelled, failed eller expired. charged_seconds visar hur mycket av ditt abonnemang jobbet har använt.

Bästa praxis

De här vanorna skyddar dina nycklar, förhindrar dubbeldebitering och gör långa jobb pålitliga.

Håll nycklarna hemliga

• Anropa API:t bara från en server eller ett skript som du kontrollerar. Lägg aldrig en nyckel i webbläsarkod, en mobilapp, en URL eller versionshantering.
• Läs in nyckeln från en miljövariabel eller en hemlighetshanterare, och håll den borta från loggar, felrapporter och kommandoradsargument.
• Använd en nyckel per integration med ett utgångsdatum, så att du kan byta eller återkalla en nyckel utan att röra de andra.
• För att byta nyckel skapar du den nya, driftsätter den och återkallar sedan den gamla. Jobb som redan har startat fortsätter.
• Om en nyckel kan ha läckt, till exempel i en chatt, ett ärende eller en commit, återkallar du den direkt i panelen API-nycklar.

Gör det säkert att upprepa skapandet av jobb

• Generera en slumpmässig Idempotency-Key, till exempel ett UUID, för varje nytt jobb och spara den med uppladdnings-ID:t innan du skickar begäran.
• Om svaret går förlorat skickar du samma begäran med samma nyckel igen. Du får tillbaka det ursprungliga jobbet och debiteras inte två gånger.
• Återanvänd aldrig en nyckel för en annan fil eller andra alternativ: API:t svarar då med 409 IDEMPOTENCY_CONFLICT.

Fråga med måtta och hantera gränser

• Vänta minst fem sekunder mellan statusanrop, och längre när poll_after_seconds ber om det.
• Vid 429 eller 503 väntar du enligt headern Retry-After eller error.retry_after_seconds och försöker sedan igen med lite slumpmässig fördröjning.
• Upprepa en begäran oförändrad bara när error.retryable är true. Rätta annars begäran först.
• Ett konto kör en uppladdning och ett jobb åt gången. Lägg dina filer i kö och skicka nästa när det aktuella jobbet är klart.

Styr hur många timmar du använder

• Kontrollera remaining_seconds innan du laddar upp. Ett jobb som behöver mer tid än du har misslyckas med INSUFFICIENT_BALANCE; API:t kortar aldrig ditt urval för att det ska få plats.
• Skicka ett range när du bara behöver en del av en inspelning. Bara det valda ljudet debiteras.
• Avbryt jobb som du inte längre behöver. Färdiga delar finns kvar och reserverad tid som inte användes återförs.
• Avbryt uppladdningar som du inte kommer att använda, så att nästa uppladdning kan starta.

Samla in fullständiga resultat

• Följ next_cursor tills den är null. En sida innehåller högst 32 objekt.
• Behandla gap-objekt som ljud som inte kunde bearbetas, inte som tystnad, och kontrollera warnings.
• Ladda ned filerna i artifacts medan länkarna gäller (upp till tio minuter); hämta sidan igen för nya länkar.
• Spara det du behöver: resultatfiler sparas i cirka 24 timmar och återställningen av transkriptionen i cirka 48 timmar.
• Läs de fält du behöver och ignorera resten.

Vanliga frågor

Filer och exempel

Exemplen och kontraktsfilerna publiceras med webbplatsen och stämmer med API:t i drift.

• client.py: exempelklient för Python 3.12+, bara standardbiblioteket
• quickstart.sh: Bash-exempel med curl och jq
• openapi.json: OpenAPI 3.1-beskrivning av varje endpoint, med exempel
• paid-api.schema.json: JSON Schema för varje begäran och svar

Hjälp

Är något oklart eller fungerar inte? Kontakta oss och ange request_id från felsvaret, tidpunkten och endpointen. Skicka aldrig din API-nyckel till oss.