Runas apstrādes un tulkošanas darbi

Tālāk aizstājiet SERVICE ar speech_to_text vai translate un JOB_ID ar atgriezto UUID. Visām darbībām ir vajadzīgi jūsu konta autentifikācijas dati, kā aprakstīts sadaļā Autentifikācija, un tās ir ierobežotas ar kontu, kuram darbs pieder. Darbu var nolasīt no jebkura API servera, taču katrs izmanto savu atbildes apvalku, tāpēc konsekventi izmantojiet vienu serveri.

Serverī api.multitel.net autentifikācijas kļūdas (401) tiek atgrieztas pirms šī apvalka piemērošanas, un to saturs var atšķirties, tāpēc pirms atbildes parsēšanas pārbaudiet HTTP statusu.

Autentifikācija

Katrā pieprasījumā jābūt jūsu konta autentifikācijas datiem. Darbi, idempotences atslēgas, ierobežojumi, lietojums un maksas pieder kontam, kuram pieder autentifikācijas dati. Tie ir kopīgi visiem šī konta autentifikācijas datiem abos serveros neatkarīgi no tā, ar kuriem datiem pieprasījums tiek sūtīts.

• HTTP Basic (Authorization: Basic vai curl --user). Tiek pieņemti paroles tipa API konta, apakškonta vai jūsu konta pieteikšanās dati. Iesakām atsevišķu API kontu. Lietotājvārds nedrīkst saturēt kolu, lietotājvārds nedrīkst būt tukšs, un parole nedrīkst būt tukša.
• Bearer marķieris (Authorization: Bearer YOUR_TOKEN). Tiek pieņemts marķiera tipa API kontam. Šādiem API kontiem obligāti jābūt IP ierobežojumam, un pieprasījumiem jānāk no atļautas adreses. Abi API serveri pieņem kontam konfigurētās IPv4 adreses un CIDR diapazonus. Marķieri nevar sūtīt kā Basic paroli. Pārliecinieties, ka marķieris darbojas jūsu izmantotajā serverī.

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

Ja API kontam ir IP adreses ierobežojums, sūtiet pieprasījumus no atļautas adreses. Ja autentifikācijas datu nav vai tie nav derīgi, tiek atgriezts 401. Serverī api.multitel.net derīgi autentifikācijas dati, ar kuriem nevar izmantot šos pakalpojumus, piemēram, marķiera konta dati, kas sūtīti kā Basic, atgriež 403 ar kodu unsupported_transcription_principal vai unsupported_translation_principal. Atkārtoti neveiksmīgi autentifikācijas mēģinājumi no vienas adreses serverī api.multitel.net var izraisīt šīs adreses bloķēšanu, tāpēc pirms atkārtota mēģinājuma izlabojiet autentifikācijas datus.

Periodiski pārbaudiet darba pabeigšanu

Sūtiet pieprasījumu GET /v3/SERVICE/JOB_ID. Iesakām pārbaudīt ne biežāk kā reizi 3 sekundēs. Ārējais apvalks apraksta pieprasījumu; pārbaudiet tajā ietvertā darba lauku status, lai noteiktu, vai apstrāde ir pabeigta.

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"

Serverī api.multitel.net iestatiet HOST uz https://api.multitel.net un nolasiet .response.id nevis .data.id.

Droši atkārtojiet pieprasījumus ar neskaidru iznākumu

Ja iesniegšanas laikā iestājas noildze vai tiek atgriezts 429 vai 5xx statuss, atkārtoti sūtiet to pašu ievadi ar to pašu idempotences atslēgu. Jebkura servera atbilde var pazust vai tikt aizstāta ar kļūdu pēc darba pieņemšanas; atkārtota sūtīšana ar to pašu atslēgu atgriež darbu, ja tas pastāv. Atslēgas atkārtota izmantošana ar citu ievadi atgriež 409 ar kodu idempotency_conflict. Dažas kļūdas atkārtojas katrā mēģinājumā, piemēram, 503, ja maksas pakalpojums ir atspējots, vai 500 audiofailam, kuru nevar nolasīt, tāpēc pēc dažiem mēģinājumiem pārtrauciet.

Atslēgas maiņai katrā pakalpojumā ir atšķirīgas sekas.

• Runas pārveidošanai tekstā jauna atslēga izveido jaunu darbu ar atsevišķu maksu, ja apstrāde tiek veiksmīgi pabeigta. Sākotnējā atslēga turpina atgriezt sākotnējo darbu arī pēc apstrādes atjaunināšanas.
• Tulkošanai jauna atslēga ar identisku saturu atgriež atbilstošu darbu, kas ir rindā, tiek apstrādāts, ir pabeigts vai gaida apmaksu, bez jaunas maksas. Jauns darbs tiek izveidots, ja iepriekšējais darbs neizdevās vai apstrādes versija ir mainījusies. Tulkošanas atkārtojums ar sākotnējo atslēgu pēc apstrādes versijas maiņas atgriež 409, tāpēc saglabājiet sākotnējā darba ID un nolasiet darbu tieši.

Saņemiet rezultātu pēc līdzekļu pievienošanas

Ja darba statuss ir awaiting_payment, papildiniet atlikumu tā, lai tas būtu vismaz darba costUsd vērtība, kas noapaļota uz augšu līdz nākamajam $0.00001 daudzkārtnim, un tad sūtiet POST /v3/SERVICE/JOB_ID/settle. Debetēšana notiek pilnos $0.00001 soļos un ietver atlikuma daļu no iepriekšējiem tā paša pakalpojuma darbiem, tāpēc debetētā summa var pārsniegt costUsd vērtību par mazāk nekā $0.00001. Serverī api.multi.tel sūtiet JSON {} vai tukšu pamattekstu; jebkurš rekvizīts pamattekstā tiek noraidīts ar 400. Serveris api.multitel.net pamattekstu ignorē. Apmaksa atbrīvo saglabāto rezultātu, atkārtoti neveicot transkripciju vai tulkošanu. Atbilde ietver darbu; pārbaudiet, vai tā statuss ir completed. Ja atlikums joprojām nav pietiekams, darba statuss paliek awaiting_payment un atbilde joprojām ir HTTP 200.

Runas pārveidošanai tekstā jau pabeigta darba apmaksas pieprasījums atgriež to ar duplicate: true, bet rindā esoša, apstrādē esoša vai neveiksmīga darba apmaksa atgriež 409 ar kodu transcription_not_awaiting_payment. Tulkošanai darba apmaksa jebkurā citā statusā atgriež darbu nemainītu. Apmaksa ir pieejama tikai tad, ja maksas apstrāde ir iespējota (citādi 503). Darbi, kas gaida apmaksu, tiek ieskaitīti rezervētajās izmaksās, tāpēc priekšapmaksas kontiem tie var bloķēt jaunu maksas darbu iesniegšanu ar 402, līdz tie ir apmaksāti.

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"

Pārbaudiet lietojumu

Izmantojiet GET /v3/SERVICE/usage. Neobligātie parametri from un to ir UTC datumi formātā YYYY-MM-DD, un abi robeždatumi ir iekļauti. Ja tie nav norādīti, from noklusējuma vērtība ir datums 30 dienas pirms šodienas un to noklusējuma vērtība ir šodiena (UTC). to nedrīkst būt agrāks par from, un datumi drīkst būt ne vairāk kā 366 dienu attālumā (līdz 367 datumiem). Nederīgi kalendāra datumi, apgriezts vai garāks intervāls atgriež 400, tāpat kā citi vaicājuma parametri serverī 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"

Atbilde ietver mode, currency (USD), from, to un days — sarakstu, kas sakārtots no jaunākā uz vecāko.

• Runas pārveidošanas tekstā ieraksti ir grupēti pēc datuma un avota. Tie ietver date, source (api vai hpbx Hosted PBX ierakstiem), files, audioSeconds, billedSeconds, accruedUsd un debitedUsd.
• Tulkošanas ieraksti ir grupēti pēc datuma, avota un tulkošanas dzinēja. Tie ietver date, source, engine, jobs, sourceCharacters, accruedUsd un debitedUsd.

accruedUsd ir precīzās izmaksas ar deviņām zīmēm aiz komata, bet debitedUsd ir debetētā summa ar piecām zīmēm aiz komata. Lietojums tiek reģistrēts tajā UTC datumā, kad ir veikta katra darba apmaksa, tāpēc rindā esoši, apstrādē esoši, neveiksmīgi un apmaksu gaidoši darbi netiek parādīti.

Ierobežojumi

Katram kontam var būt kopā ne vairāk kā 50 nepabeigtu runas pārveidošanas tekstā un tulkošanas darbu: rindā, apstrādē vai apmaksas gaidās, tostarp Hosted PBX ierakstu apstrāde. Sasniedzot šo ierobežojumu vai pakalpojuma kopējo jaudu, iesniegšana atgriež 429 ar kodu transcription_queue_full vai translation_queue_full. Serveris api.multi.tel arī ierobežo katru klienta IP adresi līdz 300 pieprasījumiem minūtē visiem pieprasījumiem uz šo serveri kopā. Šī ierobežojuma pārsniegšana atgriež 429 ar pieprasījumu biežuma ierobežojuma galvenēm un vienkārša teksta pamattekstu JSON kļūdas apvalka vietā.

Apstrādājiet pieprasījumu kļūdas

Galvenajā serverī kļūmes atgriež HTTP kļūdas statusu un JSON ar status: "error", code, message un requestId. Katrā atbildē ir arī X-Request-ID galvene. Varat norādīt savu vērtību; vērtības, kas garākas par 128 rakstzīmēm, tiek saīsinātas. Saderības serveris atgriež tikai kļūdas kodu laukā response.code. Reģistrējiet pieprasījuma ID, ja tas ir pieejams, un kļūdas kodu, bet neiekļaujiet žurnālos audio, tekstu vai autentifikācijas datus.

Biežākie statusi:

Vadieties pēc atgrieztā kļūdas koda, nevis pieņēmuma, ka visām validācijas kļūdām ir viens statuss.

Saņemot 429 vai 503, uzgaidiet un mēģiniet vēlreiz, palielinot gaidīšanas intervālu un izmantojot to pašu iesniegšanas atslēgu; ievērojiet Retry-After galveni, ja tā ir norādīta. Nederīgas ievades vai autentifikācijas datu gadījumā vispirms novērsiet cēloni. Nesūtiet atkārtoti jaunas atslēgas, kamēr iepriekšējie darbi vēl ir rindā.