Teksto vertimo API

Ši API verčia tekstą kaip į eilę įtrauktas užduotis: vienai užduočiai skirta viena tikslinė kalba. Pateikite tekstą, išsaugokite grąžintą užduoties ID ir užklauskite užduoties, kol apdorojimas bus baigtas. Visas užklausas siųskite per HTTPS su savo paskyros prisijungimo duomenimis: pavyzdžiuose parodytais HTTP Basic duomenimis arba API prieigos raktu, kaip aprašyta skyriuje Autentifikavimas. Prisijungimo duomenis laikykite savo serveryje.

Galiniai taškai

Du API serveriai, https://api.multi.tel ir suderinamumo serveris https://api.multitel.net, naudoja tas pačias paskyrai priskirtas užduotis, idempotentiškumo raktus, apribojimus ir atsiskaitymą. Atsakymo apvalkalas skiriasi, todėl nuosekliai naudokite vieną serverį su jam tinkamu analizatoriumi.

Serveryje api.multi.tel visi keliai taip pat pasiekiami su prefiksu /v1/translate vietoj /v3/translate. Serveryje api.multitel.net naudokite /v3/translate kelius.

Paslaugos informacijos atsakyme pateikiami enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages ir ratesNanosPerCharacter. cpuLanguages pateikia pagrindinių kalbų kodus, priimamus standartiniam vertimui. ratesNanosPerCharacter pateikia kiekvienam varikliui sukonfigūruotą kainą už šaltinio teksto kodo tašką JAV dolerio milijardosiomis dalimis: reikšmė 5000 reiškia $5 už milijoną kodo taškų. Atsakymas nepraneša, ar patobulintas vertimas šiuo metu pasiekiamas; kai jis nepasiekiamas, patobulinto vertimo įvertis grąžina 503. Šią informaciją gauti nemokama.

Verskite tekstą

Siųskite JSON su antrašte Content-Type: application/json adresu POST https://api.multi.tel/v3/translate. Kiekviena užduotis turi vieną tikslinę kalbą, todėl kiekvienai tikslinei kalbai pateikite atskirą užduotį.

Lokalių kodai yra BCP 47 žymos iš 2–63 raidžių, skaitmenų ir brūkšnelių. Jos kanonizuojamos, todėl en-us įrašomas kaip en-US. Netaisyklingos žymos ir und, mul arba zxx grąžina 400 invalid_translation_language. Standartinio vertimo prieinamumas tikrinamas pagal pagrindinę kalbą, o nb ir nn laikomi no. Regioninė tikslinė kalba, pavyzdžiui, fr-CA, priimama ir įrašoma, bet standartinis rezultatas atitinka pagrindinę kalbą ir negarantuojama, kad atspindės regioną.

Šiame serveryje užklausos turinys turi neviršyti 128 KiB. Siųskite tekstą UTF-8 formatu, o ne kiekvieną ne ASCII simbolį užrašydami kaip \u seką, nes taip 20,000 simbolių užklausa gali viršyti ribą.

Turinyje priimami tik šie keturi laukai. Bet kuri kita savybė atmetama su 400 invalid_translation_request, įskaitant idempotency_key, savininkų ID, nemokamo apdorojimo požymius ir segmentų masyvus.

Idempotentiškumas ir pakartotinis naudojimas

Kiekvienam pateikimui būtina Idempotency-Key antraštė, turinti nuo 1 iki 190 simbolių. Naudokite ASCII raides, skaitmenis, -, _, . ir : be tarpų pradžioje ar pabaigoje; trūkstamas arba 191 ar daugiau simbolių turintis raktas atmetamas su 400. Raktai priskiriami jūsų paskyrai ir vertimui abiejuose serveriuose bei naudojant visus jūsų paskyros prisijungimo duomenis.

• Tas pats raktas su tuo pačiu tekstu, kanonizuotomis kalbomis ir varikliu grąžina esamą užduotį su HTTP 200 ir duplicate: true be pakartotinio mokesčio.
• Tas pats raktas su kitu tekstu, kalbomis arba varikliu grąžina 409 idempotency_conflict. Tas pats raktas taip pat grąžina 409, jei nuo užduoties sukūrimo pasikeitė apdorojimo versija. Tokiu atveju gaukite pradinę užduotį pagal jos ID, užuot pateikę iš naujo.
• Naujas raktas su tuo pačiu tekstu, kanonizuotomis kalbomis ir varikliu grąžina esamą užduotį su HTTP 200 ir duplicate: true be naujo apdorojimo mokesčio, jei užduotis su tuo turiniu ir dabartine apdorojimo versija yra eilėje, vykdoma, baigta arba laukia mokėjimo. Pakartotinai naudojamą mokėjimo laukiančią užduotį vis tiek reikia apmokėti. Nepavykusios užduotys pakartotinai nenaudojamos: sukuriama nauja užduotis, už kurią mokestis taikomas ją baigus.

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'

Nauja užduotis grąžina HTTP 202. Pavyzdžio tekste yra 57 kodo taškai, todėl taikant $5 už milijoną kodo taškų kainą jis kainuoja $0.000285. Sutrumpintas atsakymas (identifikatorius yra pavyzdys):

{
  "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
  }
}

Pateikimas taip pat gali grąžinti 402 insufficient_balance, kai išankstinio mokėjimo likučio nepakanka šiai užduočiai kartu su kitomis nebaigtomis jūsų užduotimis, ir 429 translation_queue_full, kai jūsų paskyroje arba paslaugoje yra per daug nebaigtų užduočių. Atsakymas 503 grąžinamas šiais atvejais:

• paid_translation_not_enabled, kai mokamas vertimas išjungtas.
• translation_unavailable patobulinto vertimo užklausai, kai patobulintas vertimas nepasiekiamas.
• translation_pricing_unavailable, kai pasirinktam varikliui nesukonfigūruotas įkainis.

Gavę 429 ar 503 atsakymą, vėliau bandykite dar kartą su tuo pačiu raktu.

Pasirinkite kokybę

Ilgas tekstas apdorojamas mažesnėmis dalimis ir vėl sujungiamas. Eilučių lūžiai ir tarpai gali pasikeisti, o ties apdorojimo riba sakinys gali prarasti kontekstą. Išsaugokite pradinį tekstą ir peržiūrėkite sujungtą rezultatą. Standartinis vertimas naudoja regioninės žymos pagrindinę kalbą; žymos priėmimas ir įrašymas negarantuoja regioninės formuluotės.

Standartinis vertimas vykdomas CPU darbiniuose procesuose. Patobulintas vertimas siunčia tekstą į sukonfigūruotą išorinę DI paslaugą. Jos rezultatą vis tiek reikia peržiūrėti; paslauga negarantuoja, kad vienas variklis tikslesnis kiekvienai kalbų porai ar teksto tipui.

Standartinis vertimas yra juodraštis, kurio kokybė ir apdorojimo laikas priklauso nuo kalbų poros. Patobulintas vertimas skirtas tekstui, kuriam svarbus kontekstas, bet vis tiek reikia patikrinti svarbius vardus, skaičius, neiginius ir įsipareigojimus. Nė vienas variantas neištaiso klaidų, jau esančių pradinėje transkripcijoje, todėl išsaugokite originalą palyginimui.

Naudokite GET /v3/translate tame pačiame API serveryje, kad patikrintumėte dabartinį pasiekiamumą, palaikomas standartinio vertimo kalbas ir sukonfigūruotus įkainius. Standartinė užklausa, kurios šaltinio arba tikslinė pagrindinė kalba nėra sąraše cpuLanguages, grąžina 422 translation_language_pair_unavailable. Kai source_language pateiktas ir jo pagrindinė kalba tokia pati kaip tikslinė, užklausa grąžina 409 translation_same_language, užuot sukūrusi užduotį. Patobulintas vertimas įjungiamas atskirai: kol jis nepasiekiamas, patobulinto vertimo pateikimai ir įverčiai grąžina 503.

Pirmiausia gaukite įvertį

Serveryje api.multi.tel siųskite tą patį JSON turinį adresu POST /v3/translate/estimate. Idempotentiškumo raktas nereikalingas. Įverčiui taikoma ta pati validacija, įskaitant 422 ir 409 patikras, bet jis nesukuria užduoties, neverčia teksto, nerezervuoja lėšų, netikrina likučio ir neapmokestina paskyros. Jis grąžina HTTP 200 su laukais estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd ir costUsd objekte data. Pirmiau pateiktame pavyzdyje costUsd yra 0.000285000 taikant standartinį įkainį. Kai patobulintas vertimas nepasiekiamas, patobulinto vertimo įvertis grąžina 503 service_unavailable. Įverčiai naudoja šiuo metu sukonfigūruotą įkainį. Užduoties įkainis užfiksuojamas ją sukuriant ir naudojamas jos mokesčiui apskaičiuoti.

Gaukite vertimą

Naujas pateikimas grąžina HTTP 202, o esama arba pakartotinai naudojama užduotis grąžina HTTP 200. Išsaugokite data.id ir naudokite bendrą užduočių eigą. Užduoties objektas turi šiuos laukus:

• id, status, engine, sourceLocale ir targetLocale.
• sourceCharacters, costUsd, costIsEstimate ir pricePerMillionCharactersUsd.
• progress ir createdAt.
• modelVersion, neinterpretuojama apdorojimo versijos eilutė.
• duplicate pakartotinai naudojamų užduočių atsakymuose.
• failureCode nepavykusioms užduotims: translation_failed, translation_timeout, input_failed arba worker_lease_lost.

Nepavykusios užduoties costUsd yra nulis.

Baigta užduotis turi data.result su sourceLocale (tuščias, jei šaltinio kalba nepateikta), targetLocale, išverstu text (segmentų tekstai sujungti eilučių lūžiais) ir segments. Per šią API pateiktam tekstui segments turi vieną įrašą su išverstu text ir tiksline language. Mokėjimo laukiančių užduočių rezultatai neteikiami, kol neapmokėta.

api.multitel.net naudojimas

Suderinamumo galinis taškas POST https://api.multitel.net/v3/translate priima tuos pačius JSON laukus ir tą pačią Idempotency-Key antraštę. Jei jos nėra, taip pat priima idempotency_key eilutę JSON turinyje. Bet kuris kitas papildomas laukas atmetamas su 400 unsupported_translation_option. Šiame serveryje neapdorotas turinys gali būti iki 256,000 baitų, o tekstas, ilgesnis nei 20,000 kodo taškų, grąžina 413 translation_too_large vietoj 400. Tuščias source_language laikomas praleistu. 429 atsakyme pateikiama Retry-After: 15. Šis serveris taip pat grąžina šias klaidas:

• 400 json_body_required, kai turinio nėra, tai netaisyklingas JSON arba JSON skaliaras. Siųskite JSON objektą.
• 400 invalid_translation_options, kai text, target_language arba engine trūksta, jis tuščias arba nėra eilutė, arba source_language nėra eilutė.
• 400 invalid_translation_text, kai tekstas sudarytas tik iš tarpo simbolių.
• 400 invalid_translation_engine, kai variklis nežinomas.
• 400 idempotency_key_required, kai rakto nėra, jis tuščias arba per ilgas, arba kai idempotency_key nėra eilutė.
• 400 invalid_job, kai užduoties ID formatas netaisyklingas.

Šio serverio vertimo paslaugos atsakymai naudoja apvalkalą {"status":{"code":HTTP_STATUS},"response":{...}}, kuriame status yra objektas. Užduoties ID skaitykite iš response.id, o baigtą rezultatą iš response.result. Klaidos atveju kodas pateikiamas response.code be pranešimo ar užklausos ID. Autentifikavimo klaidas (401) grąžina bendroji serverio prisijungimo patikra; jų turinys gali skirtis, todėl prieš analizuodami patikrinkite HTTP būseną. Užduotys bendros su pagrindiniu serveriu, bet periodinėms užklausoms, apmokėjimui ir naudojimui naudokite tą patį serverį, kad analizatorius atitiktų apvalkalą. Šis serveris taip pat priima tuos pačius JSON laukus adresu /v3/translate/estimate be idempotentiškumo rakto; įvertis pateikiamas objekte response.