Kõne tekstiks teisendamise API

See API transkribeerib valmis helifaile järjekorras töödeldavate töödena. Saatke fail, salvestage tagastatud töö ID ja pärige tööd, kuni töötlemine on lõppenud. Saatke kõik päringud HTTPS-i kaudu oma konto autentimisandmetega: näidetes toodud HTTP Basic andmetega või API pääsmikuga, nagu on kirjeldatud jaotises Autentimine. Hoidke autentimisandmeid oma serveris.

Lõpp-punktid

Kaks API serverit, https://api.multi.tel ja ühilduvusserver https://api.multitel.net, jagavad samu kontopõhiseid töid, idempotentsusvõtmeid, piiranguid ja arveldust. Üleslaadimise kodeering ja vastuse ümbris erinevad, seega kasutage järjepidevalt üht serverit ning sobivat parserit.

Serveris api.multi.tel on kõik teed saadaval ka prefiksiga /v1/speech-to-text järgmise prefiksi asemel: /v3/speech_to_text, näiteks POST /v1/speech-to-text/estimate. Serveris api.multitel.net kasutage /v3/speech_to_text teid.

Teenuse teabe vastus sisaldab välju mode (batch), realtime (false), paidEnabled (kas uusi tasulisi töid praegu vastu võetakse), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) ja maxUploadBytes (26214400) ning lühikirjeldust väljal description. Teabe pärimine on tasuta ja toimib ka siis, kui tasuliste tööde esitamine on keelatud; vastus 503 transcription_unavailable tagastatakse ainult siis, kui kogu teenus pole saadaval.

Helifaili ettevalmistamine

Kasutage valmis helifaili, mille suurus on kuni 25 MiB (26,214,400 baiti) ja kestus kuni 2 tundi (7,200 sekundit). Esitamisel peab fail olema tuvastatav MP3-, WAV-, Ogg-, FLAC-, MOV- või Matroska-meediana, mis sisaldab helivoogu ning mille metaandmetes on kestus suurem kui null ja kuni 7,200 sekundit. Tuvastatud fail, mis neid kontrolle ei läbi, lükatakse tagasi vastusega 422 unsupported_audio. Fail, mida ei saa üheski neist vormingutest lugeda, võidakse praegu selle asemel tagasi lükata serveriveaga (500); ärge saatke sellist faili muutmata kujul uuesti. Üksnes faililaiend ei tõenda ühilduvust.

Nende kontrollide läbimine ei taga heli dekodeerimise õnnestumist. Heli töödeldakse ühe või kahe kanalina. Fail, milles on rohkem kui kaks helikanalit, mille dekodeeritud heli kestab üle 2 tunni või mille dekodeerimine töötlemise käigus muul põhjusel ebaõnnestub, lõpetatakse olekus failed, tavaliselt veakoodiga decode_failed, ning selle eest tasu ei võeta. Teisendage mitmekanaliline heli enne esitamist monoks või stereoks.

Valikuline keelevihje on kõneldava keele kahe- või kolmetäheline väiketähtedes kood, näiteks en. Kui te vihjet anda ei soovi, jätke väli välja; api.multi.tel lükkab tühja stringi tagasi. Vihje suunab töötlemist, kuid seda ei kontrollita toetatud keelte loendi alusel, seega kasutage kõneldava keele kehtivat koodi.

Transkribeerimistöö esitamine

Saatke JSON päisega Content-Type: application/json aadressile POST https://api.multi.tel/v3/speech_to_text. Päringu keha võib olla kuni 35 MiB, et mahutada suurima lubatud mahuga fail pärast base64-kodeerimist; suurem keha lükatakse tagasi vastusega 413.

Kõik muud JSON-i atribuudid, sealhulgas idempotency_key, lükatakse tagasi vastusega 400 invalid_transcription_request. Saatke võti päisena.

Idempotentsusvõti

Iga esitamine nõuab Idempotency-Key-päist pikkusega 1 kuni 190 märki. Kasutage ASCII tähti, numbreid, -, _, . ja : ilma algus- ja lõputühikuteta: ühilduvusserver eemaldab ümbritsevad tühimärgid ja mõõdab võtit baitides, seega võivad serverid muid märke erinevalt loendada. Puuduv või vähemalt 191 märgi pikkune võti lükatakse tagasi vastusega 400.

Võtmed on seotud teie konto ja kõne tekstiks teisendamisega mõlemas serveris ning kõigi teie konto autentimisandmete puhul. Sama võtme uuesti saatmine sama faili ja keelega tagastab olemasoleva töö vastusega HTTP 200 ja duplicate: true, olenemata töö olekust ja isegi siis, kui töötlemist on pärast töö loomist uuendatud, ilma uue tasuta. Võtme taaskasutamine teise faili või keelega tagastab 409 idempotency_conflict. Uus võti loob uue töö ka identse faili jaoks ning selle eest võetakse eraldi tasu, kui töötlemine lõpeb edukalt.

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'

Uus töö tagastab HTTP 202 koos allpool näidatud väljadega ning korduspäring tagastab HTTP 200 koos täieliku tööobjektiga, mida kirjeldatakse jaotises Transkriptsiooni lugemine. Lugege töö ID, mis on UUID, väljalt data.id. Uue töö vastus näeb välja selline (tunnus ja väärtused on näited):

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

Kui töö on järjekorras või käib, on durationSeconds, billedSeconds ja costUsd faili metaandmetel põhinevad hinnangud. Lõplik tasu põhineb dekodeeritud kestusel.

Esitamine võib tagastada ka 402 insufficient_balance, kui ettemakstud saldo ei kata tööd koos teie teiste lõpetamata töödega, 429 transcription_queue_full, kui teie kontol või teenuses on liiga palju lõpetamata töid, 429 audio_validation_busy, kui failide kontrolli võimsus on ammendunud, ning 503 paid_transcription_not_enabled, kui tasuline transkribeerimine on keelatud. Vastuste 429 ja 503 järel proovige hiljem sama võtmega uuesti.

Hinnangu saamine tööd loomata

Saatke sama JSON-keha aadressile POST https://api.multi.tel/v3/speech_to_text/estimate. Idempotentsusvõtit pole vaja. Hinnangu koostamisel kontrollitakse ja mõõdetakse faili, kuid seda ei transkribeerita, tööd ei looda, raha ei broneerita, teie saldot ei kontrollita ega kontolt tasu võeta. Vihjet language aktsepteeritakse, kuid see ei mõjuta hinnangut.

Õnnestunud hinnang tagastab HTTP 200 väljadega estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd ja costUsd objekti data sees. See kasutab faili metaandmetes olevat kestust, kuid lõpetatud töö eest võetakse tasu dekodeeritud kestuse põhjal, mis võib erineda. Hinnangutele kehtivad samad failikontrollid nagu esitamisele. Need on saadaval ainult siis, kui tasuline transkribeerimine on lubatud (muidu 503 paid_transcription_not_enabled). Need võivad tagastada 429 audio_validation_busy, kui failide kontrolli võimsus on ammendunud; proovige pärast lühikest pausi uuesti.

Transkriptsiooni lugemine

Pärige korduvalt GET /v3/speech_to_text/JOB_ID, nagu on kirjeldatud töövoo juhendis. Tööobjekt sisaldab järgmisi välju:

Transkriptsioonid ning nende ajatemplid, keele- ja kanalimärgised luuakse automaatselt ning nende täpsus pole tagatud. Võtke iga kvaliteedilippu põhjusena tulemust üle vaadata ning võrrelge olulisi nimesid, numbreid ja lubadusi algse heliga. Pikad vaikuseperioodid ja väga vaiksed lõigud jäetakse vahele ning neist segmente ei looda. Tulemused ei tuvasta üksikuid kõnelejaid. Kui tulemuse channelCount on 2, on iga segmendi channel väärtus A (esimene ehk vasak kanal) või B (teine ehk parem kanal). See eristab kõnelejaid ainult siis, kui iga kõneleja salvestati eraldi kanalile. Kahekanalilise heli eest võetakse tasu üks kord selle kestuse järgi, mitte kanali kohta. Monotulemustel kanalimärgiseid pole.

api.multitel.net-i kasutamine

Ühilduvuse lõpp-punkt POST https://api.multitel.net/v3/speech_to_text aktsepteerib multipart/form-data-päringut audio-failiosaga ja valikulise language-väljaga JSON-välja audioBase64 asemel. Tühja language väärtust käsitatakse vihje puudumisena. Saatke sama Idempotency-Key-päis. Kui päis puudub, aktsepteerib see server ka idempotency_key-vormivälja. Väljad nimega source, free, billing_source, realtime või stream lükatakse tagasi vastusega 400 unsupported_transcription_option; muid vormivälju eiratakse. See server tagastab ka järgmised vead:

• 400 idempotency_key_required puuduva või liiga pika võtme korral.
• 400 audio_upload_required puuduva või mittetäielikult vastu võetud üleslaadimise korral.
• 400 invalid_language vigase keele korral.
• 413 invalid_audio_size tühja või liiga suure faili korral.
• 400 invalid_job vigases vormingus töö ID korral.

Selle serveri kõne tekstiks teisendamise teenuse vastused kasutavad ümbrist {"status":{"code":HTTP_STATUS},"response":{...}}. Pange tähele, et status on objekt, mitte string. Õnnestumise korral sisaldab response sama objekti nagu data põhiserveris, seega töö ID on response.id. Vea korral sisaldab response.code veakoodi; teadet ega päringu ID-d ei lisata. Autentimisvead (401) tagastatakse serveri üldise sisselogimiskontrolli kaudu ja nende keha võib erineda, seega kontrollige enne parsimist HTTP olekut. Ärge kasutage ühe serveri üleslaadimiskodeeringut või vastuseparserit teise serveri jaoks.

Selles serveris hinnangu saamiseks saatke samad multipart-väljad POST-päringuga aadressile /v3/speech_to_text/estimate. Idempotentsusvõtit pole vaja ning hinnang asub objekti response sees.

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'