Beszéd- és fordítási feladatok

Az alábbiakban cserélje le a(z) SERVICE értéket erre: speech_to_text vagy translate, a(z) JOB_ID értéket pedig a visszakapott UUID-ra. Minden művelethez a fiókjához tartozó hitelesítő adatok szükségesek (lásd: Hitelesítés), és a műveletek a tulajdonos fiókra korlátozódnak. Egy feladat bármelyik API-hosztról lekérdezhető, de mindegyik hoszt saját borítékformátumot használ, ezért következetesen ugyanazt a hosztot használja.

Ha ezt a hosztot használja: api.multitel.net, a hitelesítési hibák (401) még a boríték alkalmazása előtt érkeznek vissza, és eltérő törzsük lehet, ezért az elemzés előtt ellenőrizze a HTTP-állapotkódot.

Hitelesítés

Minden kérésnek tartalmaznia kell a fiókjához tartozó hitelesítő adatokat. A feladatok, az idempotenciakulcsok, a korlátok, a használat és a díjak ahhoz a fiókhoz tartoznak, amelyhez a hitelesítő adatok tartoznak. Ezeken a fiók összes hitelesítő adata osztozik mindkét hoszton, függetlenül attól, hogy melyik hitelesítő adat küldi a kérést.

• HTTP Basic-hitelesítés (Authorization: Basic, vagy curl --user). Elfogadott hitelesítő adatok: jelszó típusú API-fiók, alfiók vagy a fiókja bejelentkezési adatai. Dedikált API-fiók használatát javasoljuk. A felhasználónév nem tartalmazhat kettőspontot, és sem a felhasználónév, sem a jelszó nem lehet üres.
• Bearer-token (Authorization: Bearer YOUR_TOKEN). Token típusú API-fiókok esetén használható. A token típusú API-fiókokhoz IP-korlátozást kell beállítani, és a kéréseknek engedélyezett címről kell érkezniük. Mindkét API-hoszt elfogadja a fiókhoz beállított IPv4-címeket és CIDR-tartományokat. Token nem küldhető Basic jelszóként. Ellenőrizze, hogy a tokenje működik-e az Ön által használt hoszton.

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

Ha egy API-fiók IP-cím alapján korlátozott, engedélyezett címről küldje a kéréseket. Hiányzó vagy érvénytelen hitelesítő adatok esetén a válasz 401. Ha ezt a hosztot használja: api.multitel.net, az érvényes, de e szolgáltatások használatára nem jogosult hitelesítő adatok – például egy token típusú fiók Basic módon küldött hitelesítő adatai – esetén a válasz 403 unsupported_transcription_principal vagy unsupported_translation_principal. Ha az api.multitel.net hoszton egy címről ismételten sikertelen a hitelesítés, az adott cím letiltásra kerülhet, ezért az újrapróbálkozás előtt javítsa ki a hitelesítő adatokat.

Lekérdezés a befejezésig

Küldjön kérést: GET /v3/SERVICE/JOB_ID. Javasoljuk, hogy legfeljebb 3 másodpercenként egyszer kérdezzen le. A külső boríték a kérést írja le; vizsgálja meg a belső feladat status mezőjét, hogy megállapítsa, befejeződött-e a feldolgozá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"

Ha ezt a hosztot használja: api.multitel.net, állítsa a HOST változót a(z) https://api.multitel.net értékre, és olvassa ki a(z) .response.id mezőt a következő helyett: .data.id.

Bizonytalan kimenetelű kérések biztonságos újrapróbálása

Ha egy beküldés túllépi az időkorlátot, vagy 429-es vagy 5xx állapotkódot ad vissza, küldje el újra ugyanazt a bemenetet ugyanazzal az idempotenciakulccsal. Bármelyik hoszt válasza elveszhet vagy hibára cserélődhet azután, hogy a munkát már elfogadtuk; ugyanazzal a kulccsal újraküldve visszakapja a feladatot, ha az létezik. Ha egy kulcsot eltérő bemenettel használ újra, a válasz 409 idempotency_conflict. Egyes hibák minden kísérletnél megismétlődnek, például az 503, amíg egy fizetős szolgáltatás le van tiltva, vagy az 500 egy nem olvasható hangfájl esetén, ezért néhány kísérlet után hagyja abba.

A kulcs módosításának hatása szolgáltatásonként eltér.

• Beszéd szöveggé alakításánál az új kulcs új feladatot hoz létre, amelyért külön díjat számítunk fel, ha a feldolgozás sikeresen befejeződik. Az eredeti kulcs továbbra is az eredeti feladatot adja vissza, a feldolgozás frissítése után is.
• Fordításnál az azonos tartalmú új kulcs új díj nélkül visszaadja az egyező várakozó, futó, befejezett vagy fizetésre váró feladatot. Új munkát hoz létre, ha a korábbi feladat sikertelen volt, vagy ha a feldolgozási verzió megváltozott. A feldolgozási verzió változása után az eredeti kulccsal végzett fordítási újrapróbálkozás 409-et ad vissza, ezért őrizze meg az eredeti feladatazonosítót, és a feladatot közvetlenül kérdezze le.

Eredmény feloldása egyenlegfeltöltés után

Ha egy feladat állapota awaiting_payment, töltse fel az egyenlegét úgy, hogy az legalább elérje a feladat costUsd értékét a következő $0.00001-re felfelé kerekítve, majd küldje el ezt a kérést: POST /v3/SERVICE/JOB_ID/settle. A terhelés egész, $0.00001-es lépésekben történik, és magában foglalja az ugyanazon szolgáltatás korábbi feladataiból áthozott maradékot is, így a terhelt összeg meghaladhatja a(z) costUsd értéket, legfeljebb $0.00001-nél kisebb különbséggel. Ha ezt a hosztot használja: api.multi.tel, küldjön JSON-ként {} értéket vagy üres törzset; a törzsben szereplő bármely tulajdonságot 400-as hibával elutasítjuk. Az api.multitel.net figyelmen kívül hagyja a törzset. A rendezés a mentett eredményt az átírás vagy a fordítás újbóli futtatása nélkül adja ki. A válasz tartalmazza a feladatot; ellenőrizze, hogy az állapota a következő-e: completed. Ha az egyenleg továbbra sem elegendő, a feladat állapota awaiting_payment marad, és a válasz ekkor is HTTP 200.

Beszéd szöveggé alakításánál egy már befejezett feladat rendezése a feladatot ezzel az értékkel adja vissza: duplicate: true, a várakozó, futó vagy sikertelen feladat rendezésére pedig a válasz 409 transcription_not_awaiting_payment. Fordításnál bármely más állapotú feladat rendezése változatlanul adja vissza a feladatot. A rendezés csak akkor érhető el, ha a fizetős feldolgozás engedélyezve van (ellenkező esetben 503). A fizetésre váró feladatok lefoglalt költségnek számítanak, így előre fizetett fiókok esetén a rendezésükig 402-es hibával blokkolhatják az új fizetős beküldéseket.

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"

Használat ellenőrzése

Használja ezt: GET /v3/SERVICE/usage. Az opcionális from és to paraméterek UTC-dátumok, YYYY-MM-DD formátumban, és mindkét határnap beleszámít. Ha elhagyja őket, a(z) from alapértéke a mai napnál 30 nappal korábbi dátum, a(z) to alapértéke pedig a mai nap (UTC). A(z) to nem lehet korábbi, mint a(z) from, és a két dátum között legfeljebb 366 nap lehet (legfeljebb 367 dátum). Érvénytelen naptári dátumok, illetve fordított vagy hosszabb tartomány esetén a válasz 400, és ugyanez történik más lekérdezési paraméterek esetén is a következő hoszton: 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"

A válasz a következőket tartalmazza: mode, currency (USD), from, to és days, amely a legújabb elemmel kezdődő lista.

• A beszéd szöveggé alakítási bejegyzések dátum és forrás szerint vannak csoportosítva. A következőket tartalmazzák: date, source (api, vagy hpbx a Hosted PBX-felvételeknél), files, audioSeconds, billedSeconds, accruedUsd és debitedUsd.
• A fordítási bejegyzések dátum, forrás és motor szerint vannak csoportosítva. A következőket tartalmazzák: date, source, engine, jobs, sourceCharacters, accruedUsd és debitedUsd.

accruedUsd a pontos költség kilenc tizedesjeggyel, a(z) debitedUsd pedig a terhelt összeg öt tizedesjeggyel. A használatot azon az UTC-dátumon rögzítjük, amikor az adott feladat díjának rendezése megtörtént, ezért a várakozó, futó, sikertelen és fizetésre váró feladatok nem jelennek meg.

Korlátok

Fiókonként összesen legfeljebb 50 függőben lévő beszéd szöveggé alakítási és fordítási feladat lehet: várakozó, futó vagy fizetésre váró, beleértve a Hosted PBX-felvételek feldolgozását is. Ha ezt a korlátot vagy a szolgáltatás teljes kapacitását elérik, a beküldésekre a válasz 429 transcription_queue_full vagy translation_queue_full. Az api.multi.tel ezenfelül ügyfél-IP-címenként percenként 300 kérésre korlátozza az adott hosztra irányuló összes kérést. Ennek a korlátnak az elérésekor a válasz 429, sebességkorlát-fejlécekkel és egyszerű szöveges törzzsel a JSON-hibaboríték helyett.

Kéréshibák kezelése

Az elsődleges hoszton a hibák HTTP-hibaállapotkódot és olyan JSON-t adnak vissza, amely a következőket tartalmazza: status: "error", code, message és requestId. Minden válasz tartalmaz egy X-Request-ID fejlécet is. Saját értéket is megadhat; a 128 karakternél hosszabb értékeket csonkoljuk. A kompatibilitási hoszt csak a hibakódot adja vissza, a következő mezőben: response.code. Naplózza a kérésazonosítót (ha elérhető) és a hibakódot, a hanganyagot, a szöveget és a hitelesítő adatokat azonban ne vegye fel a naplókba.

Gyakori állapotkódok:

A visszaadott hibakód alapján járjon el, ahelyett hogy feltételezné, hogy minden validálási hibához egyetlen állapotkód tartozik.

429 vagy 503 esetén várjon, majd próbálkozzon újra fokozatosan növekvő várakozással (backoff) és ugyanazzal a beküldési kulccsal; ha jelen van, vegye figyelembe a(z) Retry-After fejlécet. Érvénytelen bemenet vagy hitelesítő adatok esetén először hárítsa el az okot. Ne küldjön be ismételten új kulcsokat, amíg a korábbi feladatok még várakoznak.