MultiTEL
Zhvilluesit

Detyrat e të folurit dhe përkthimit

Autentikoni kërkesat, kontrolloni statusin e detyrave, riprovoni dërgimet me rezultat të pasigurt, shlyeni pagesat për rezultatet në pritje të pagesës, kontrolloni përdorimin dhe trajtoni gabimet e kufijtë.

Në këtë faqe
  1. Autentikimi
  2. Kontrolloni periodikisht deri në përfundim
  3. Riprovoni në mënyrë të sigurt kërkesat me rezultat të pasigurt
  4. Merrni rezultatin pas shtimit të fondeve
  5. Kontrolloni përdorimin
  6. Kufijtë
  7. Trajtoni gabimet e kërkesave

Zëvendësoni SERVICE më poshtë me speech_to_text ose translate, dhe JOB_ID me UUID-në e kthyer. Të gjitha veprimet kërkojnë kredencialet e llogarisë suaj, siç përshkruhet te Autentikimi, dhe kufizohen te llogaria pronare. Një detyrë mund të lexohet nga cilido prej dy serverëve API, por secili përdor mbështjellësin e vet të përgjigjes, ndaj përdorni vazhdimisht të njëjtin server.

ServeriSuksesGabim
api.multi.tel{"status":"success","data":{...}}{"status":"error","code":"...","message":"...","requestId":"..."}
api.multitel.net{"status":{"code":200},"response":{...}}{"status":{"code":409},"response":{"code":"idempotency_conflict"}}

Në api.multitel.net, dështimet e autentikimit (401) kthehen përpara se të zbatohet ky mbështjellës dhe mund të kenë trup tjetër përgjigjeje, ndaj kontrolloni statusin HTTP përpara analizimit të përgjigjes.

Autentikimi

Çdo kërkesë duhet të përmbajë kredencialet e llogarisë suaj. Detyrat, çelësat e idempotencës, kufijtë, përdorimi dhe tarifat i përkasin llogarisë që zotëron kredencialet. Ato janë të përbashkëta për të gjitha kredencialet e asaj llogarie në të dy serverët, pavarësisht cilat kredenciale dërgojnë kërkesën.

  • HTTP Basic (Authorization: Basic ose curl --user). Pranohen kredencialet e një llogarie API të tipit fjalëkalim, të një nënllogarie ose të hyrjes në llogarinë tuaj. Rekomandojmë një llogari API të posaçme. Emri i përdoruesit nuk mund të përmbajë dy pika dhe as emri i përdoruesit, as fjalëkalimi nuk mund të jenë bosh.
  • Token Bearer (Authorization: Bearer YOUR_TOKEN). Pranohet për një llogari API të tipit token. Llogaritë API me token duhet të kenë kufizim IP dhe kërkesat duhet të vijnë nga një adresë e lejuar. Të dy serverët API pranojnë adresat IPv4 dhe intervalet CIDR të konfiguruara për llogarinë. Tokeni nuk mund të dërgohet si fjalëkalim Basic. Verifikoni që tokeni funksionon në serverin që përdorni.
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

Nëse llogaria API kufizohet sipas adresës IP, dërgoni kërkesa nga një adresë e lejuar. Kredencialet që mungojnë ose janë të pavlefshme kthejnë 401. Në api.multitel.net, kredencialet e vlefshme që nuk mund t’i përdorin këto shërbime, si kredencialet e një llogarie me token të dërguara si Basic, kthejnë 403 unsupported_transcription_principal ose unsupported_translation_principal. Autentikimi i dështuar në mënyrë të përsëritur nga një adresë në api.multitel.net mund të shkaktojë bllokimin e saj, ndaj korrigjoni kredencialet përpara se të provoni sërish.

Kontrolloni periodikisht deri në përfundim

Dërgoni kërkesën GET /v3/SERVICE/JOB_ID. Rekomandojmë ta kontrolloni statusin jo më shpesh se një herë çdo 3 sekonda. Mbështjellësi i jashtëm përshkruan kërkesën; kontrolloni fushën status të detyrës brenda tij për të përcaktuar nëse përpunimi ka përfunduar.

StatusiKuptimi
queuedU pranua dhe po pret. Detyrat e një llogarie përpunohen një nga një, duke alternuar me detyrat e llogarive të tjera.
runningPo përpunohet. Fusha progress mund të jetë null; vetëm vlera null nuk do të thotë se detyra ka ngecur.
completedRezultati është i disponueshëm. Ruajeni dhe krahasoni hollësitë e rëndësishme me burimin.
failedKontrolloni failureCode. Puna e dështuar nuk tarifohet. Korrigjoni shkakun dhe dërgojeni me një çelës të ri; ridërgimi me të njëjtin çelës kthen të njëjtën detyrë të dështuar.
awaiting_paymentPërpunimi përfundoi, por balanca e parapaguar nuk mjaftoi për tarifën. Rezultati ruhet dhe mbahet i padisponueshëm derisa të shlyhet pagesa e detyrës.
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"

Në api.multitel.net, vendosni HOST në https://api.multitel.net dhe lexoni .response.id në vend të .data.id.

Riprovoni në mënyrë të sigurt kërkesat me rezultat të pasigurt

Nëse dërgimit i mbaron koha e pritjes ose ai kthen 429 apo një status 5xx, ridërgoni të njëjtat të dhëna hyrëse me të njëjtin çelës idempotence. Përgjigjja nga cilido server mund të humbasë ose të zëvendësohet me gabim pasi puna të jetë pranuar; ridërgimi me të njëjtin çelës kthen detyrën nëse ajo ekziston. Ripërdorimi i një çelësi me të dhëna të ndryshme kthen 409 idempotency_conflict. Disa gabime përsëriten në çdo përpjekje, si 503 kur një shërbim me pagesë është çaktivizuar ose 500 për një skedar audio që nuk mund të lexohet, ndaj ndaloni pas disa përpjekjesh.

Ndryshimi i çelësit ka pasoja të ndryshme për secilin shërbim.

  • Për kthimin e të folurit në tekst, një çelës i ri krijon një detyrë të re me tarifë më vete nëse përpunimi përfundon me sukses. Çelësi fillestar vazhdon të kthejë detyrën fillestare, edhe pasi përpunimi përditësohet.
  • Për përkthimin, një çelës i ri me përmbajtje identike kthen një detyrë përkatëse në radhë, në përpunim, të përfunduar ose në pritje të pagesës, pa tarifë të re. Krijohet punë e re nëse detyra e mëparshme dështoi ose versioni i përpunimit ka ndryshuar. Riprovimi i përkthimit me çelësin fillestar kthen 409 pas një ndryshimi të versionit të përpunimit, ndaj ruani ID-në e detyrës fillestare dhe lexojeni detyrën drejtpërdrejt.

Merrni rezultatin pas shtimit të fondeve

Për një detyrë me status awaiting_payment, shtoni fonde që balanca të jetë të paktën sa vlera costUsd e detyrës, e rrumbullakosur lart në shumëfishin e ardhshëm të $0.00001, pastaj dërgoni POST /v3/SERVICE/JOB_ID/settle. Debitimet bëhen në hapa të plotë prej $0.00001 dhe përfshijnë çdo mbetje të bartur nga detyrat e mëparshme të të njëjtit shërbim, ndaj shuma e debituar mund ta tejkalojë costUsd me më pak se $0.00001. Në api.multi.tel, dërgoni JSON {} ose trup bosh; çdo veti në trup refuzohet me 400. api.multitel.net e shpërfill trupin. Shlyerja e pagesës vë në dispozicion rezultatin e ruajtur pa kryer sërish transkriptim ose përkthim. Përgjigjja përmban detyrën; kontrolloni që statusi i saj të jetë completed. Nëse balanca ende nuk mjafton, detyra mbetet me status awaiting_payment dhe përgjigjja mbetet HTTP 200.

Për kthimin e të folurit në tekst, shlyerja e një detyre tashmë të përfunduar e kthen atë me duplicate: true, ndërsa shlyerja e një detyre në radhë, në përpunim ose të dështuar kthen 409 transcription_not_awaiting_payment. Për përkthimin, shlyerja e një detyre në cilindo status tjetër e kthen detyrën pa ndryshime. Shlyerja është e disponueshme vetëm kur përpunimi me pagesë është aktiv (përndryshe 503). Detyrat në pritje të pagesës llogariten si kosto e rezervuar, ndaj për llogaritë e parapaguara mund të bllokojnë dërgime të reja me pagesë me 402 derisa të shlyhen.

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"

Kontrolloni përdorimin

Përdorni GET /v3/SERVICE/usage. Parametrat opsionalë from dhe to janë data UTC në formatin YYYY-MM-DD dhe përfshihen të dyja datat kufitare. Nëse mungojnë, from merr si parazgjedhje datën 30 ditë para ditës së sotme dhe to datën e sotme (UTC). Data to nuk duhet të jetë më e hershme se from dhe datat mund të jenë larg njëra-tjetrës maksimumi 366 ditë (deri në 367 data). Datat kalendarike të pavlefshme ose një interval i përmbysur apo më i gjatë kthejnë 400, po ashtu edhe parametrat e tjerë të kërkesës në 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"

Përgjigjja përmban mode, currency (USD), from, to dhe days, një listë të renditur me hyrjet më të reja në fillim.

  • Hyrjet e kthimit të të folurit në tekst grupohen sipas datës dhe burimit. Ato përmbajnë date, source (api ose hpbx për regjistrimet e Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd dhe debitedUsd.
  • Hyrjet e përkthimit grupohen sipas datës, burimit dhe motorit. Ato përmbajnë date, source, engine, jobs, sourceCharacters, accruedUsd dhe debitedUsd.

accruedUsd është kostoja e saktë me nëntë shifra pas presjes dhjetore, ndërsa debitedUsd është shuma e debituar me pesë shifra. Përdorimi regjistrohet në datën UTC kur është shlyer tarifa e secilës detyrë, ndaj detyrat në radhë, në përpunim, të dështuara dhe në pritje të pagesës nuk shfaqen.

Kufijtë

Çdo llogari mund të ketë maksimumi 50 detyra të pambyllura për kthimin e të folurit në tekst dhe përkthim së bashku: në radhë, në përpunim ose në pritje të pagesës, përfshirë punën për regjistrimet e Hosted PBX. Kur arrihet ky kufi ose kapaciteti i përgjithshëm i shërbimit, dërgimet kthejnë 429 transcription_queue_full ose translation_queue_full. api.multi.tel gjithashtu kufizon çdo adresë IP klienti në 300 kërkesa në minutë për të gjitha kërkesat drejt atij serveri së bashku. Ky kufi kthen 429 me titujt e kufizimit të shpeshtësisë dhe trup me tekst të thjeshtë në vend të mbështjellësit JSON të gabimit.

Trajtoni gabimet e kërkesave

Në serverin kryesor, dështimet kthejnë një status gabimi HTTP dhe JSON me status: "error", code, message dhe requestId. Çdo përgjigje përmban gjithashtu një titull X-Request-ID. Mund të jepni vlerën tuaj; vlerat më të gjata se 128 karaktere shkurtohen. Serveri i përputhshmërisë kthen vetëm kodin e gabimit në response.code. Regjistroni ID-në e kërkesës, kur është e disponueshme, dhe kodin e gabimit, por mos regjistroni audio, tekst ose kredenciale në regjistra.

Statuset e zakonshme:

StatusiKuptimi
400Të dhëna hyrëse të pavlefshme.
401Kredenciale që mungojnë ose janë të pavlefshme.
402Balancë e parapaguar e pamjaftueshme.
403Në serverin e përputhshmërisë, kredenciale që nuk mund t’i përdorin këto shërbime.
404Detyrë ose rrugë e panjohur.
405Metodë e pambështetur ose shteg i panjohur brenda një shërbimi.
409Të dhëna hyrëse në konflikt, përkthim në të njëjtën gjuhë ose shlyerje e një detyre të të folurit që nuk pret pagesë.
413Trup ose skedar tepër i madh.
422Audio e pambështetur ose çift gjuhësh standard i padisponueshëm.
429Kufij të radhës, vleftësimit ose shpeshtësisë së kërkesave.
500Gabim i papritur i serverit, përfshirë një skedar audio që nuk mund të lexohet.
503Shërbim i çaktivizuar ose përkohësisht i padisponueshëm, ose kredenciale që nuk mund të kontrollohen për momentin.

Ndiqni kodin e kthyer të gabimit në vend që të supozoni se çdo dështim vleftësimi ka të njëjtin status.

Për 429 ose 503, prisni dhe riprovoni me vonesa gjithnjë më të gjata dhe të njëjtin çelës dërgimi; respektoni Retry-After kur është i pranishëm. Për të dhëna hyrëse ose kredenciale të pavlefshme, korrigjoni më parë shkakun. Mos dërgoni vazhdimisht çelësa të rinj kur detyrat e mëparshme janë ende në radhë.