Ordrett API

API-versjon 1.0.0 · OpenAPI-dokumentet

Norsk tale til tekst fra egne systemer, for Pro og Pro+, med nøkkel fra «Priser», «API-nøkler» i appen (versjon 1.7 eller nyere). Bare for kall fra server: andre nettsteder får ikke CORS.

Autentisering

Flyt

KEY=ordrett_sk_...
API=https://ordrett.app/api/v1
  1. Opprett jobben med body som i Opprett jobb. Svaret har id, job_token, upload_url og upload_headers.
    curl -sS $API/jobs -H "Authorization: Bearer $KEY" \
      -H "Content-Type: application/json" -d @jobb.json
  2. Last opp hele filen med én PUT til upload_url, med upload_headers og uten API-nøkkel. 200 eller 201: fullført. 308: opprett på nytt med samme client_request_id for ny upload_url.
    curl -sS -X PUT -H "Content-Type: audio/mp4" --upload-file mote.m4a "$UPLOAD_URL"
  3. Start jobben. Idempotent, svarer 202 med id og status.
    curl -sS -X POST $API/jobs/$ID/start \
      -H "Authorization: Bearer $KEY" -H "X-Ordrett-Job-Token: $TOKEN"
  4. Polling hvert 5. til 10. sekund til status er ferdig eller feilet.
    curl -sS $API/jobs/$ID \
      -H "Authorization: Bearer $KEY" -H "X-Ordrett-Job-Token: $TOKEN"
  5. Slett når resultatet er lagret: 204. Først med X-Ordrett-Cleanup-Accepted: 1 er lyd, tekst og kopien hos leverandøren av tale til tekst slettet; gjenta til headeren kommer. Ukjent jobb: 204 uten headeren.
    curl -sS -X DELETE -D - -o /dev/null $API/jobs/$ID \
      -H "Authorization: Bearer $KEY" -H "X-Ordrett-Job-Token: $TOKEN"

Endepunkter

EndepunktBeskrivelse
POST /api/v1/jobs Opprett jobb: 201, eller 200 ved gjentatt client_request_id.
POST /api/v1/jobs/{job_id}/start Start jobben. Idempotent.
GET /api/v1/jobs/{job_id} Status og resultat.
DELETE /api/v1/jobs/{job_id} Slett jobb, lyd og tekst.
GET /api/v1/usage Månedens timer og forbruk.
GET /api/v1/openapi.json OpenAPI-dokumentet, uten nøkkel.

GET /api/v1/usage: plan er pro, propluss eller null, month er i UTC, og forbruket gjelder app og API samlet.

{"plan": "pro", "month": "2026-11", "plan_seconds": 28800, "plan_seconds_used": 1234.5}

Opprett jobb

{"client_request_id": "7b0c6a52-3f7e-4a3c-9a51-0c2e6d1f8b44",
 "filename": "mote.m4a", "size_bytes": 52428800, "content_type": "audio/mp4",
 "duration_seconds": 2519.6,
 "options": {"speakers": true, "summary": true, "dialect": true, "maalform": true}}
FeltTypeStandardMerknad
client_request_id string påkrevd UUIDv4 med små bokstaver. Idempotensnøkkel: samme verdi gir samme id og job_token, også etter at abonnementet er avsluttet.
filename string påkrevd 1 til 200 tegn.
size_bytes integer påkrevd Nøyaktig filstørrelse, maks 314 572 800 (300 MB).
content_type string "application/octet-stream" Maks 120 tegn.
duration_seconds number null Lengden. Gir avvisning før opplasting hvis opptaket er for langt eller timene ikke strekker til.
options object {} Se under. Ukjente felt gir 422.
ValgTypeStandardMerknad
transcript boolean true false gir bare gjetning.
speakers boolean false Talere («Taler 1», «Taler 2», ...) på segmentene.
speaker_count integer null 1 til 20, hvis kjent. Bare med speakers.
summary boolean false Sammendrag.
chapters boolean false Kapitler.
words boolean false Tider per ord i segments[].words.
dialect boolean false Gjetning på hvor i landet hver taler kommer fra. +90 s belastning.
maalform boolean false Gjetning på om hver taler ligger nærmest bokmål eller nynorsk. +90 s belastning.
vocabulary string[] [] Navn og fagord til gjenkjenningen: maks 30, hvert maks 80 tegn og 6 ord, uten komma, og maks 500 tegn samlet med ", " mellom.

Svar (201, eller 200 ved gjentak). upload_complete: true: filen er allerede lastet opp. cleanup_only: true: innholdet er utløpt, bare DELETE gjenstår.

{"id": "6f1c0e2a9b7d4c3e8a5f0b1d2c3e4f5a", "client_request_id": "7b0c6a52-...",
 "job_token": "...", "upload_url": "https://...", "upload_method": "PUT",
 "upload_headers": {"Content-Type": "audio/mp4"},
 "upload_complete": false, "cleanup_only": false}

Resultat

StatusBetydning
behandles Opprettet eller under behandling.
tekst_klar Foreløpig tekst for lange opptak. Kan endres; vent på ferdig.
ferdig Ferdig.
feilet Årsaken står i feil; ved kvote eller abonnement også error_code (quota_hours_exhausted, api_requires_subscription).
avbrutt Slettet.

Ferdig jobb med body som over:

{
  "id": "6f1c0e2a9b7d4c3e8a5f0b1d2c3e4f5a",
  "status": "ferdig",
  "duration_seconds": 2519.6,
  "transcript": "Velkommen til styremøtet. Første sak er budsjettet. ...",
  "speakers": ["Taler 1", "Taler 2"],
  "segments": [
    {"start": 0.0, "end": 2.4, "speaker": "Taler 1",
     "text": "Velkommen til styremøtet."},
    {"start": 2.6, "end": 4.9, "speaker": "Taler 2",
     "text": "Første sak er budsjettet."}
  ],
  "summary": {"tittel": "...", "sammendrag": "...",
              "hovedpunkter": ["..."], "aksjonspunkter": ["..."]},
  "speech_profile": {"speakers": [
    {"speaker": "Taler 1", "maalform": "bokmål",
     "dialect": {"region": "Trøndelag", "second": "Nordland"}},
    {"speaker": "Taler 2", "maalform": "nynorsk",
     "dialect": {"region": "Vestland", "second": "Rogaland"}}
  ]},
  "billable_seconds": 2700.0
}

Bare gjetning

"options": {"transcript": false, "speakers": true, "dialect": true, "maalform": true}

Svaret har ingen tekst: transcript, segments, summary og chapters mangler. Det har speech_profile og, med speakers, turns: [{start, end, speaker}]. Med summary, chapters, words eller vocabulary gir opprettelsen 400 transcript_required, uten verken dialect eller maalform 400 guess_required. Belastes som andre jobber.

Grenser

Feil

Feilsvar: {"detail": "...", "error_code": "..."}. detail er en setning på norsk, error_code er stabil der den finnes.

Statuserror_codeBetydning
400 quota_hours_exhausted For lite igjen av månedens timer (remaining_seconds, required_seconds). Nullstilles ved månedsskiftet.
400 vocabulary_invalid vocabulary bryter reglene.
400 transcript_required transcript: false med summary, chapters, words eller vocabulary.
400 guess_required transcript: false uten dialect eller maalform.
400 ingen Annen ugyldig forespørsel, for eksempel ufullstendig opplasting, feil filstørrelse eller for langt opptak.
401 api_key_invalid Nøkkelen mangler, er ugyldig eller er slettet (WWW-Authenticate: Bearer). Feil hos oss gir aldri 401.
403 api_requires_subscription Appen nøkkelen hører til, har ikke lenger Pro eller Pro+.
404 ingen Ukjent jobb, feil job_token eller en jobb fra en annen apps nøkkel.
409 ingen Jobben er avbrutt, og slettingen pågår.
410 ingen Avbrutt og slettet. Bruk en ny client_request_id.
422 ingen Ugyldig body, for eksempel ukjente felt.
429 api_rate_limited Over 60 kall i minuttet eller mer enn 1 samtidig per nøkkel. Vent Retry-After.
429 ingen Kapasitetsgrense. Vent Retry-After.
503 api_key_unavailable, quota_unavailable eller ingen Midlertidig feil. Vent Retry-After.

Pris

En API-nøkkel gir tilgang til det samme abonnementet og de samme timene som appen den ble laget i. Hver jobb gjennom API-et belastes per påbegynte minutt lyd, minst ett minutt, og med halvannet minutt ekstra for hver gjetning på dialekt eller målform. Se Priser.

LydGjetningerBelastes
30 s ingen 60 s
60 s ingen 60 s
61 s ingen 120 s
30 s dialekt 150 s
61 s dialekt og målform 300 s

billable_seconds regnes av urundet lyd, så duration_seconds 60.0 kan gi billable_seconds 120.0.

Personvern

Lyden du transkriberer behandles i Europa, hos en leverandør av tale til tekst og hos skyleverandøren vår. Lyd og tekst ligger bare midlertidig på serveren mens jobben behandles og leveres. Lagring av nøkler, sletting og ansvar: personvern og vilkår.