API for tale-til-tekst

Dette API-et transkriberer ferdige lydfiler som jobber i en kø. Send inn en fil, ta vare på den returnerte jobb-ID-en, og hent jobben til behandlingen er ferdig. Send alle forespørsler over HTTPS med påloggingsopplysninger for kontoen din, enten HTTP Basic-opplysninger som vist i eksemplene eller et API-token som beskrevet under Autentisering. Oppbevar påloggingsopplysninger på serveren din.

Endepunkter

De to API-vertene https://api.multi.tel og kompatibilitetsverten https://api.multitel.net deler de samme kontoavgrensede jobbene, idempotensnøklene, grensene og faktureringen. De bruker ulik opplastingskoding og svarstruktur, så bruk én vert konsekvent med en parser som passer til den.

På api.multi.tel er alle stier også tilgjengelige med prefikset /v1/speech-to-text i stedet for /v3/speech_to_text, for eksempel POST /v1/speech-to-text/estimate. På api.multitel.net bruker du stiene /v3/speech_to_text.

Svaret med tjenesteinformasjon oppgir mode (batch), realtime (false), paidEnabled (om nye betalte innsendelser godtas for øyeblikket), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) og maxUploadBytes (26214400), sammen med en kort description. Det er gratis å hente informasjonen, også mens betalte innsendelser er deaktivert; svaret er bare 503 transcription_unavailable når hele tjenesten er utilgjengelig.

Klargjør en lydfil

Bruk en ferdig lydfil på maksimalt 25 MiB (26,214,400 byte) og maksimalt 2 timer (7,200 sekunder). Ved innsending må filen gjenkjennes som MP3-, WAV-, Ogg-, FLAC-, MOV- eller Matroska-medier med en lydstrøm, og varigheten i metadataene må være større enn null og maksimalt 7,200 sekunder. En gjenkjent fil som ikke består disse kontrollene, avvises med 422 unsupported_audio. En fil som ikke kan leses som noen av disse formatene, kan for øyeblikket i stedet bli avvist med en serverfeil (500); ikke send inn en slik fil på nytt uten å endre den. Filendelsen alene fastslår ikke kompatibilitet.

At filen består disse kontrollene, garanterer ikke at lyden kan dekodes. Lyd behandles som én eller to kanaler. En fil med mer enn to lydkanaler, en fil der den dekodede lyden er lengre enn 2 timer, eller en annen fil som ikke kan dekodes under behandlingen, ender som en jobb med status failed, vanligvis med decode_failed, og faktureres ikke. Konverter flerkanalslyd til mono eller stereo før innsending.

Det valgfrie språkhintet er en kode med to eller tre små bokstaver for språket som snakkes, for eksempel en. Utelat feltet hvis du ikke vil angi et hint; api.multi.tel avviser en tom streng. Hintet veileder behandlingen, men kontrolleres ikke mot en liste over støttede språk, så bruk en gyldig kode for språket som snakkes.

Send inn en transkripsjonsjobb

Send JSON med Content-Type: application/json til POST https://api.multi.tel/v3/speech_to_text. Forespørselskroppen kan være opptil 35 MiB, noe som rommer en fil av maksimal størrelse etter base64-koding; en større kropp avvises med 413.

Alle andre JSON-egenskaper, inkludert idempotency_key, avvises med 400 invalid_transcription_request. Send nøkkelen som en header.

Idempotensnøkkel

Hver innsending krever en Idempotency-Key-header på 1 til 190 tegn. Bruk ASCII-bokstaver, sifre, -, _, . og :, uten innledende eller avsluttende mellomrom: kompatibilitetsverten fjerner omkringliggende blanktegn og måler nøkkelen i byte, så andre tegn kan telles ulikt av de to vertene. En manglende nøkkel eller en nøkkel på 191 tegn eller mer avvises med 400.

Nøkler er avgrenset til kontoen din og til tale-til-tekst, på tvers av begge verter og alle kontoens påloggingsopplysninger. Hvis du sender den samme nøkkelen på nytt med samme fil og språk, returneres den eksisterende jobben med HTTP 200 og duplicate: true, uansett status og selv om behandlingen er oppdatert siden jobben ble opprettet, uten en ny belastning. Gjenbruk av en nøkkel med en annen fil eller et annet språk returnerer 409 idempotency_conflict. En ny nøkkel oppretter en ny jobb selv for en identisk fil, med en separat belastning hvis behandlingen fullfø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'

En ny jobb returnerer HTTP 202 med feltene nedenfor, og en gjentatt innsending returnerer HTTP 200 med hele jobbobjektet beskrevet under Hent transkripsjonen. Hent jobb-ID-en, en UUID, fra data.id. Svaret for en ny jobb ser slik ut (identifikatoren og verdiene 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 en jobb står i kø eller kjører, er durationSeconds, billedSeconds og costUsd estimater fra filens metadata. Den endelige belastningen bruker den dekodede varigheten.

En innsending kan også returnere 402 insufficient_balance når en forhåndsbetalt saldo ikke kan dekke jobben sammen med de andre utestående jobbene dine, 429 transcription_queue_full når kontoen din eller tjenesten har for mange utestående jobber, 429 audio_validation_busy når filvalideringen har nådd kapasitetsgrensen, og 503 paid_transcription_not_enabled mens betalt transkripsjon er deaktivert. Prøv igjen senere etter svar med 429 og 503, og bruk den samme nøkkelen.

Beregn et estimat uten å opprette en jobb

Send den samme JSON-kroppen til POST https://api.multi.tel/v3/speech_to_text/estimate. Ingen idempotensnøkkel er nødvendig. Et estimat validerer og måler filen, men transkriberer den ikke, oppretter ikke en jobb, reserverer ikke penger, kontrollerer ikke saldoen din og belaster ikke kontoen din. Et hint i language godtas, 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 bruker varigheten i filens metadata, mens en fullført jobb faktureres etter den dekodede varigheten, som kan være annerledes. Estimater bruker de samme filkontrollene som innsendelser. De er bare tilgjengelige mens betalt transkripsjon er aktivert (ellers 503 paid_transcription_not_enabled). De kan returnere 429 audio_validation_busy når filvalideringen har nådd kapasitetsgrensen; prøv igjen etter en kort ventetid.

Hent transkripsjonen

Hent jobbstatusen gjentatte ganger med GET /v3/speech_to_text/JOB_ID som beskrevet i veiledningen for jobbforløpet. Jobbobjektet inneholder disse feltene:

Transkripsjoner og tilhørende tidsstempler, språkmerking og kanalmerking produseres automatisk, og nøyaktigheten er ikke garantert. Se ethvert kvalitetsflagg som en grunn til å gjennomgå resultatet, og sammenlign viktige navn, tall og forpliktelser med den opprinnelige lyden. Lange stillheter og svært stille partier hoppes over og gir ingen segmenter. Resultater identifiserer ikke individuelle talere. Når et resultat oppgir en channelCount på 2, har hvert segment en channel på A (den første, eller venstre, kanalen) eller B (den andre, eller høyre, kanalen). Dette skiller bare talerne når hver taler ble tatt opp på en separat kanal. Lyd med to kanaler faktureres én gang etter medgått varighet, ikke per kanal. Monoresultater har ingen kanalmerking.

Bruk av api.multitel.net

Kompatibilitetsendepunktet POST https://api.multitel.net/v3/speech_to_text godtar multipart/form-data med en audio-fildel og et valgfritt language-felt i stedet for JSON-feltet audioBase64. En tom verdi i language behandles som intet hint. Send den samme Idempotency-Key-headeren. Hvis headeren mangler, godtar denne verten også et idempotency_key-skjemafelt. Felter med navnene source, free, billing_source, realtime eller stream avvises med 400 unsupported_transcription_option; andre skjemafelter ignoreres. Denne verten returnerer også disse feilene:

• 400 idempotency_key_required ved en manglende eller for lang nøkkel.
• 400 audio_upload_required ved en manglende opplasting eller en opplasting som ikke ble mottatt fullstendig.
• 400 invalid_language ved et ugyldig språk.
• 413 invalid_audio_size ved en tom eller for stor fil.
• 400 invalid_job ved en feilformatert jobb-ID.

Svar fra denne vertens tale-til-tekst-tjeneste bruker svarstrukturen {"status":{"code":HTTP_STATUS},"response":{...}}. Merk at status er et objekt, ikke en streng. Ved suksess inneholder response det samme objektet som data på primærverten, så jobb-ID-en er response.id. Ved feil inneholder response.code feilkoden; ingen melding eller forespørsels-ID er inkludert. Autentiseringsfeil (401) returneres av vertens generelle påloggingskontroll og kan ha en annen kropp, så kontroller HTTP-statusen før parsing. Ikke bruk opplastingskodingen eller svarparseren for den ene verten på den andre.

For et estimat på denne verten sender du de samme multipart-feltene med POST til /v3/speech_to_text/estimate. Ingen idempotensnøkkel er nødvendig, og estimatet ligger 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'