Kalbos apdorojimo ir vertimo užduotys

Toliau pakeiskite SERVICE reikšme speech_to_text arba translate, o JOB_ID – grąžintu UUID. Visoms operacijoms reikia jūsų paskyros prisijungimo duomenų, kaip aprašyta skyriuje Autentifikavimas, ir jos apribotos užduotį valdančia paskyra. Užduotį galima nuskaityti iš bet kurio API serverio, tačiau kiekvienas naudoja savo atsakymo apvalkalą, todėl nuosekliai naudokite tą patį serverį.

Serveryje api.multitel.net autentifikavimo klaidos (401) grąžinamos prieš pritaikant šį apvalkalą, todėl jų turinys gali būti kitoks. Prieš analizuodami atsakymą patikrinkite HTTP būsenos kodą.

Autentifikavimas

Kiekvienoje užklausoje turi būti jūsų paskyros prisijungimo duomenys. Užduotys, idempotentiškumo raktai, ribojimai, naudojimas ir mokesčiai priklauso paskyrai, kuriai priklauso prisijungimo duomenys. Jie bendri visiems tos paskyros prisijungimo duomenims abiejuose serveriuose, nesvarbu, kuriais duomenimis siunčiama užklausa.

• HTTP Basic (Authorization: Basic arba curl --user). Priimami slaptažodžio tipo API paskyros, antrinės paskyros arba jūsų paskyros prisijungimo duomenys. Rekomenduojame atskirą API paskyrą. Naudotojo varde negali būti dvitaškio, o naudotojo vardas ir slaptažodis negali būti tušti.
• Bearer prieigos raktas (Authorization: Bearer YOUR_TOKEN). Priimamas prieigos rakto tipo API paskyroms. Tokioms API paskyroms būtinas IP ribojimas, o užklausos turi būti siunčiamos iš leidžiamo adreso. Abu API serveriai priima paskyrai sukonfigūruotus IPv4 adresus ir CIDR diapazonus. Prieigos rakto negalima siųsti kaip Basic slaptažodžio. Įsitikinkite, kad jūsų prieigos raktas veikia naudojamame serveryje.

API_TOKEN="your-api-token"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $API_TOKEN" \
  https://api.multi.tel/v3/speech_to_text

Jei API paskyra apribota pagal IP adresą, siųskite užklausas iš leidžiamo adreso. Trūkstami arba netinkami prisijungimo duomenys grąžina kodą 401. Serveryje api.multitel.net galiojantys prisijungimo duomenys, kuriais negalima naudotis šiomis paslaugomis, pavyzdžiui, prieigos rakto paskyros duomenys, siunčiami kaip Basic, grąžina kodą 403 ir klaidą unsupported_transcription_principal arba unsupported_translation_principal. Pasikartojantys nesėkmingi autentifikavimo bandymai iš vieno adreso serveryje api.multitel.net gali užblokuoti tą adresą, todėl prieš bandydami dar kartą pataisykite prisijungimo duomenis.

Periodiškai tikrinkite, ar užduotis baigta

Siųskite užklausą GET /v3/SERVICE/JOB_ID. Rekomenduojame tikrinti ne dažniau kaip kartą per 3 sekundes. Išorinis apvalkalas aprašo užklausą; patikrinkite jame esančios užduoties lauką status, kad nustatytumėte, ar apdorojimas baigtas.

API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/$JOB_ID"

Serveryje api.multitel.net nustatykite HOST reikšmę į https://api.multitel.net ir skaitykite .response.id vietoj .data.id.

Saugiai kartokite užklausas, kurių rezultatas neaiškus

Jei pateikimo laikas baigiasi arba grąžinamas kodas 429 ar būsena 5xx, pakartotinai siųskite tuos pačius įvesties duomenis su tuo pačiu idempotentiškumo raktu. Bet kurio serverio atsakymas gali dingti arba būti pakeistas klaida jau priėmus užduotį; pakartotinis siuntimas su tuo pačiu raktu grąžina užduotį, jei ji yra. Pakartotinis rakto naudojimas su kitais įvesties duomenimis grąžina kodą 409 ir klaidą idempotency_conflict. Kai kurios klaidos kartojasi per kiekvieną bandymą, pavyzdžiui, 503, kai mokama paslauga išjungta, arba 500, kai garso failo negalima perskaityti, todėl po kelių bandymų sustokite.

Rakto pakeitimo poveikis priklauso nuo paslaugos.

• Kalbos pavertimo tekstu atveju naujas raktas sukuria naują užduotį, už kurią sėkmingai baigus apdorojimą imamas atskiras mokestis. Pradinis raktas ir toliau grąžina pradinę užduotį net atnaujinus apdorojimą.
• Vertimo atveju naujas raktas su identišku turiniu grąžina atitinkamą eilėje esančią, apdorojamą, baigtą arba apmokėjimo laukiančią užduotį be naujo mokesčio. Nauja užduotis sukuriama, jei ankstesnė nepavyko arba pasikeitė apdorojimo versija. Pakartotinis vertimo bandymas su pradiniu raktu po apdorojimo versijos pakeitimo grąžina kodą 409, todėl išsaugokite pradinį užduoties ID ir skaitykite užduotį tiesiogiai.

Gaukite rezultatą papildę likutį

Jei užduoties būsena yra awaiting_payment, papildykite likutį, kad jis būtų ne mažesnis už užduoties costUsd reikšmę, suapvalintą aukštyn iki artimiausio $0.00001 kartotinio, tada siųskite POST /v3/SERVICE/JOB_ID/settle. Lėšos nurašomos sveikais $0.00001 žingsniais, įskaitant iš ankstesnių tos pačios paslaugos užduočių perkeltą likutinę dalį, todėl nurašyta suma gali viršyti costUsd reikšmę mažesne nei $0.00001 suma. Serveryje api.multi.tel siųskite JSON {} arba tuščią turinį; bet kuri turinyje esanti savybė atmetama su kodu 400. Serveris api.multitel.net turinį ignoruoja. Apmokėjimas atveria išsaugotą rezultatą iš naujo nevykdant transkripcijos ar vertimo. Atsakyme yra užduotis; patikrinkite, ar jos būsena yra completed. Jei likučio vis dar nepakanka, užduoties būsena lieka awaiting_payment, o atsakymo HTTP kodas vis tiek yra 200.

Kalbos pavertimo tekstu atveju jau baigtos užduoties apmokėjimo užklausa grąžina ją su duplicate: true, o eilėje esančios, apdorojamos arba nepavykusios užduoties apmokėjimas grąžina kodą 409 ir klaidą transcription_not_awaiting_payment. Vertimo atveju bet kurios kitos būsenos užduoties apmokėjimo užklausa grąžina užduotį nepakeistą. Apmokėjimas galimas tik įjungus mokamą apdorojimą (kitu atveju 503). Apmokėjimo laukiančios užduotys įskaičiuojamos kaip rezervuotos išlaidos, todėl išankstinio mokėjimo paskyroms jos gali blokuoti naujų mokamų užduočių pateikimą su kodu 402, kol bus apmokėtos.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -X POST -H "Content-Type: application/json" --data '{}' \
  "$HOST/v3/$SERVICE/$JOB_ID/settle"

Tikrinkite naudojimą

Naudokite GET /v3/SERVICE/usage. Neprivalomi parametrai from ir to yra UTC datos formatu YYYY-MM-DD, o abi ribinės datos įtraukiamos. Jei parametrai nenurodyti, from numatytoji reikšmė yra 30 dienų iki šiandienos, o to – šiandienos data (UTC). to negali būti ankstesnė už from, o datos gali skirtis ne daugiau kaip 366 dienomis (iki 367 datų). Netinkamos kalendorinės datos, atvirkštinis arba ilgesnis laikotarpis grąžina kodą 400, kaip ir kiti užklausos parametrai serveryje api.multi.tel.

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  "$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"

Atsakyme yra mode, currency (USD), from, to ir days – sąrašas nuo naujausių įrašų iki seniausių.

• Kalbos pavertimo tekstu įrašai grupuojami pagal datą ir šaltinį. Juose yra date, source (api arba hpbx Hosted PBX įrašams), files, audioSeconds, billedSeconds, accruedUsd ir debitedUsd.
• Vertimo įrašai grupuojami pagal datą, šaltinį ir vertimo modulį. Juose yra date, source, engine, jobs, sourceCharacters, accruedUsd ir debitedUsd.

accruedUsd yra tiksli kaina devynių skaitmenų po kablelio tikslumu, o debitedUsd – nurašyta suma penkių skaitmenų po kablelio tikslumu. Naudojimas registruojamas pagal UTC datą, kai apmokamas kiekvienos užduoties mokestis, todėl eilėje esančios, apdorojamos, nepavykusios ir apmokėjimo laukiančios užduotys nerodomos.

Ribojimai

Kiekvienoje paskyroje iš viso gali būti ne daugiau kaip 50 nebaigtų kalbos pavertimo tekstu ir vertimo užduočių: eilėje, apdorojamų arba laukiančių apmokėjimo, įskaitant Hosted PBX įrašų apdorojimą. Pasiekus šią ribą arba bendrą paslaugos pajėgumą, pateikimas grąžina kodą 429 ir klaidą transcription_queue_full arba translation_queue_full. Serveris api.multi.tel taip pat riboja kiekvieną kliento IP adresą iki 300 užklausų per minutę, skaičiuojant visas užklausas tam serveriui. Viršijus šią ribą grąžinamas kodas 429 su užklausų dažnio ribojimo antraštėmis ir paprasto teksto turiniu vietoj JSON klaidos apvalkalo.

Tvarkykite užklausų klaidas

Pagrindiniame serveryje nesėkmingos užklausos grąžina HTTP klaidos kodą ir JSON su status: "error", code, message ir requestId. Kiekviename atsakyme taip pat yra X-Request-ID antraštė. Galite pateikti savo reikšmę; ilgesnės nei 128 simbolių reikšmės nukerpamos. Suderinamumo serveris grąžina tik klaidos kodą lauke response.code. Registruokite užklausos ID, jei jis pasiekiamas, ir klaidos kodą, bet į žurnalus neįtraukite garso, teksto ar prisijungimo duomenų.

Dažniausi būsenos kodai:

Vadovaukitės grąžintu klaidos kodu, o ne prielaida, kad visų tikrinimo klaidų būsenos kodas vienodas.

Gavę 429 arba 503, palaukite ir bandykite dar kartą didindami laukimo intervalą bei naudodami tą patį pateikimo raktą; laikykitės Retry-After antraštės, jei ji pateikta. Netinkamų įvesties ar prisijungimo duomenų atveju pirmiausia pašalinkite priežastį. Nesiųskite vis naujų raktų, kol ankstesnės užduotys tebėra eilėje.