API-referanse
Hvert kall nedenfor har et eksempel på forespørsel og svar, etterfulgt av jobbtilstander, feilkoder, grenser og oppbevaringstider. Ny her? Start med utviklerguiden.
Oversikt
- Basis-URL:
https://api.video-to-notes.com. Alle stier begynner med/api/v1. - Forespørsler og svar er JSON over HTTPS. Send
Content-Type: application/jsonmed hver forespørselskropp. - Tidspunkter er Unix-tidsstempler i sekunder (UTC). Posisjoner i et opptak er sekunder fra starten av filen.
- ID-er og pekere er ugjennomsiktige strenger. Lagre dem nøyaktig slik du mottar dem.
- Hvert feilsvar inneholder en
request_id. Oppgi den når du kontakter brukerstøtte. - Svar sendes med
Cache-Control: no-store; ikke lagre dem i delte hurtigbuffere. - Den maskinlesbare kontrakten ligger i openapi.json (OpenAPI 3.1) og paid-api.schema.json (JSON Schema).
Autentisering
Send API-nøkkelen din som bearer-token med hver API-forespørsel. Nøkler begynner med vtn_prod_. Du oppretter og tilbakekaller nøkler mens du er logget inn på nettstedet; en API-nøkkel kan ikke administrere nøkler, betalinger eller kontoen.
Authorization: Bearer vtn_prod_...En nøkkel som mangler, er feilformatert, er utløpt eller er tilbakekalt, gir 401 UNAUTHORIZED. Send aldri nøkkelen til de signerte lagrings-URL-ene: de har sin egen autorisasjon. Curl-eksemplene på denne siden bruker denne lille hjelpefunksjonen, som gir nøkkelen til curl via standard inndata:
# 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 - "$@"
}Konto
GET /api/v1/account
Returnerer abonnementet, de gjenværende abonnementssekundene, slutten på den gjeldende tildelingen og funksjonene og grensene som gjelder for kontoen akkurat nå. Les det før du laster opp: hvis eligible eller capabilities.api_admission_enabled er false, avvises nye jobber.
vtn "$VTN_API_BASE/api/v1/account"{
"plan": "basic",
"eligible": true,
"remaining_seconds": 64800,
"allowance_expires_at": 1792886400,
"capabilities": {
"api_admission_enabled": true,
"key_creation_enabled": true,
"server_upload_enabled": true,
"long_jobs": true,
"formats": [
"mp4", "m4v", "mov", "webm", "mkv", "ogv", "avi", "wmv", "asf",
"flv", "mpg", "mpeg", "vob", "ts", "mts", "m2ts", "3gp", "3g2",
"mxf", "mp3", "m4a", "aac", "wav", "flac", "ogg", "oga", "opus",
"wma", "amr", "aiff", "aif", "caf", "ac3"
],
"audio_languages": [
"auto", "af", "am", "ar", "hy", "az", "be", "bn", "bs", "bg", "my",
"ca", "zh", "hr", "cs", "da", "nl", "en", "et", "tl", "fi", "fr",
"gl", "ka", "de", "el", "gu", "ha", "he", "hi", "hu", "is", "id",
"it", "ja", "kn", "kk", "km", "ko", "lv", "lt", "mk", "ms", "ml",
"mt", "mr", "mn", "ne", "no", "fa", "pl", "pt", "pa", "ro", "ru",
"sr", "sk", "sl", "es", "sw", "sv", "ta", "te", "th", "tr", "uk",
"uz", "vi"
],
"notes_languages": [
"auto", "af", "am", "ar", "hy", "az", "be", "bn", "bs", "bg", "my",
"ca", "zh", "hr", "cs", "da", "nl", "en", "et", "tl", "fi", "fr",
"gl", "ka", "de", "el", "gu", "ha", "he", "hi", "hu", "is", "id",
"it", "ja", "kn", "kk", "km", "ko", "lv", "lt", "mk", "ms", "ml",
"mt", "mr", "mn", "ne", "no", "fa", "pl", "pt", "pa", "ro", "ru",
"sr", "sk", "sl", "es", "sw", "sv", "ta", "te", "th", "tr", "uk",
"uz", "vi"
],
"download_formats": ["transcript_txt", "notes_md", "notes_html", "notes_pdf"],
"email_opt_in": false,
"limits": {
"max_upload_bytes": 8589934592,
"max_selection_seconds": null,
"active_jobs": 1,
"active_uploads": 1,
"daily_uploads": 10,
"daily_upload_bytes": 21474836480,
"new_requests_per_minute": 12,
"read_requests_per_minute": 60,
"poll_after_seconds": 5,
"result_page_bytes": 1000000,
"result_page_items": 32,
"upload_url_seconds": 900,
"download_url_seconds": 600,
"result_retention_seconds": 86400,
"recovery_retention_seconds": 172800,
"idempotency_retention_seconds": 34560000
}
}
}Opplastinger
Filer lastes opp i deler rett til lagringen via signerte URL-er. En konto kan ha én aktiv opplasting om gangen.
POST /api/v1/uploads
Starter en opplasting. Send den nøyaktige filstørrelsen i byte og filtypen. Svaret oppgir part_size og part_count: del filen i deler på part_size byte; den siste delen kan være mindre.
vtn -X POST "$VTN_API_BASE/api/v1/uploads" \
-H "Content-Type: application/json" \
-d '{
"byte_size": 1048576,
"extension": "mp4"
}'{
"upload_id": "upload-1",
"state": "created",
"expires_at": 1792807200,
"part_size": 16777216,
"part_count": 1,
"error": null
}POST /api/v1/uploads/{upload_id}/parts
Returnerer signerte opplastings-URL-er for 1 til 100 delnumre. Hver URL er gyldig i opptil 15 minutter; be om en ny når den utløper eller når en del må sendes på nytt.
vtn -X POST "$VTN_API_BASE/api/v1/uploads/upload-1/parts" \
-H "Content-Type: application/json" \
-d '{
"part_numbers": [1]
}'{
"upload_id": "upload-1",
"targets": [
{
"part_number": 1,
"url": "https://example.invalid/signed",
"expires_at": 1792800900
}
]
}PUT {signed part URL}
Send hver del som rå byte i en HTTP-PUT til den signerte URL-en, uten Authorization-header. Ta vare på svarheaderen ETag nøyaktig slik den returneres, inkludert anførselstegnene. Hver URL godtar bare delens nøyaktige størrelse: part_size for hver del unntatt den siste, som inneholder de gjenværende bytene. En body med en annen lengde avvises med HTTP 403.
# PART_URL comes from the parts response; send no Authorization header.
curl -s --upload-file part-0001.bin --dump-header - --output /dev/null \
"$PART_URL" | grep -i '^etag:'POST /api/v1/uploads/{upload_id}/complete
Fullfører opplastingen. Send hvert delnummer med sin ETag. Å fullføre en opplasting starter ikke behandlingen; opprett en jobb etterpå.
vtn -X POST "$VTN_API_BASE/api/v1/uploads/upload-1/complete" \
-H "Content-Type: application/json" \
-d '{
"parts": [
{
"part_number": 1,
"etag": "opaque-etag"
}
]
}'{
"upload_id": "upload-1",
"state": "uploaded",
"expires_at": 1792807200,
"part_size": 16777216,
"part_count": 1,
"error": null
}GET /api/v1/uploads/{upload_id}
Returnerer tilstanden til en opplasting: created, uploading, uploaded, probing, probed, failed, aborted eller expired.
vtn "$VTN_API_BASE/api/v1/uploads/upload-1"{
"upload_id": "upload-1",
"state": "uploaded",
"expires_at": 1792807200,
"part_size": 16777216,
"part_count": 1,
"error": null
}POST /api/v1/uploads/{upload_id}/abort
Avbryter en opplasting du ikke kommer til å bruke, og frigjør kontoens opplastingsplass. Det er trygt å kalle den på nytt.
vtn -X POST "$VTN_API_BASE/api/v1/uploads/upload-1/abort" \
-H "Content-Type: application/json" \
-d '{}'Jobber
En jobb behandler én opplastet fil til en transkripsjon og notater. En konto kan kjøre én jobb om gangen.
POST /api/v1/jobs
Starter behandlingen av en opplastet fil. Headeren Idempotency-Key er påkrevd: 1 til 128 utskrivbare ASCII-tegn uten mellomrom, ny for hver jobb. Valgfrie felt er range (start_seconds og end_seconds, begge påkrevd hvis feltet er med), audio_language og notes_language. Returnerer 202 med jobben i tilstanden preparing. Samme nøkkel med samme innhold returnerer den samme jobben; samme nøkkel med annet innhold returnerer 409.
vtn -X POST "$VTN_API_BASE/api/v1/jobs" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d '{
"upload_id": "upload-1",
"range": {
"start_seconds": 5,
"end_seconds": 60
},
"audio_language": null,
"notes_language": "en"
}'{
"job_id": "job-1",
"state": "preparing",
"stage": "probe",
"created_at": 1792800000,
"expires_at": 1792807200,
"result_expires_at": null,
"idempotency_expires_at": 1827360000,
"poll_after_seconds": 5,
"status_url": "/api/v1/jobs/job-1",
"result_url": "/api/v1/jobs/job-1/result",
"completed_units": 0,
"total_units": null,
"charged_seconds": 0,
"result_available": false,
"can_resume": false,
"warnings": [],
"error": null
}GET /api/v1/jobs/{job_id}
Returnerer tilstanden, den gjeldende fasen, fremdriften (completed_units av total_units), charged_seconds, advarsler og eventuell feil. En mislykket jobb returnerer likevel 200; les error.
vtn "$VTN_API_BASE/api/v1/jobs/job-1"{
"job_id": "job-1",
"state": "completed",
"stage": "terminal",
"created_at": 1792800000,
"expires_at": 1792807200,
"result_expires_at": 1792886400,
"idempotency_expires_at": 1827360000,
"poll_after_seconds": 5,
"status_url": "/api/v1/jobs/job-1",
"result_url": "/api/v1/jobs/job-1/result",
"completed_units": 8,
"total_units": 8,
"charged_seconds": 1140,
"result_available": true,
"can_resume": false,
"warnings": [],
"error": null
}POST /api/v1/jobs/{job_id}/cancel
Stopper en jobb. Ferdige deler forblir tilgjengelige, og reservert tid som ikke ble brukt, gis tilbake. Det er trygt å kalle den på nytt.
vtn -X POST "$VTN_API_BASE/api/v1/jobs/job-1/cancel" \
-H "Content-Type: application/json" \
-d '{}'POST /api/v1/jobs/{job_id}/resume
Gjenopptar en avbrutt jobb når statusen oppgir can_resume: true. Det krever et aktivt abonnement og sjekker den gjenværende tiden din på nytt. Deler som allerede er behandlet, belastes ikke igjen.
vtn -X POST "$VTN_API_BASE/api/v1/jobs/job-1/resume" \
-H "Content-Type: application/json" \
-d '{}'Resultater
GET /api/v1/jobs/{job_id}/result
Returnerer én resultatside med opptil 32 elementer og 1 MB. Elementene er ordnet og har en kind: transcript (tekst med tidfestede segmenter), notes (Markdown), gap (lyd som ikke kunne behandles) eller warning. Send next_cursor som spørreparameteren cursor for å hente neste side, til den er null. Hver side kan liste opptil fire nedlastingslenker i artifacts, gyldige i opptil 10 minutter. Hvis jobben gjenopptas mens du leser, returnerer API-et 409 JOB_CONFLICT; start da på nytt fra første side.
vtn --get "$VTN_API_BASE/api/v1/jobs/job-1/result" \
--data-urlencode "cursor=$NEXT_CURSOR" # omit for the first page{
"job_id": "job-1",
"snapshot": "generation-1",
"items": [
{
"index": 0,
"kind": "transcript",
"text": "Welcome to the weekly planning meeting.",
"segments": [
{
"text": "Welcome to the weekly planning meeting.",
"start_seconds": 0,
"end_seconds": 4.2,
"timing_quality": "approximate",
"timing_method": "provider_segment"
}
]
},
{
"index": 0,
"kind": "notes",
"text": "## Summary\n\nThe team agreed on the launch plan.\n\n## Key points\n\n- Launch moves to Monday."
}
],
"next_cursor": "opaque-account-bound-cursor",
"artifacts": [
{
"format": "notes_md",
"url": "https://example.invalid/signed-notes",
"expires_at": 1792800600
}
],
"charged_seconds": 1140,
"partial": false,
"expires_at": 1792886400
}Hvert transkripsjonssegment oppgir sin timing_quality: aligned, approximate eller unavailable. Omtrentlige tider ligger nær talen, men er ikke nøyaktige ned til ordet.
Nedlastingsformatene er transcript_txt (TXT), notes_md (Markdown), notes_html (HTML) og notes_pdf (PDF). Lange notater kan være fordelt på flere filer; last dem ned i rekkefølge. Kontokallet viser formatene som er tilgjengelige akkurat nå.
Jobbtilstander
| Tilstand | Betydning |
|---|---|
preparing | Serveren sjekker filen og planlegger arbeidet. |
queued | Jobben venter på å starte. |
processing | Lyden hentes ut, transkriberes og gjøres om til notater. |
completed | Ferdig. Den fullstendige transkripsjonen og notatene er tilgjengelige. |
completed_with_gaps | Ferdig, men en del av lyden kunne ikke behandles. Se gap-elementene. |
interrupted | Stoppet før slutten. Sjekk can_resume. |
cancelled | Stoppet etter ønske fra deg. Ferdige deler forblir tilgjengelige. |
failed | Jobben kunne ikke behandles. Se error. |
expired | Innholdet oppbevares ikke lenger. |
stage viser trinnet som pågår: probe, planning, admission, extraction, transcription, notes, publication og til slutt terminal.
Feil
Alle feil har den samme JSON-kroppen. retryable forteller om den samme forespørselen kan lykkes senere, og retry_after_seconds hvor lenge du skal vente.
{
"error": {
"code": "RATE_LIMITED",
"message": "Request refused.",
"retryable": true,
"retry_after_seconds": 5
},
"request_id": "request-1"
}| Kode | HTTP | Betydning | Hva du gjør |
|---|---|---|---|
UNAUTHORIZED | 401 | Nøkkelen mangler, er feilformatert, utløpt, tilbakekalt eller hører til et annet miljø. | Sjekk nøkkelen, eller opprett en ny. |
FORBIDDEN | 403 | Nøkkelen kan ikke brukes til denne forespørselen. | Administrer nøkler og betalinger på nettstedet. |
NOT_FOUND | 404 | Opplastingen eller jobben finnes ikke eller tilhører en annen konto. | Sjekk ID-en. |
VALIDATION_ERROR | 400 | Kroppen, en header eller en spørreparameter er ugyldig. | Rett forespørselen; ikke gjenta den uendret. |
PLAN_REQUIRED | 403 | Kontoen har ikke et aktivt Basic- eller Plus-abonnement. | Velg et abonnement, og prøv igjen. |
INSUFFICIENT_BALANCE | 403 | Den gjenværende abonnementstiden dekker ikke den valgte lyden. | Velg et kortere område, eller vent til timene dine fornyes. |
CAPABILITY_DISABLED | 503 | Nye jobber er satt på pause, eller en funksjon er slått av. | Prøv igjen senere; kontokallet viser gjeldende status. |
UNSUPPORTED_MEDIA | 400 | Formatet støttes ikke, eller den opplastede størrelsen avviker fra den oppgitte. | Last opp en støttet fil med nøyaktig størrelse. |
MEDIA_TOO_LARGE | 413 | Filen er større enn grensen. | Last opp en fil på maksimalt 8 GiB. |
PROBE_FAILED | 400 | Filen har ikke noe lydspor som kan dekodes, eller området ligger utenfor filen. | Sjekk filen og området. Ingen tid belastes. |
IDEMPOTENCY_CONFLICT | 409 | Idempotency-Key er allerede brukt med andre inndata. | Bruk en ny nøkkel for en ny jobb. |
IDEMPOTENCY_EXPIRED | 410 | Den opprinnelige jobben for denne nøkkelen er utløpt. | Ikke gjenta den; start en ny jobb med en ny nøkkel. |
JOB_CONFLICT | 409 | En annen opplasting eller jobb er aktiv, tilstanden tillater ikke handlingen, eller resultatet endret seg mens du bladde. | Vent på den gjeldende jobben, eller start bladingen på nytt fra første side. |
RESULT_EXPIRED | 410 | Resultatet oppbevares ikke lenger. | Lagre resultatene før de utløper. |
RATE_LIMITED | 429 | For mange forespørsler, eller den daglige opplastingsgrensen er nådd. | Vent som angitt i Retry-After, og prøv deretter igjen. |
UNAVAILABLE | 503 | En tjeneste er midlertidig utilgjengelig. | Prøv igjen med stadig lengre pauser. |
Grenser
Dette er standardverdiene. Kontokallet returnerer verdiene som gjelder for kontoen din; gå ut fra dem.
| Grense | Standard | Felt i capabilities.limits |
|---|---|---|
| Filstørrelse | 8 GiB | max_upload_bytes |
| Valgt lyd per jobb | Den gjenværende abonnementstiden din (null betyr ingen annen øvre grense) | max_selection_seconds |
| Aktive opplastinger og jobber | Én av hver per konto | active_uploads, active_jobs |
| Opplastinger per UTC-døgn | 10 opplastinger, til sammen 20 GiB | daily_uploads, daily_upload_bytes |
| Nye jobber og gjenopptakelser | 12 per minutt | new_requests_per_minute |
| Andre forespørsler | 60 per minutt for alle nøkler samlet | read_requests_per_minute |
| Statusforespørsler | Ikke oftere enn hvert 5. sekund | poll_after_seconds |
| Resultatside | 32 elementer og 1 MB | result_page_items, result_page_bytes |
| Signert opplastings-URL | Gyldig i opptil 15 minutter | upload_url_seconds |
| Nedlastingslenke | Gyldig i opptil 10 minutter | download_url_seconds |
| Mislykket autentisering | 30 per minutt per IP-adresse; deretter får hver forespørsel fra den adressen 429, også med en gyldig nøkkel, til minuttet har gått | — |
Oppbevaring
| Data | Oppbevares i |
|---|---|
| Opplasting uten jobb | Omtrent 2 timer |
| Resultatsider og nedlastingsfiler | Omtrent 24 timer etter at jobben er ferdig |
| Gjenoppretting av transkripsjonen | Omtrent 48 timer |
| Idempotenspost, uten innhold | 400 dager |
Verdiene i expires_at i hvert svar gjelder; bruk dem i stedet for disse standardverdiene.
Endringslogg
API-versjonen er en del av stien. Endringer i v1 står her med dato.
- 2026-10-24: API v1 tilgjengelig for abonnementene Basic og Plus.