Kalbos transkribavimo API

Ši API transkribuoja užbaigtus garso failus kaip į eilę įtrauktas užduotis. Pateikite failą, išsaugokite grąžintą užduoties ID ir užklauskite užduoties, kol apdorojimas bus baigtas. Visas užklausas siųskite per HTTPS su savo paskyros prisijungimo duomenimis: pavyzdžiuose parodytais HTTP Basic duomenimis arba API prieigos raktu, kaip aprašyta skyriuje Autentifikavimas. Prisijungimo duomenis laikykite savo serveryje.

Galiniai taškai

Du API serveriai, https://api.multi.tel ir suderinamumo serveris https://api.multitel.net, naudoja tas pačias paskyrai priskirtas užduotis, idempotentiškumo raktus, apribojimus ir atsiskaitymą. Įkėlimo kodavimas ir atsakymo apvalkalas skiriasi, todėl nuosekliai naudokite vieną serverį su jam tinkamu analizatoriumi.

Serveryje api.multi.tel visi keliai taip pat pasiekiami su prefiksu /v1/speech-to-text vietoj /v3/speech_to_text, pavyzdžiui, POST /v1/speech-to-text/estimate. Serveryje api.multitel.net naudokite /v3/speech_to_text kelius.

Paslaugos informacijos atsakyme pateikiami mode (batch), realtime (false), paidEnabled (ar šiuo metu priimamos naujos mokamos užduotys), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) ir maxUploadBytes (26214400) kartu su trumpu aprašymu lauke description. Šią informaciją gauti nemokama; tai veikia ir tada, kai mokamų užduočių pateikimas išjungtas. Atsakymas 503 transcription_unavailable grąžinamas tik tada, kai visa paslauga nepasiekiama.

Paruoškite garso failą

Naudokite užbaigtą garso failą, ne didesnį nei 25 MiB (26,214,400 baitų) ir ne ilgesnį nei 2 valandos (7,200 sekundžių). Pateikiant failas turi būti atpažįstamas kaip MP3, WAV, Ogg, FLAC, MOV arba Matroska medija su garso srautu, o metaduomenyse nurodyta trukmė turi būti didesnė už nulį ir ne ilgesnė nei 7,200 sekundžių. Atpažintas failas, neatitinkantis šių patikrų, atmetamas su 422 unsupported_audio. Failas, kurio nepavyksta perskaityti nė vienu iš šių formatų, šiuo metu gali būti atmestas su serverio klaida (500); tokio failo nepateikite pakartotinai jo nepakeitę. Vien failo plėtinys suderinamumo nepatvirtina.

Šių patikrų sėkmė negarantuoja, kad garsą pavyks dekoduoti. Garsas apdorojamas kaip vienas arba du kanalai. Failo, turinčio daugiau nei du garso kanalus, failo, kurio dekoduotas garsas ilgesnis nei 2 valandos, arba bet kurio kito failo, kurio dekoduoti apdorojant nepavyksta, užduotis baigiama būsena failed, paprastai su kodu decode_failed, ir mokestis netaikomas. Prieš pateikdami daugiakanalį garsą konvertuokite į monofoninį arba stereofoninį.

Neprivaloma kalbos užuomina yra mažosiomis raidėmis užrašytas dviejų arba trijų raidžių šnekamosios kalbos kodas, pavyzdžiui, en. Jei užuominos neteikiate, praleiskite lauką; api.multi.tel atmeta tuščią eilutę. Užuomina padeda apdoroti, bet netikrinama pagal palaikomų kalbų sąrašą, todėl naudokite galiojantį įraše vartojamos kalbos kodą.

Pateikite transkripcijos užduotį

Siųskite JSON su antrašte Content-Type: application/json adresu POST https://api.multi.tel/v3/speech_to_text. Užklausos turinys gali būti iki 35 MiB, kad jame tilptų didžiausio leidžiamo dydžio failas po base64 kodavimo; didesnis turinys atmetamas su 413.

Bet kuri kita JSON savybė, įskaitant idempotency_key, atmetama su 400 invalid_transcription_request. Raktą siųskite antraštėje.

Idempotentiškumo raktas

Kiekvienam pateikimui būtina Idempotency-Key antraštė, turinti nuo 1 iki 190 simbolių. Naudokite ASCII raides, skaitmenis, -, _, . ir : be tarpų pradžioje ar pabaigoje: suderinamumo serveris pašalina aplinkinius tarpo simbolius ir matuoja raktą baitais, todėl kiti simboliai abiejuose serveriuose gali būti skaičiuojami skirtingai. Trūkstamas arba 191 ar daugiau simbolių turintis raktas atmetamas su 400.

Raktai priskiriami jūsų paskyrai ir kalbos transkribavimui abiejuose serveriuose bei naudojant visus jūsų paskyros prisijungimo duomenis. Pakartotinai siunčiant tą patį raktą su tuo pačiu failu ir kalba grąžinama esama užduotis su HTTP 200 ir duplicate: true, nepriklausomai nuo jos būsenos ir net jei apdorojimas buvo atnaujintas po užduoties sukūrimo, be pakartotinio mokesčio. Naudojant tą patį raktą su kitu failu arba kalba grąžinama 409 idempotency_conflict. Naujas raktas sukuria naują užduotį net identiškam failui; jei apdorojimas baigiamas sėkmingai, taikomas atskiras mokestis.

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'

Nauja užduotis grąžina HTTP 202 su toliau parodytais laukais, o pakartotinis pateikimas grąžina HTTP 200 su visu užduoties objektu, aprašytu skyriuje Transkripcijos gavimas. Užduoties ID, UUID, skaitykite iš data.id. Naujos užduoties atsakymas atrodo taip (identifikatorius ir reikšmės yra pavyzdžiai):

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

Kol užduotis yra eilėje arba vykdoma, durationSeconds, billedSeconds ir costUsd yra įverčiai iš failo metaduomenų. Galutinis mokestis apskaičiuojamas pagal dekoduotą trukmę.

Pateikimas taip pat gali grąžinti 402 insufficient_balance, kai išankstinio mokėjimo likučio nepakanka šiai užduočiai kartu su kitomis nebaigtomis jūsų užduotimis, 429 transcription_queue_full, kai jūsų paskyroje arba paslaugoje yra per daug nebaigtų užduočių, 429 audio_validation_busy, kai failų tikrinimo pajėgumai išnaudoti, ir 503 paid_transcription_not_enabled, kai mokama transkripcija išjungta. Gavę 429 ar 503 atsakymą, vėliau bandykite dar kartą su tuo pačiu raktu.

Gaukite įvertį nesukurdami užduoties

Siųskite tą patį JSON turinį adresu POST https://api.multi.tel/v3/speech_to_text/estimate. Idempotentiškumo raktas nereikalingas. Įvertis patikrina ir išmatuoja failą, bet jo netranskribuoja, nesukuria užduoties, nerezervuoja lėšų, netikrina likučio ir neapmokestina paskyros. language užuomina priimama, bet įverčiui įtakos neturi.

Sėkmingas įvertis grąžina HTTP 200 su laukais estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd ir costUsd objekte data. Naudojama failo metaduomenyse nurodyta trukmė, o už baigtą užduotį mokestis skaičiuojamas pagal dekoduotą trukmę, kuri gali skirtis. Įverčiams taikomos tos pačios failo patikros kaip ir pateikiamoms užduotims. Jie pasiekiami tik kai mokama transkripcija įjungta (kitu atveju 503 paid_transcription_not_enabled). Jie gali grąžinti 429 audio_validation_busy, kai failų tikrinimo pajėgumai išnaudoti; trumpai palaukę bandykite dar kartą.

Transkripcijos gavimas

Periodiškai užklauskite GET /v3/speech_to_text/JOB_ID, kaip aprašyta užduočių eigos vadove. Užduoties objektas turi šiuos laukus:

Transkripcijos, jų laiko žymos, kalbos ir kanalų žymos sukuriamos automatiškai, todėl tikslumas negarantuojamas. Bet kurį kokybės požymį laikykite priežastimi peržiūrėti rezultatą, o svarbius vardus, skaičius ir įsipareigojimus palyginkite su originaliu garsu. Ilgi tylos ir labai tylūs tarpai praleidžiami ir nesukuria segmentų. Rezultatai neidentifikuoja atskirų kalbėtojų. Kai rezultato channelCount yra 2, kiekvienas segmentas turi channel reikšmę A (pirmasis, arba kairysis, kanalas) arba B (antrasis, arba dešinysis, kanalas). Tai atskiria kalbėtojus tik tada, kai kiekvienas buvo įrašytas atskirame kanale. Už dviejų kanalų garsą mokestis taikomas vieną kartą pagal praėjusią trukmę, o ne už kiekvieną kanalą. Monofoninių rezultatų kanalai nežymimi.

api.multitel.net naudojimas

Suderinamumo galinis taškas POST https://api.multitel.net/v3/speech_to_text priima multipart/form-data su audio failo dalimi ir neprivalomu language lauku vietoj JSON audioBase64. Tuščia language reikšmė laikoma užuominos nebuvimu. Siųskite tą pačią Idempotency-Key antraštę. Jei jos nėra, šis serveris taip pat priima idempotency_key formos lauką. Laukai, pavadinti source, free, billing_source, realtime arba stream, atmetami su 400 unsupported_transcription_option; kiti formos laukai ignoruojami. Šis serveris taip pat grąžina šias klaidas:

• 400 idempotency_key_required, kai rakto nėra arba jis per ilgas.
• 400 audio_upload_required, kai įkeliamo failo nėra arba jis gautas ne visas.
• 400 invalid_language, kai kalba negaliojanti.
• 413 invalid_audio_size, kai failas tuščias arba per didelis.
• 400 invalid_job, kai užduoties ID formatas netaisyklingas.

Šio serverio kalbos transkribavimo paslaugos atsakymai naudoja apvalkalą {"status":{"code":HTTP_STATUS},"response":{...}}. Atminkite, kad status yra objektas, o ne eilutė. Sėkmės atveju response turi tą patį objektą kaip data pagrindiniame serveryje, todėl užduoties ID yra response.id. Klaidos atveju response.code turi klaidos kodą; pranešimas ir užklausos ID nepateikiami. Autentifikavimo klaidas (401) grąžina bendroji serverio prisijungimo patikra; jų turinys gali skirtis, todėl prieš analizuodami patikrinkite HTTP būseną. Nekeiskite įkėlimo kodavimo ar atsakymų analizatoriaus tarp serverių.

Norėdami gauti įvertį šiame serveryje, siųskite tuos pačius multipart laukus POST užklausa adresu /v3/speech_to_text/estimate. Idempotentiškumo raktas nereikalingas; įvertis pateikiamas objekte 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'