API pro překlad textu

Toto API překládá text jako úlohy ve frontě, vždy do jednoho cílového jazyka na úlohu. Odešli text, ulož si vrácené ID úlohy a načítej úlohu, dokud zpracování neskončí. Každý požadavek posílej přes HTTPS s přihlašovacími údaji svého účtu: buď pomocí HTTP Basic jako v příkladech, nebo pomocí tokenu API, jak popisuje část Ověřování. Přihlašovací údaje uchovávej na svém serveru.

Koncové body

Dva servery API, https://api.multi.tel a server pro kompatibilitu https://api.multitel.net, sdílejí stejné úlohy, klíče idempotence, limity a účtování v rámci účtu. Liší se vnější strukturou odpovědi, proto důsledně používej jeden server s odpovídajícím parserem.

Na api.multi.tel je každá cesta dostupná také s prefixem /v1/translate místo /v3/translate. Na api.multitel.net používej cesty /v3/translate.

Odpověď s informacemi o službě uvádí enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages a ratesNanosPerCharacter. cpuLanguages vypisuje základní jazykové kódy přijímané pro standardní překlad. ratesNanosPerCharacter uvádí pro každý modul nakonfigurovanou cenu za kódový bod zdrojového textu v miliardtinách amerického dolaru: hodnota 5000 znamená $5 za milion kódových bodů. Odpověď neuvádí, zda je právě dostupný rozšířený překlad; jeho odhad vrací 503, když dostupný není. Načtení je zdarma.

Překlad textu

Pošli JSON s hlavičkou Content-Type: application/json na POST https://api.multi.tel/v3/translate. Každá úloha má jeden cílový jazyk, proto pro každý cíl odešli samostatnou úlohu.

Kódy jazyka a národního prostředí jsou značky BCP 47 o délce 2 až 63 písmen, číslic a spojovníků. Převádějí se do kanonického tvaru, takže en-us se zaznamená jako en-US. Neplatné značky a und, mul nebo zxx vracejí 400 a kód invalid_translation_language. Dostupnost standardního překladu se ověřuje podle základního jazyka a nb a nn se počítají jako no. Regionální cíl, například fr-CA, se přijme a zaznamená, ale standardní výstup se řídí základním jazykem a není zaručeno, že bude odpovídat regionu.

Na tomto serveru udržuj tělo požadavku do 128 KiB. Posílej text jako UTF-8 místo zápisu každého znaku mimo ASCII pomocí sekvence \u, což může požadavek s 20,000 znaky dostat nad limit.

Tělo přijímá pouze tato čtyři pole. Jakákoli jiná vlastnost je odmítnuta s 400 a kódem invalid_translation_request, včetně idempotency_key, ID vlastníků, příznaků bezplatného zpracování a polí segmentů.

Idempotence a opětovné použití

Každé odeslání vyžaduje hlavičku Idempotency-Key o délce 1 až 190 znaků. Používej písmena ASCII, číslice, -, _, . a : bez mezer na začátku a konci; chybějící klíč nebo klíč o délce 191 či více znaků je odmítnut s 400. Klíče platí pro tvůj účet a překlad, napříč oběma servery a všemi přihlašovacími údaji účtu.

• Stejný klíč se stejným textem, kanonickými jazyky a modulem vrátí existující úlohu s HTTP 200 a duplicate: true bez dalšího poplatku.
• Stejný klíč s jiným textem, jazyky nebo modulem vrátí 409 a kód idempotency_conflict. Stejný klíč vrátí 409 také tehdy, když se verze zpracování od vytvoření jeho úlohy změnila. V takovém případě načti původní úlohu podle ID místo nového odeslání.
• Nový klíč se stejným textem, kanonickými jazyky a modulem vrátí existující úlohu s HTTP 200 a duplicate: true bez nového poplatku za zpracování, pokud úloha se stejným obsahem a aktuální verzí zpracování čeká ve frontě, zpracovává se, je dokončená nebo čeká na platbu. Znovu použitá úloha čekající na platbu stále vyžaduje vypořádání. Neúspěšné úlohy se znovu nepoužívají: vytvoří se nová úloha a po dokončení se zaúčtuje.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

Nová úloha vrátí HTTP 202. Ukázkový text má 57 kódových bodů, takže při ceně $5 za milion kódových bodů stojí $0.000285. Zkrácená odpověď (identifikátor je příklad):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

Odeslání může také vrátit 402 a kód insufficient_balance, když předplacený zůstatek nepokryje úlohu spolu s ostatními nevyřízenými úlohami, a 429 a kód translation_queue_full, když má účet nebo služba příliš mnoho nevyřízených úloh. V těchto případech vrací 503:

• paid_translation_not_enabled, když je placený překlad vypnutý.
• translation_unavailable pro rozšířený požadavek, když rozšířený překlad není dostupný.
• translation_pricing_unavailable, když vybraný modul nemá nastavenou sazbu.

Po odpovědích 429 a 503 to zkus později se stejným klíčem.

Volba kvality

Dlouhý text se zpracovává po menších částech a znovu spojuje. Konce řádků a mezery se mohou změnit a věta může na hranici zpracovaných částí ztratit kontext. Uchovej původní text a zkontroluj spojený výsledek. Standardní překlad používá základní jazyk regionální značky; přijetí a zaznamenání značky nezaručuje regionální formulace.

Standardní překlad běží v pracovních procesech na CPU. Rozšířený překlad odesílá text do nakonfigurované externí služby AI. I její výstup vyžaduje kontrolu; služba nezaručuje, že jeden modul bude přesnější pro každou jazykovou dvojici nebo typ textu.

Standardní překlad je návrh, jehož kvalita a doba zpracování se liší podle jazykové dvojice. Rozšířený překlad je určen pro text, u kterého záleží na kontextu, ale stále vyžaduje kontrolu důležitých jmen, čísel, záporů a závazků. Ani jedna možnost neopravuje chyby přítomné už v původním přepisu, proto si originál uchovej pro porovnání.

Použij GET /v3/translate na stejném serveru API pro kontrolu aktuální dostupnosti, podporovaných standardních jazyků a nastavených sazeb. Standardní požadavek, jehož základní zdrojový nebo cílový jazyk není v cpuLanguages, vrací 422 a kód translation_language_pair_unavailable. Pokud je uvedeno source_language a má stejný základní jazyk jako cíl, požadavek vrátí 409 a kód translation_same_language místo vytvoření úlohy. Rozšířený překlad se zapíná samostatně: dokud není dostupný, odesílání úloh rozšířeného překladu a jeho odhady vracejí 503.

Nejdříve získej odhad

Na api.multi.tel pošli stejné tělo JSON na POST /v3/translate/estimate. Klíč idempotence není potřeba. Odhad používá stejnou validaci včetně kontrol 422 a 409, ale nevytváří úlohu, nepřekládá text, nerezervuje prostředky, nekontroluje zůstatek ani neúčtuje poplatek. Vrací HTTP 200 s poli estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd a costUsd pod data. V příkladu výše má costUsd hodnotu 0.000285000 při standardní sazbě. Když rozšířený překlad není dostupný, jeho odhad vrací 503 a kód service_unavailable. Odhady používají aktuálně nastavenou sazbu. Sazba úlohy se zafixuje při jejím vytvoření a podle ní se účtuje.

Načtení překladu

Nové odeslání vrací HTTP 202 a existující nebo znovu použitá úloha vrací HTTP 200. Uchovej data.id a použij společný postup práce s úlohami. Objekt úlohy obsahuje tato pole:

• id, status, engine, sourceLocale a targetLocale.
• sourceCharacters, costUsd, costIsEstimate a pricePerMillionCharactersUsd.
• progress a createdAt.
• modelVersion, neprůhledný řetězec identifikující verzi zpracování.
• duplicate v odpovědích využívajících existující úlohu.
• failureCode pro neúspěšné úlohy: translation_failed, translation_timeout, input_failed nebo worker_lease_lost.

Neúspěšná úloha ukazuje costUsd s hodnotou nula.

Dokončená úloha obsahuje data.result. Tento objekt obsahuje sourceLocale (prázdné, pokud nebyl uveden zdrojový jazyk), targetLocale, pole text s přeloženým textem (texty segmentů spojené konci řádků) a segments. Pro text odeslaný přes toto API segments obsahuje jednu položku s polem text obsahujícím překlad a cílovým jazykem v poli language. Výsledky úloh čekajících na platbu se zadržují do vypořádání.

Použití api.multitel.net

Koncový bod pro kompatibilitu POST https://api.multitel.net/v3/translate přijímá stejná pole JSON a stejnou hlavičku Idempotency-Key. Pokud hlavička chybí, přijímá také řetězec idempotency_key v těle JSON. Jakékoli jiné dodatečné pole je odmítnuto s 400 a kódem unsupported_translation_option. Na tomto serveru může mít surové tělo až 256,000 bajtů a text nad 20,000 kódových bodů vrací 413 s kódem translation_too_large místo 400. Prázdné source_language se bere jako vynechané. Odpověď 429 zahrnuje Retry-After: 15. Tento server vrací také tyto chyby:

• 400 json_body_required při chybějícím těle, neplatném JSON nebo skalární hodnotě JSON. Pošli objekt JSON.
• 400 invalid_translation_options když text, target_language nebo engine chybí, je prázdné nebo není řetězcem, nebo když source_language není řetězcem.
• 400 invalid_translation_text u textu obsahujícího jen bílé znaky.
• 400 invalid_translation_engine při neznámém modulu.
• 400 idempotency_key_required při chybějícím, prázdném nebo příliš dlouhém klíči nebo pokud idempotency_key není řetězcem.
• 400 invalid_job při nesprávném formátu ID úlohy.

Odpovědi služby překladu na tomto serveru používají vnější strukturu {"status":{"code":HTTP_STATUS},"response":{...}}, kde status je objekt. ID úlohy načti z response.id a dokončený výsledek z response.result. Při chybách je kód v response.code bez zprávy nebo ID požadavku. Chyby ověřování (401) vrací obecná kontrola přihlášení serveru a mohou mít jiné tělo, proto před parsováním zkontroluj stav HTTP. Úlohy se sdílejí s hlavním serverem, ale pro pravidelné dotazování, vypořádání a využití používej stejný server, aby parser odpovídal vnější struktuře. Tento server přijímá stejná pole JSON také na /v3/translate/estimate bez klíče idempotence a odhad je pod response.