Asenda allpool SERVICE väärtusega speech_to_text või translate ning JOB_ID tagastatud UUID-ga. Kõik toimingud nõuavad sinu konto autentimisandmeid, nagu kirjeldatud jaotises Autentimine, ning on piiratud tööd omava kontoga. Tööd saab lugeda kummast tahes API-serverist, kuid kumbki kasutab oma vastuseümbrist, seega kasuta järjepidevalt sama serverit.
| Server | Edukas vastus | Viga |
|---|---|---|
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"}} |
Serveris api.multitel.net tagastatakse autentimisvead (401) enne selle ümbrise rakendamist ja nende sisu võib olla teistsugune, seega kontrolli enne vastuse parsimist HTTP-olekukoodi.
Autentimine
Iga päring peab sisaldama sinu konto autentimisandmeid. Tööd, idempotentsusvõtmed, piirangud, kasutus ja tasud kuuluvad kontole, millele autentimisandmed kuuluvad. Need on ühised konto kõigile autentimisandmetele mõlemas serveris olenemata sellest, milliste andmetega päring saadetakse.
- HTTP Basic (
Authorization: Basicvõicurl --user). Aktsepteeritakse paroolitüüpi API-konto, alamkonto või sinu konto sisselogimisandmeid. Soovitame eraldi API-kontot. Kasutajanimi ei tohi sisaldada koolonit ning kasutajanimi ega parool ei tohi olla tühi. - Bearer-token (
Authorization: Bearer YOUR_TOKEN). Aktsepteeritakse tokenitüüpi API-konto puhul. Tokeniga API-kontodel peab olema IP-piirang ning päringud peavad tulema lubatud aadressilt. Mõlemad API-serverid aktsepteerivad kontole seadistatud IPv4-aadresse ja CIDR-vahemikke. Tokenit ei saa saata Basic-paroolina. Veendu, et token töötab kasutatavas serveris.
API_TOKEN="your-api-token"
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $API_TOKEN" \
https://api.multi.tel/v3/speech_to_textKui API-kontol on IP-aadressi piirang, saada päringud lubatud aadressilt. Puuduvad või vigased autentimisandmed tagastavad koodi 401. Serveris api.multitel.net tagastavad kehtivad autentimisandmed, millega ei saa neid teenuseid kasutada, näiteks Basic-kujul saadetud tokenikonto andmed, koodi 403 koos veakoodiga unsupported_transcription_principal või unsupported_translation_principal. Korduvad ebaõnnestunud autentimiskatsed samalt aadressilt serveris api.multitel.net võivad põhjustada selle aadressi blokeerimise, seega paranda autentimisandmed enne uuesti proovimist.
Küsi töö valmimise olekut
Saada päring GET /v3/SERVICE/JOB_ID. Soovitame küsida olekut mitte sagedamini kui kord 3 sekundi jooksul. Välimine ümbris kirjeldab päringut; kontrolli sees oleva töö välja status, et teha kindlaks, kas töötlemine on lõppenud.
| Olek | Tähendus |
|---|---|
queued | Vastu võetud ja ootel. Ühe konto töid töödeldakse ükshaaval, vaheldumisi teiste kontode töödega. |
running | Töötlemisel. Välja progress väärtus võib olla null; null-väärtus üksi ei tähenda, et töö oleks takerdunud. |
completed | Tulemus on saadaval. Salvesta see ja võrdle olulisi üksikasju algmaterjaliga. |
failed | Kontrolli välja failureCode. Ebaõnnestunud töö eest tasu ei võeta. Kõrvalda põhjus ja saada töö uue võtmega; sama võtme uuesti saatmine tagastab sama ebaõnnestunud töö. |
awaiting_payment | Töötlemine lõppes, kuid ettemaksujäägist ei piisanud tasu katmiseks. Tulemus on salvestatud ja seda ei väljastata enne töö eest tasumist. |
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"Serveris api.multitel.net määra HOST väärtuseks https://api.multitel.net ja loe .response.id välja .data.id asemel.
Proovi ebaselge tulemusega päringuid turvaliselt uuesti
Kui töö saatmine aegub või tagastab koodi 429 või olekukoodi 5xx, saada sama sisend uuesti sama idempotentsusvõtmega. Kummagi serveri vastus võib pärast töö vastuvõtmist kaduma minna või asenduda veaga; sama võtmega uuesti saatmine tagastab töö, kui see on olemas. Võtme taaskasutamine erineva sisendiga tagastab koodi 409 ja veakoodi idempotency_conflict. Mõned vead korduvad igal katsel, näiteks 503, kui tasuline teenus on välja lülitatud, või 500 helifaili puhul, mida ei saa lugeda. Lõpeta seetõttu pärast mõnda katset.
Võtme muutmise mõju on teenuseti erinev.
- Kõne tekstiks teisendamisel loob uus võti uue töö, mille eest võetakse töötlemise õnnestumisel eraldi tasu. Algne võti tagastab jätkuvalt algse töö ka pärast töötlemise uuendamist.
- Tõlkimisel tagastab uus võti identse sisuga vastava töö, mis on järjekorras, töötlemisel, lõpetatud või makse ootel, uut tasu võtmata. Uus töö luuakse, kui varasem töö ebaõnnestus või töötlemisversioon on muutunud. Tõlke korduskatse algse võtmega tagastab pärast töötlemisversiooni muutmist koodi 409, seega säilita algne töö ID ja loe tööd otse.
Vabasta tulemus pärast raha lisamist
Kui töö olek on awaiting_payment, lisa raha nii, et saldo oleks vähemalt töö costUsd väärtus, ümardatuna üles lähima $0.00001 täiskordseni. Seejärel saada POST /v3/SERVICE/JOB_ID/settle. Debiteerimine toimub $0.00001 täissammudena ja sisaldab sama teenuse varasematest töödest üle kantud jääki, seega võib debiteeritud summa ületada costUsd väärtust vähem kui $0.00001 võrra. Serveris api.multi.tel saada JSON {} või tühi päringukeha; iga kehas olev omadus lükatakse tagasi koodiga 400. Server api.multitel.net eirab keha. Tasumine vabastab salvestatud tulemuse ilma transkribeerimist või tõlkimist uuesti käivitamata. Vastus sisaldab tööd; kontrolli, et selle olek oleks completed. Kui saldost endiselt ei piisa, jääb töö olekuks awaiting_payment ning vastuse HTTP-olekukood on endiselt 200.
Kõne tekstiks teisendamisel tagastab juba lõpetatud töö eest tasumise päring selle märkega duplicate: true, kuid järjekorras oleva, töötlemisel või ebaõnnestunud töö eest tasumine tagastab koodi 409 ja veakoodi transcription_not_awaiting_payment. Tõlkimisel tagastab mis tahes muus olekus töö eest tasumise päring töö muutmata kujul. Tasumine on võimalik ainult siis, kui tasuline töötlemine on lubatud (muidu 503). Makset ootavad tööd arvestatakse broneeritud kuluna, seega võivad need ettemaksukontodel blokeerida uute tasuliste tööde saatmise koodiga 402, kuni nende eest tasutakse.
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"Kontrolli kasutust
Kasuta päringut GET /v3/SERVICE/usage. Valikulised parameetrid from ja to on UTC-kuupäevad vormingus YYYY-MM-DD ning mõlemad piirkuupäevad kaasatakse. Kui need jäetakse ära, on from vaikeväärtus 30 päeva enne tänast ja to vaikeväärtus tänane kuupäev (UTC). to ei tohi olla varasem kui from ning kuupäevade vahe võib olla kuni 366 päeva (kuni 367 kuupäeva). Vigased kalendrikuupäevad, vastupidine või pikem vahemik tagastavad koodi 400, nagu ka muud päringuparameetrid serveris 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"Vastus sisaldab välju mode, currency (USD), from, to ja days, mis on uusimast vanimani järjestatud loend.
- Kõne tekstiks teisendamise kirjed rühmitatakse kuupäeva ja allika järgi. Need sisaldavad välju
date,source(apivõihpbxHosted PBX-i salvestiste puhul),files,audioSeconds,billedSeconds,accruedUsdjadebitedUsd. - Tõlkekirjed rühmitatakse kuupäeva, allika ja tõlkemootori järgi. Need sisaldavad välju
date,source,engine,jobs,sourceCharacters,accruedUsdjadebitedUsd.
accruedUsd on täpne kulu üheksa komakohaga ning debitedUsd on debiteeritud summa viie komakohaga. Kasutus registreeritakse UTC-kuupäeval, mil iga töö tasu arveldati, seega ei kuvata järjekorras olevaid, töötlemisel, ebaõnnestunud ega makset ootavaid töid.
Piirangud
Igal kontol võib olla kokku kuni 50 lõpetamata kõne tekstiks teisendamise ja tõlketööd: järjekorras, töötlemisel või makse ootel, sealhulgas Hosted PBX-i salvestiste töötlemine. Selle piiri täitumisel või teenuse koguvõimsuse ammendumisel tagastab töö saatmine koodi 429 ja veakoodi transcription_queue_full või translation_queue_full. Server api.multi.tel piirab ka iga kliendi IP-aadressi päringute arvu 300 päringuni minutis kõigi sellele serverile tehtud päringute peale kokku. Selle piiri ületamisel tagastatakse kood 429 koos päringusageduse piirangu päiste ja lihttekstikehaga JSON-veaümbrise asemel.
Käsitle päringuvigu
Põhiserveris tagastatakse vea korral HTTP-veaolekukood ja JSON, mis sisaldab välju status: "error", code, message ja requestId. Iga vastus sisaldab ka X-Request-ID päist. Võid anda oma väärtuse; üle 128 märgi pikad väärtused kärbitakse. Ühilduvusserver tagastab ainult veakoodi väljas response.code. Logi võimaluse korral päringu ID ja veakood, kuid ära lisa logidesse heli, teksti ega autentimisandmeid.
Levinud olekukoodid:
| Olekukood | Tähendus |
|---|---|
| 400 | Vigane sisend. |
| 401 | Puuduvad või vigased autentimisandmed. |
| 402 | Ebapiisav ettemaksujääk. |
| 403 | Ühilduvusserveris autentimisandmed, millega ei saa neid teenuseid kasutada. |
| 404 | Tundmatu töö või marsruut. |
| 405 | Toetamata meetod või tundmatu tee teenuse sees. |
| 409 | Vastuoluline sisend, tõlge samasse keelde või makset mitteootava kõnetöö eest tasumine. |
| 413 | Liiga suur keha või fail. |
| 422 | Toetamata heli või kättesaamatu standardne keelepaar. |
| 429 | Järjekorra, valideerimise või päringusageduse piirangud. |
| 500 | Ootamatu serveriviga, sealhulgas helifail, mida ei saa lugeda. |
| 503 | Välja lülitatud või ajutiselt kättesaamatu teenus või autentimisandmed, mida ei saa praegu kontrollida. |
Lähtu tagastatud veakoodist, mitte eeldusest, et iga valideerimisviga annab sama olekukoodi.
Koodide 429 või 503 korral oota ja proovi uuesti pikenevate ooteaegade ning sama saatmisvõtmega; järgi Retry-After päist, kui see on olemas. Vigase sisendi või autentimisandmete korral kõrvalda kõigepealt põhjus. Ära saada korduvalt uusi võtmeid, kui varasemad tööd on veel järjekorras.