Tale-til-tekst-API

Denne API transskriberer færdige lydfiler som job i en kø. Indsend en fil, gem det returnerede job-ID, og hent jobbet, indtil behandlingen er færdig. Send alle anmodninger over HTTPS med legitimationsoplysninger til din konto, enten HTTP Basic-legitimationsoplysninger som vist i eksemplerne eller et API-token som beskrevet under Godkendelse. Opbevar legitimationsoplysninger på din server.

Endpoints

De to API-værter https://api.multi.tel og kompatibilitetsværten https://api.multitel.net deler de samme kontotilknyttede job, idempotensnøgler, grænser og fakturering. De adskiller sig med hensyn til uploadkodning og svarstruktur, så brug konsekvent én vært med en parser, der passer til den.

På api.multi.tel er alle stier også tilgængelige med præfikset /v1/speech-to-text i stedet for /v3/speech_to_text, for eksempel POST /v1/speech-to-text/estimate. På api.multitel.net skal du bruge stierne /v3/speech_to_text.

Svaret med tjenesteoplysninger angiver mode (batch), realtime (false), paidEnabled (om nye betalte indsendelser accepteres i øjeblikket), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) og maxUploadBytes (26214400) sammen med en kort description. Det er gratis at hente oplysningerne, også mens betalte indsendelser er deaktiveret; svaret er kun 503 transcription_unavailable når tjenesten som helhed er utilgængelig.

Klargør en lydfil

Brug en færdig lydfil på højst 25 MiB (26,214,400 byte) og højst 2 timer (7,200 sekunder). Ved indsendelsen skal filen genkendes som MP3-, WAV-, Ogg-, FLAC-, MOV- eller Matroska-medie med et lydspor, og varigheden i dens metadata skal være større end nul og højst 7,200 sekunder. En genkendt fil, der ikke opfylder disse krav, afvises med 422 unsupported_audio. En fil, der ikke kan læses som nogen af disse formater, kan i øjeblikket i stedet blive afvist med en serverfejl (500); indsend ikke en sådan fil igen uden at ændre den. Filtypenavnet alene fastslår ikke kompatibilitet.

At filen består disse kontroller, garanterer ikke, at lyden kan afkodes. Lyd behandles som én eller to kanaler. En fil med mere end to lydkanaler, en fil, hvis afkodede lyd er længere end 2 timer, eller enhver anden fil, der ikke kan afkodes under behandlingen, ender som et job med status failed, typisk med decode_failed, og faktureres ikke. Konvertér flerkanalslyd til mono eller stereo før indsendelsen.

Det valgfrie sproghint er en kode med to eller tre små bogstaver for det talte sprog, f.eks. en. Udelad feltet, hvis du ikke vil angive et hint; api.multi.tel afviser en tom streng. Hintet vejleder behandlingen, men kontrolleres ikke mod en liste over understøttede sprog, så brug en gyldig kode for det talte sprog.

Indsend et transskriptionsjob

Send JSON med Content-Type: application/json til POST https://api.multi.tel/v3/speech_to_text. Anmodningens body kan være op til 35 MiB, hvilket rummer en fil af maksimal størrelse efter base64-kodning; en større body afvises med 413.

Alle andre JSON-egenskaber, herunder idempotency_key, afvises med 400 invalid_transcription_request. Send nøglen som en header.

Idempotensnøgle

Hver indsendelse kræver en Idempotency-Key-header på 1 til 190 tegn. Brug ASCII-bogstaver, cifre, -, _, . og :, uden indledende eller afsluttende mellemrum: kompatibilitetsværten fjerner omgivende blanktegn og måler nøglen i byte, så andre tegn kan tælles forskelligt på de to værter. En manglende nøgle eller en nøgle på 191 tegn eller mere afvises med 400.

Nøgler er afgrænset til din konto og til tale-til-tekst på tværs af begge værter og alle kontoens legitimationsoplysninger. Når den samme nøgle sendes igen med samme fil og sprog, returneres det eksisterende job med HTTP 200 og duplicate: true, uanset dets status, og selv hvis behandlingen er blevet opdateret, siden jobbet blev oprettet, uden en ny opkrævning. Genbrug af en nøgle med en anden fil eller et andet sprog returnerer 409 idempotency_conflict. En ny nøgle opretter et nyt job, selv for en identisk fil, med en separat opkrævning, hvis behandlingen fuldføres.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

node -e 'process.stdout.write(JSON.stringify({audioBase64:require("node:fs").readFileSync("completed-call.mp3").toString("base64"),language:"en"}))' > completed-call.json

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-call-001" \
  --data-binary @completed-call.json \
  -o speech-job.json \
  https://api.multi.tel/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id'

Et nyt job returnerer HTTP 202 med felterne nedenfor, og en gentagelse returnerer HTTP 200 med hele jobobjektet beskrevet under Hent transskriptionen. Hent jobbets ID, et UUID, fra data.id. Svaret for et nyt job ser sådan ud (identifikatoren og værdierne er eksempler):

{
  "status": "success",
  "data": {
    "id": "3f6c1b2e-8a4d-4e7f-9c21-5b0d7e4a9f13",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "source": "api",
    "durationSeconds": 90.5,
    "billedSeconds": 91,
    "costUsd": "0.007583334",
    "pricePerMinuteUsd": "0.005"
  }
}

Mens et job er i kø eller kører, er durationSeconds, billedSeconds og costUsd estimater fra filens metadata. Den endelige opkrævning bruger den afkodede varighed.

En indsendelse kan også returnere 402 insufficient_balance når en forudbetalt saldo ikke kan dække jobbet sammen med dine øvrige uafsluttede job, 429 transcription_queue_full når din konto eller tjenesten har for mange uafsluttede job, 429 audio_validation_busy når filvalideringen har nået sin kapacitet, og 503 paid_transcription_not_enabled mens betalt transskription er deaktiveret. Prøv igen senere efter svar med 429 og 503, og brug den samme nøgle.

Beregn et estimat uden at oprette et job

Send den samme JSON-body til POST https://api.multi.tel/v3/speech_to_text/estimate. Der kræves ingen idempotensnøgle. Et estimat validerer og måler filen, men transskriberer den ikke, opretter ikke et job, reserverer ikke penge, kontrollerer ikke din saldo og opkræver ikke betaling fra din konto. Et hint i language accepteres, men påvirker ikke estimatet.

Et vellykket estimat returnerer HTTP 200 med estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd og costUsd under data. Det bruger varigheden i filens metadata, mens et fuldført job faktureres efter den afkodede varighed, som kan være anderledes. Estimater anvender de samme filkontroller som indsendelser. De er kun tilgængelige, mens betalt transskription er aktiveret (ellers 503 paid_transcription_not_enabled). De kan returnere 429 audio_validation_busy når filvalideringen har nået sin kapacitet; prøv igen efter en kort ventetid.

Hent transskriptionen

Forespørg gentagne gange på GET /v3/speech_to_text/JOB_ID som beskrevet i vejledningen til jobforløbet. Jobobjektet indeholder disse felter:

Transskriptioner og deres tidsstempler, sprogmarkeringer og kanalmarkeringer genereres automatisk, og deres nøjagtighed garanteres ikke. Betragt ethvert kvalitetsflag som en grund til at gennemgå resultatet, og sammenlign vigtige navne, tal og tilsagn med den oprindelige lyd. Lange pauser og meget stille passager springes over og giver ingen segmenter. Resultater identificerer ikke individuelle talere. Når et resultat angiver en channelCount på 2, har hvert segment en channel på A (den første eller venstre kanal) eller B (den anden eller højre kanal). Dette adskiller kun talerne, når hver taler er optaget på en separat kanal. Lyd med to kanaler faktureres én gang efter sin forløbne varighed, ikke pr. kanal. Monoresultater har ingen kanalmarkeringer.

Brug af api.multitel.net

Kompatibilitetsendpointet POST https://api.multitel.net/v3/speech_to_text accepterer multipart/form-data med en audio-fildel og et valgfrit language-felt i stedet for JSON-feltet audioBase64. En tom værdi i language behandles som intet hint. Send den samme Idempotency-Key-header. Hvis headeren mangler, accepterer denne vært også et idempotency_key-formularfelt. Felter med navnene source, free, billing_source, realtime eller stream afvises med 400 unsupported_transcription_option; andre formularfelter ignoreres. Denne vært returnerer også disse fejl:

• 400 idempotency_key_required ved en manglende eller for lang nøgle.
• 400 audio_upload_required ved en manglende upload eller en upload, der ikke blev modtaget fuldstændigt.
• 400 invalid_language ved et ugyldigt sprog.
• 413 invalid_audio_size ved en tom eller for stor fil.
• 400 invalid_job ved et forkert formateret job-ID.

Svar fra denne værts tale-til-tekst-tjeneste bruger svarstrukturen {"status":{"code":HTTP_STATUS},"response":{...}}. Bemærk, at status er et objekt, ikke en streng. Ved succes indeholder response det samme objekt som data på den primære vært, så jobbets ID er response.id. Ved fejl indeholder response.code fejlkoden; der medfølger ingen meddelelse eller anmodnings-ID. Godkendelsesfejl (401) returneres af værtens generelle loginkontrol og kan have en anden body, så kontrollér HTTP-status før parsing. Bland ikke uploadkodning eller svarparser mellem værterne.

For et estimat på denne vært skal du sende de samme multipart-felter med POST til /v3/speech_to_text/estimate. Der kræves ingen idempotensnøgle, og estimatet findes under response.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Idempotency-Key: speech-call-001" \
  -F "audio=@completed-call.mp3" -F "language=en" \
  -o speech-job.json \
  https://api.multitel.net/v3/speech_to_text

node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).response.id'