MultiTEL
Programeri

Zadaci obrade govora i prijevoda

Autentificirajte zahtjeve, provjeravajte status zadataka, ponovite slanja s neizvjesnim ishodom, podmirite zadatke koji čekaju plaćanje, provjerite potrošnju te obradite pogreške i ograničenja.

Na ovoj stranici
  1. Autentifikacija
  2. Provjeravajte je li zadatak dovršen
  3. Sigurno ponovite zahtjeve s neizvjesnim ishodom
  4. Oslobodite rezultat nakon nadoplate
  5. Provjerite potrošnju
  6. Ograničenja
  7. Obradite pogreške zahtjeva

U nastavku zamijenite SERVICE vrijednošću speech_to_text ili translate, a JOB_ID vraćenim UUID-om. Sve operacije zahtijevaju vjerodajnice vašeg računa, kako je opisano u odjeljku Autentifikacija, i ograničene su na račun kojem zadatak pripada. Zadatak možete pročitati s bilo kojeg API poslužitelja, ali svaki koristi vlastitu omotnicu odgovora, pa dosljedno koristite isti poslužitelj.

PoslužiteljUspjehPogreška
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"}}

Na poslužitelju api.multitel.net pogreške autentifikacije (401) vraćaju se prije primjene ove omotnice i mogu imati drukčije tijelo, pa provjerite HTTP status prije parsiranja.

Autentifikacija

Svaki zahtjev mora sadržavati vjerodajnice vašeg računa. Zadaci, ključevi idempotentnosti, ograničenja, potrošnja i naknade pripadaju računu koji je vlasnik vjerodajnica. Zajednički su svim vjerodajnicama tog računa na oba poslužitelja, neovisno o tome kojim se vjerodajnicama šalje zahtjev.

  • HTTP Basic (Authorization: Basic ili curl --user). Prihvaćaju se vjerodajnice API računa vrste lozinka, podračuna ili vaše vjerodajnice za prijavu na račun. Preporučujemo zaseban API račun. Korisničko ime ne smije sadržavati dvotočku, a ni korisničko ime ni lozinka ne smiju biti prazni.
  • Bearer token (Authorization: Bearer YOUR_TOKEN). Prihvaća se za API račun vrste token. API računi s tokenom moraju imati IP ograničenje, a zahtjevi moraju dolaziti s dopuštene adrese. Oba API poslužitelja prihvaćaju IPv4 adrese i CIDR raspone konfigurirane za račun. Token se ne može poslati kao Basic lozinka. Provjerite radi li vaš token na poslužitelju koji koristite.
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

Ako je API račun ograničen prema IP adresi, šaljite zahtjeve s dopuštene adrese. Nedostajuće ili nevaljane vjerodajnice vraćaju 401. Na poslužitelju api.multitel.net valjane vjerodajnice koje ne dopuštaju korištenje ovih usluga, primjerice vjerodajnice računa s tokenom poslane kao Basic, vraćaju 403 s kodom unsupported_transcription_principal ili unsupported_translation_principal. Ponavljani neuspješni pokušaji autentifikacije s jedne adrese na poslužitelju api.multitel.net mogu dovesti do blokiranja te adrese, pa ispravite vjerodajnice prije ponovnog pokušaja.

Provjeravajte je li zadatak dovršen

Pošaljite zahtjev GET /v3/SERVICE/JOB_ID. Preporučujemo provjeravanje najviše jednom svake 3 sekunde. Vanjska omotnica opisuje zahtjev; provjerite polje status unutarnjeg zadatka kako biste utvrdili je li obrada završena.

StatusZnačenje
queuedPrihvaćen i čeka obradu. Zadaci jednog računa obrađuju se jedan po jedan, naizmjenično sa zadacima drugih računa.
runningObrada je u tijeku. Polje progress može imati vrijednost null; sama vrijednost null ne znači da je zadatak zapeo.
completedRezultat je dostupan. Sačuvajte ga i usporedite važne pojedinosti s izvornikom.
failedProvjerite failureCode. Neuspješna obrada ne naplaćuje se. Ispravite uzrok i pošaljite zadatak s novim ključem; ponovno slanje istog ključa vraća isti neuspjeli zadatak.
awaiting_paymentObrada je završena, ali unaprijed uplaćeno stanje nije moglo pokriti naknadu. Rezultat je spremljen i zadržava se do podmirenja zadatka.
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"

Na poslužitelju api.multitel.net postavite HOST na https://api.multitel.net i čitajte .response.id umjesto .data.id.

Sigurno ponovite zahtjeve s neizvjesnim ishodom

Ako istekne vrijeme čekanja pri slanju ili se vrati 429 ili status 5xx, ponovno pošaljite isti ulaz s istim ključem idempotentnosti. Odgovor bilo kojeg poslužitelja može se izgubiti ili biti zamijenjen pogreškom nakon prihvaćanja zadatka; ponovno slanje s istim ključem vraća zadatak ako postoji. Ponovna upotreba ključa s drukčijim ulazom vraća 409 s kodom idempotency_conflict. Neke se pogreške ponavljaju pri svakom pokušaju, primjerice 503 dok je plaćena usluga onemogućena ili 500 za audiodatoteku koja se ne može pročitati, pa prestanite nakon nekoliko pokušaja.

Promjena ključa ima različite učinke za pojedine usluge.

  • Za pretvaranje govora u tekst novi ključ stvara novi zadatak sa zasebnom naplatom ako obrada uspješno završi. Izvorni ključ i dalje vraća izvorni zadatak, čak i nakon ažuriranja obrade.
  • Za prijevod novi ključ s identičnim sadržajem vraća odgovarajući zadatak koji čeka u redu, obrađuje se, dovršen je ili čeka plaćanje, bez nove naknade. Novi zadatak stvara se ako prethodni nije uspio ili se promijenila verzija obrade. Ponovni pokušaj prijevoda s izvornim ključem nakon promjene verzije obrade vraća 409, pa sačuvajte izvorni ID zadatka i pročitajte zadatak izravno.

Oslobodite rezultat nakon nadoplate

Za zadatak sa statusom awaiting_payment nadoplatite račun tako da stanje bude barem jednako vrijednosti costUsd zadatka, zaokruženoj naviše na sljedeći višekratnik iznosa $0.00001, a zatim pošaljite POST /v3/SERVICE/JOB_ID/settle. Iznosi se terete u cijelim koracima od $0.00001 i uključuju preneseni ostatak iz ranijih zadataka iste usluge, pa terećeni iznos može premašiti costUsd za manje od $0.00001. Na poslužitelju api.multi.tel pošaljite JSON {} ili prazno tijelo; svako svojstvo u tijelu odbija se statusom 400. Poslužitelj api.multitel.net zanemaruje tijelo. Podmirenje oslobađa spremljeni rezultat bez ponovnog izvođenja transkripcije ili prijevoda. Odgovor sadrži zadatak; provjerite ima li status completed. Ako stanje i dalje nije dovoljno, zadatak ostaje u statusu awaiting_payment, a odgovor i dalje ima HTTP status 200.

Za pretvaranje govora u tekst podmirenje već dovršenog zadatka vraća ga s oznakom duplicate: true, a podmirenje zadatka koji čeka u redu, obrađuje se ili nije uspio vraća 409 s kodom transcription_not_awaiting_payment. Za prijevod podmirenje zadatka u bilo kojem drugom statusu vraća zadatak nepromijenjen. Podmirenje je dostupno samo dok je plaćena obrada omogućena (inače 503). Zadaci koji čekaju plaćanje računaju se kao rezervirani trošak, pa računima s unaprijed uplaćenim sredstvima mogu blokirati slanje novih plaćenih zadataka statusom 402 dok se ne podmire.

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"

Provjerite potrošnju

Koristite GET /v3/SERVICE/usage. Neobavezni parametri from i to datumi su u UTC-u u formatu YYYY-MM-DD, a oba granična datuma uključena su u razdoblje. Ako nisu navedeni, from zadano označava datum 30 dana prije današnjeg, a to današnji datum (UTC). to ne smije biti prije from, a datumi smiju biti udaljeni najviše 366 dana (do 367 datuma). Nevaljani kalendarski datumi te obrnut ili dulji raspon vraćaju 400, kao i drugi parametri upita na poslužitelju 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"

Odgovor sadrži mode, currency (USD), from, to i days, popis poredan od najnovijeg prema najstarijem.

  • Stavke pretvaranja govora u tekst grupirane su prema datumu i izvoru. Sadrže date, source (api ili hpbx za snimke Hosted PBX-a), files, audioSeconds, billedSeconds, accruedUsd i debitedUsd.
  • Stavke prijevoda grupirane su prema datumu, izvoru i mehanizmu za prevođenje. Sadrže date, source, engine, jobs, sourceCharacters, accruedUsd i debitedUsd.

accruedUsd točan je trošak s devet decimalnih mjesta, a debitedUsd terećeni je iznos s pet decimalnih mjesta. Potrošnja se bilježi na UTC datum kada je naknada za pojedini zadatak podmirena, pa se zadaci koji čekaju u redu, obrađuju se, nisu uspjeli ili čekaju plaćanje ne prikazuju.

Ograničenja

Svaki račun može imati ukupno najviše 50 otvorenih zadataka pretvaranja govora u tekst i prijevoda: u redu čekanja, u obradi ili na čekanju plaćanja, uključujući obradu snimki Hosted PBX-a. Kada se dosegne to ograničenje ili ukupni kapacitet usluge, slanje vraća 429 s kodom transcription_queue_full ili translation_queue_full. Poslužitelj api.multi.tel također ograničava svaku klijentsku IP adresu na 300 zahtjeva u minuti za sve zahtjeve tom poslužitelju zajedno. To ograničenje vraća 429 sa zaglavljima ograničenja učestalosti i običnim tekstualnim tijelom umjesto JSON omotnice pogreške.

Obradite pogreške zahtjeva

Na primarnom poslužitelju neuspjesi vraćaju HTTP status pogreške i JSON s poljima status: "error", code, message i requestId. Svaki odgovor sadrži i zaglavlje X-Request-ID. Možete navesti vlastitu vrijednost; vrijednosti dulje od 128 znakova skraćuju se. Poslužitelj za kompatibilnost vraća samo kod pogreške u response.code. Zabilježite ID zahtjeva, ako je dostupan, i kod pogreške, a audio, tekst i vjerodajnice nemojte bilježiti u zapisnike.

Uobičajeni statusi:

StatusZnačenje
400Nevaljan ulaz.
401Nedostajuće ili nevaljane vjerodajnice.
402Nedovoljno unaprijed uplaćenih sredstava.
403Na poslužitelju za kompatibilnost vjerodajnice koje ne dopuštaju korištenje ovih usluga.
404Nepoznat zadatak ili ruta.
405Nepodržana metoda ili nepoznata putanja unutar usluge.
409Proturječan ulaz, prijevod na isti jezik ili podmirenje govornog zadatka koji ne čeka plaćanje.
413Preveliko tijelo ili datoteka.
422Nepodržan audio ili nedostupan standardni jezični par.
429Ograničenja reda čekanja, provjere valjanosti ili učestalosti zahtjeva.
500Neočekivana pogreška poslužitelja, uključujući audiodatoteku koja se ne može pročitati.
503Onemogućena ili privremeno nedostupna usluga ili vjerodajnice koje se trenutačno ne mogu provjeriti.

Slijedite vraćeni kod pogreške umjesto pretpostavke da svaka pogreška provjere valjanosti ima isti status.

Za 429 ili 503 pričekajte i pokušajte ponovno s postupnim povećavanjem razmaka i istim ključem slanja; poštujte Retry-After ako je prisutno. Za nevaljan ulaz ili vjerodajnice najprije ispravite uzrok. Nemojte opetovano slati nove ključeve dok raniji zadaci još čekaju u redu.