Spraak-na-teks-API

Hierdie API transkribeer voltooide oudiolêers as take in ’n verwerkingsry. Dien ’n lêer in, hou die teruggestuurde taak-ID en vra die taak op totdat verwerking klaar is. Stuur elke versoek oor HTTPS met jou rekening se aanmeldbesonderhede: óf HTTP Basic-aanmeldbesonderhede soos in die voorbeelde, óf ’n API-token, soos beskryf onder Stawing. Hou aanmeldbesonderhede op jou bediener.

Eindpunte

Twee API-gashere, https://api.multi.tel en die versoenbaarheidsgasheer https://api.multitel.net, deel dieselfde rekeninggebonde take, idempotensiesleutels, perke en heffings. Hulle verskil in oplaai-enkodering en antwoordomhulsel; gebruik dus deurgaans een gasheer met ’n ooreenstemmende ontleder.

Op api.multi.tel is elke pad ook beskikbaar met die voorvoegsel /v1/speech-to-text in plaas van /v3/speech_to_text, byvoorbeeld POST /v1/speech-to-text/estimate. Op api.multitel.net gebruik jy die /v3/speech_to_text-paaie.

Die antwoord met diensinligting bevat mode (batch), realtime (false), paidEnabled (of nuwe betaalde indienings tans aanvaar word), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) en maxUploadBytes (26214400), tesame met ’n kort beskrywing in description. Dit is gratis om hierdie inligting te lees en dit werk terwyl betaalde indienings gedeaktiveer is; dit stuur slegs 503 transcription_unavailable terug wanneer die diens as geheel onbeskikbaar is.

Berei ’n oudiolêer voor

Gebruik ’n voltooide oudiolêer van hoogstens 25 MiB (26,214,400 grepe) en hoogstens 2 uur (7,200 sekondes). By indiening moet die lêer herken word as MP3-, WAV-, Ogg-, FLAC-, MOV- of Matroska-media wat ’n oudiostroom bevat, met ’n duur in die metadata van meer as nul en hoogstens 7,200 sekondes. ’n Herkende lêer wat nie hierdie kontroles slaag nie, word met 422 unsupported_audio verwerp. ’n Lêer wat nie as enige van hierdie formate gelees kan word nie, kan tans eerder met ’n bedienerfout (500) verwerp word; moenie so ’n lêer onveranderd weer indien nie. ’n Lêeruitbreiding alleen bevestig nie versoenbaarheid nie.

As hierdie kontroles slaag, waarborg dit nie dat die oudio gedekodeer kan word nie. Oudio word as een of twee kanale verwerk. ’n Lêer met meer as twee oudiokanale, ’n lêer waarvan die gedekodeerde oudio langer as 2 uur is, of enige ander lêer waarvan dekodering tydens verwerking misluk, eindig as ’n failed-taak, gewoonlik met decode_failed, en word nie gehef nie. Skakel meerkanaaloudio na mono of stereo om voordat jy dit indien.

Die opsionele taalwenk is ’n kleinletterkode van twee of drie letters vir die taal wat gepraat word, soos en. Laat die veld weg om geen wenk te gee nie; api.multi.tel verwerp ’n leë string. Die wenk lei verwerking, maar word nie teen ’n lys ondersteunde tale nagegaan nie; gebruik dus ’n geldige kode vir die taal wat gepraat word.

Dien ’n transkripsietaak in

Stuur JSON met Content-Type: application/json na POST https://api.multi.tel/v3/speech_to_text. Die versoekliggaam kan tot 35 MiB wees, wat ’n lêer van die maksimum grootte ná base64-enkodering akkommodeer; ’n groter liggaam word met 413 verwerp.

Enige ander JSON-eienskap, insluitend idempotency_key, word met 400 invalid_transcription_request verwerp. Stuur die sleutel as ’n kopskrif.

Idempotensiesleutel

Elke indiening vereis ’n Idempotency-Key-kopskrif van 1 tot 190 karakters. Gebruik ASCII-letters, syfers, -, _, . en :, sonder spasies aan die begin of einde: die versoenbaarheidsgasheer verwyder witspasie rondom die sleutel en meet dit in grepe; ander karakters kan dus op elke gasheer anders getel word. ’n Ontbrekende sleutel, of ’n sleutel van 191 of meer karakters, word met 400 verwerp.

Sleutels is tot jou rekening en spraak-na-teks beperk, oor albei gashere en al jou rekening se aanmeldbesonderhede heen. As jy dieselfde sleutel met dieselfde lêer en taal weer stuur, word die bestaande taak met HTTP 200 en duplicate: true teruggestuur, ongeag die status daarvan en selfs al is verwerking sedert die skepping van die taak bygewerk, sonder nog ’n heffing. Hergebruik van ’n sleutel met ’n ander lêer of taal stuur 409 idempotency_conflict terug. ’n Nuwe sleutel skep ’n nuwe taak selfs vir ’n identiese lêer, met ’n afsonderlike heffing as verwerking suksesvol voltooi word.

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'

’n Nuwe taak stuur HTTP 202 met die velde hieronder terug, en ’n herhaalde versoek stuur HTTP 200 met die volledige taakobjek terug soos beskryf onder Lees die transkripsie. Lees die taak-ID, ’n UUID, uit data.id. ’n Nuwe taak se antwoord lyk so (die identifiseerder en waardes is voorbeelde):

{
  "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"
  }
}

Terwyl ’n taak in die ry wag of loop, is durationSeconds, billedSeconds en costUsd ramings uit die lêer se metadata. Die finale heffing gebruik die gedekodeerde duur.

’n Indiening kan ook 402 insufficient_balance terugstuur wanneer ’n voorafbetaalde saldo nie die taak saam met jou ander uitstaande take kan dek nie, 429 transcription_queue_full wanneer jou rekening of die diens te veel uitstaande take het, 429 audio_validation_busy wanneer lêervalidering volle kapasiteit bereik het, en 503 paid_transcription_not_enabled terwyl betaalde transkripsie gedeaktiveer is. Probeer antwoorde met 429 en 503 later weer met dieselfde sleutel.

Kry ’n raming sonder om ’n taak te skep

Stuur dieselfde JSON-liggaam na POST https://api.multi.tel/v3/speech_to_text/estimate. Geen idempotensiesleutel word vereis nie. ’n Raming valideer en meet die lêer, maar transkribeer dit nie, skep nie ’n taak nie, reserveer nie geld nie, gaan nie jou saldo na nie en hef nie jou rekening nie. ’n language-wenk word aanvaar, maar beïnvloed nie die raming nie.

’n Suksesvolle raming stuur HTTP 200 terug met estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd en costUsd onder data. Dit gebruik die duur in die lêer se metadata, terwyl ’n voltooide taak volgens die gedekodeerde duur gehef word, wat kan verskil. Ramings pas dieselfde lêerkontroles as indienings toe. Hulle is slegs beskikbaar terwyl betaalde transkripsie geaktiveer is (andersins 503 paid_transcription_not_enabled). Hulle kan 429 audio_validation_busy terugstuur wanneer lêervalidering volle kapasiteit bereik het; probeer weer ná ’n kort wagtyd.

Lees die transkripsie

Vra GET /v3/speech_to_text/JOB_ID herhaaldelik op soos beskryf in die gids vir die taakwerkvloei. Die taakobjek bevat hierdie velde:

Transkripsies en hul tydstempels, taaletikette en kanaaletikette word outomaties geskep en is nie gewaarborg om akkuraat te wees nie. Beskou enige kwaliteitsvlag as ’n rede om die resultaat te hersien en vergelyk belangrike name, getalle en verbintenisse met die oorspronklike oudio. Lang stiltes en baie sagte gedeeltes word oorgeslaan en lewer geen segmente nie. Resultate identifiseer nie individuele sprekers nie. Wanneer ’n resultaat ’n channelCount van 2 rapporteer, het elke segment ’n channel van A (die eerste, oftewel die linkerkanaal) of B (die tweede, oftewel die regterkanaal). Dit skei sprekers slegs wanneer elke spreker op ’n afsonderlike kanaal opgeneem is. Tweekanaaloudio word een keer volgens die verstreke duur gehef, nie per kanaal nie. Monoresultate het geen kanaaletikette nie.

Gebruik van api.multitel.net

Die versoenbaarheidseindpunt POST https://api.multitel.net/v3/speech_to_text aanvaar multipart/form-data met ’n audio-lêerdeel en ’n opsionele language-veld, eerder as JSON se audioBase64. ’n Leë language-waarde word as geen wenk behandel. Stuur dieselfde Idempotency-Key-kopskrif. As die kopskrif ontbreek, aanvaar hierdie gasheer ook ’n idempotency_key-vormveld. Velde met die name source, free, billing_source, realtime of stream word met 400 unsupported_transcription_option verwerp; ander vormvelde word geïgnoreer. Hierdie gasheer stuur ook hierdie foute terug:

• 400 idempotency_key_required vir ’n ontbrekende of te lang sleutel.
• 400 audio_upload_required vir ’n ontbrekende lêeroplaai, of een wat nie volledig ontvang is nie.
• 400 invalid_language vir ’n ongeldige taal.
• 413 invalid_audio_size vir ’n leë of te groot lêer.
• 400 invalid_job vir ’n verkeerd gevormde taak-ID.

Antwoorde van hierdie gasheer se spraak-na-teks-diens gebruik die omhulsel {"status":{"code":HTTP_STATUS},"response":{...}}. Let daarop dat status ’n objek is, nie ’n string nie. By sukses bevat response dieselfde objek as data op die primêre gasheer; die taak-ID is dus response.id. By ’n fout bevat response.code die foutkode; geen boodskap of versoek-ID word ingesluit nie. Stawingsfoute (401) word deur die gasheer se algemene aanmeldkontrole teruggestuur en kan ’n ander liggaam hê; gaan dus die HTTP-status na voordat jy die antwoord ontleed. Moenie die oplaai-enkodering of antwoordontleder tussen gashere uitruil nie.

Vir ’n raming op hierdie gasheer, stuur dieselfde multipart-velde met POST na /v3/speech_to_text/estimate. Geen idempotensiesleutel word vereis nie, en die raming is onder 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'