Úlohy převodu řeči na text a překladu

Nahraďte SERVICE níže hodnotou speech_to_text nebo translate, dále JOB_ID vráceným UUID. Všechny operace vyžadují přihlašovací údaje vašeho účtu, jak je popsáno v části Ověřování, a jsou omezeny na účet, kterému patří. Úlohu lze číst z kteréhokoli hostitele API, ale každý hostitel používá vlastní obálku odpovědi, proto důsledně používejte jednoho hostitele.

Pokud používáte hostitele api.multitel.net, chyby ověření (401) se vracejí dříve, než se tato obálka použije, a mohou mít jiné tělo, proto před parsováním zkontrolujte stavový kód HTTP.

Ověřování

Každý požadavek musí obsahovat přihlašovací údaje vašeho účtu. Úlohy, klíče idempotence, limity, využití a poplatky patří účtu, kterému přihlašovací údaje náležejí. Sdílejí je všechny přihlašovací údaje daného účtu na obou hostitelích bez ohledu na to, které přihlašovací údaje požadavek odesílají.

• HTTP Basic (Authorization: Basic, nebo curl --user). Přijímanými přihlašovacími údaji jsou účet API typu heslo, podúčet nebo přihlašovací údaje k vašemu účtu. Doporučujeme vyhrazený účet API. Uživatelské jméno nesmí obsahovat dvojtečku a uživatelské jméno ani heslo nesmí být prázdné.
• Token Bearer (Authorization: Bearer YOUR_TOKEN). Přijímá se pro účet API typu token. Tokenové účty API musí mít omezení IP adres a požadavky musí přicházet z povolené adresy. Oba hostitelé API přijímají adresy IPv4 a rozsahy CIDR nakonfigurované pro účet. Token nelze odeslat jako heslo Basic. Ověřte, že váš token funguje na hostiteli, který používáte.

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

Pokud je účet API omezen podle IP adresy, odesílejte požadavky z povolené adresy. Chybějící nebo neplatné přihlašovací údaje vracejí 401. Pokud používáte hostitele api.multitel.net, platné přihlašovací údaje, které nemohou tyto služby používat, například údaje tokenového účtu odeslané jako Basic, vracejí 403 unsupported_transcription_principal nebo unsupported_translation_principal. Opakované neúspěšné ověření z jedné adresy na hostiteli api.multitel.net může způsobit zablokování této adresy, proto před dalšími pokusy opravte přihlašovací údaje.

Dotazování na dokončení

Odešlete požadavek GET /v3/SERVICE/JOB_ID. Doporučujeme dotazovat se nejvýše jednou za 3 sekundy. Vnější obálka popisuje požadavek; zda zpracování skončilo, zjistíte z pole status vnitřní úlohy.

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"

Pokud používáte hostitele api.multitel.net, nastavte HOST na https://api.multitel.net a čtěte .response.id místo .data.id.

Bezpečné opakování nejistých požadavků

Pokud u odeslání vyprší časový limit nebo vrátí 429 či stav 5xx, odešlete znovu stejný vstup se stejným klíčem idempotence. Odpověď z kteréhokoli hostitele se může ztratit nebo být nahrazena chybou až poté, co byla práce přijata; opětovné odeslání se stejným klíčem vrátí úlohu, pokud existuje. Klíč znovu použitý s jiným vstupem vrátí 409 idempotency_conflict. Některé chyby se opakují při každém pokusu, například 503, když je placená služba vypnutá, nebo 500 u zvukového souboru, který nelze přečíst, proto po několika pokusech přestaňte.

Změna klíče má u každé služby jiné důsledky.

• U převodu řeči na text vytvoří nový klíč novou úlohu se samostatným poplatkem, pokud zpracování úspěšně skončí. Původní klíč dál vrací původní úlohu, a to i po aktualizaci zpracování.
• U překladu vrátí nový klíč se shodným obsahem bez nového poplatku odpovídající úlohu, která je ve frontě, zpracovává se, je dokončená nebo čeká na platbu. Novou práci vytvoří, pokud předchozí úloha selhala nebo se změnila verze zpracování. Opakování překladu s původním klíčem vrátí po změně verze zpracování 409, proto si uchovejte ID původní úlohy a čtěte úlohu přímo.

Uvolnění výsledku po doplnění prostředků

Pokud je úloha ve stavu awaiting_payment, doplňte prostředky tak, aby váš zůstatek dosahoval alespoň hodnoty costUsd úlohy zaokrouhlené nahoru na nejbližší násobek $0.00001, a poté odešlete POST /v3/SERVICE/JOB_ID/settle. Odečty probíhají v celých krocích po $0.00001 a zahrnují případný zbytek převedený z dřívějších úloh téže služby, takže odečtená částka může překročit costUsd o méně než $0.00001. Pokud používáte hostitele api.multi.tel, odešlete JSON {} nebo prázdné tělo; jakákoli vlastnost v těle je odmítnuta s kódem 400. api.multitel.net tělo ignoruje. Úhrada uvolní uložený výsledek bez opětovného spuštění přepisu nebo překladu. Odpověď obsahuje úlohu; zkontrolujte, že její stav je completed. Pokud zůstatek stále nestačí, úloha zůstane ve stavu awaiting_payment a odpověď má i tak stav HTTP 200.

U převodu řeči na text vrátí úhrada již dokončené úlohy tuto úlohu s hodnotou duplicate: true, zatímco úhrada úlohy ve frontě, zpracovávané nebo neúspěšné vrátí 409 transcription_not_awaiting_payment. U překladu vrátí úhrada úlohy v jakémkoli jiném stavu úlohu beze změny. Úhrada je k dispozici jen tehdy, když je placené zpracování zapnuté (jinak 503). Úlohy čekající na platbu se počítají jako rezervované náklady, takže u předplacených účtů mohou až do své úhrady blokovat nová placená odeslání kódem 402.

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"

Kontrola využití

Použijte GET /v3/SERVICE/usage. Volitelné parametry from a to jsou data UTC ve formátu YYYY-MM-DD (obě hraniční data jsou zahrnuta). Pokud je vynecháte, from je ve výchozím nastavení 30 dní před dneškem a to je ve výchozím nastavení dnešní datum (UTC). to nesmí být dřívější než from, přičemž data mohou být od sebe vzdálena nejvýše 366 dní (až 367 dat). Neplatná kalendářní data nebo obrácený či delší rozsah vracejí 400, stejně jako jiné parametry dotazu na hostiteli 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"

Odpověď obsahuje mode, currency (USD), from, to a days, tedy seznam seřazený od nejnovějších položek.

• Položky převodu řeči na text jsou seskupeny podle data a zdroje. Obsahují date, source (api, nebo hpbx pro nahrávky Hosted PBX), files, audioSeconds, billedSeconds, accruedUsd a debitedUsd.
• Položky překladu jsou seskupeny podle data, zdroje a překladového modulu. Obsahují date, source, engine, jobs, sourceCharacters, accruedUsd a debitedUsd.

accruedUsd je přesná cena s devíti desetinnými místy a debitedUsd je odečtená částka s pěti. Využití se zaznamenává k datu UTC, kdy byl uhrazen poplatek za danou úlohu, takže úlohy ve frontě, zpracovávané, neúspěšné a čekající na platbu se v něm nezobrazují.

Limity

Každý účet může mít dohromady nejvýše 50 nevyřízených úloh převodu řeči na text a překladu: ve frontě, zpracovávaných nebo čekajících na platbu, včetně zpracování nahrávek Hosted PBX. Po dosažení tohoto limitu nebo celkové kapacity služby vracejí odeslání 429 transcription_queue_full nebo translation_queue_full. api.multi.tel navíc omezuje každou IP adresu klienta na 300 požadavků za minutu napříč všemi požadavky na tohoto hostitele. Tento limit vrací 429 s hlavičkami omezení rychlosti a tělem ve formátu prostého textu místo chybové obálky JSON.

Zpracování chyb požadavků

Na primárním hostiteli vracejí chyby chybový stav HTTP a JSON s poli status: "error", code, message a requestId. Každá odpověď navíc obsahuje hlavičku X-Request-ID s ID požadavku. Můžete zadat vlastní hodnotu; hodnoty delší než 128 znaků jsou zkráceny. Hostitel kompatibility vrací pouze kód chyby v poli response.code. Zaznamenávejte ID požadavku (je-li k dispozici) a kód chyby a do protokolů nezapisujte zvuk, text ani přihlašovací údaje.

Běžné stavy:

Řiďte se vráceným kódem chyby a nepředpokládejte, že každé selhání validace má jediný stav.

U 429 nebo 503 počkejte a opakujte pokus s postupně prodlužovanou prodlevou a stejným klíčem odeslání; respektujte hlavičku Retry-After (pokud je k dispozici). Při neplatném vstupu nebo přihlašovacích údajích nejprve odstraňte příčinu. Neodesílejte opakovaně nové klíče, dokud jsou dřívější úlohy stále ve frontě.