Tekstitõlke API

See API tõlgib teksti järjekorras töödeldavate töödena, üks sihtkeel töö kohta. Saatke tekst, salvestage tagastatud töö ID ja pärige tööd, kuni töötlemine on lõppenud. Saatke kõik päringud HTTPS-i kaudu oma konto autentimisandmetega: näidetes toodud HTTP Basic andmetega või API pääsmikuga, nagu on kirjeldatud jaotises Autentimine. Hoidke autentimisandmeid oma serveris.

Lõpp-punktid

Kaks API serverit, https://api.multi.tel ja ühilduvusserver https://api.multitel.net, jagavad samu kontopõhiseid töid, idempotentsusvõtmeid, piiranguid ja arveldust. Vastuse ümbris erineb, seega kasutage järjepidevalt üht serverit ning sobivat parserit.

Serveris api.multi.tel on kõik teed saadaval ka prefiksiga /v1/translate järgmise prefiksi asemel: /v3/translate. Serveris api.multitel.net kasutage /v3/translate teid.

Teenuse teabe vastus sisaldab välju enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages ja ratesNanosPerCharacter. cpuLanguages loetleb standardtõlkes aktsepteeritavate põhikeelte koodid. ratesNanosPerCharacter näitab iga mootori seadistatud hinda lähteteksti koodipunkti kohta USA dollari miljardikosades: väärtus 5000 tähendab $5 miljoni koodipunkti kohta. Vastus ei näita, kas täiustatud tõlge on praegu saadaval; täiustatud tõlke hinnang tagastab 503, kui see pole saadaval. Teabe pärimine on tasuta.

Teksti tõlkimine

Saatke JSON päisega Content-Type: application/json aadressile POST https://api.multi.tel/v3/translate. Igal tööl on üks sihtkeel, seega esitage iga sihtkeele jaoks eraldi töö.

Lokaadikoodid on BCP 47 sildid pikkusega 2 kuni 63 tähte, numbrit ja sidekriipsu. Need kanoniseeritakse, seega en-us salvestatakse kujul en-US. Vigased sildid ning und, mul või zxx tagastavad 400 invalid_translation_language. Standardtõlke saadavust kontrollitakse põhikeele järgi ning nb ja nn loetakse keeleks no. Piirkondlikku sihtkeelt, näiteks fr-CA, aktsepteeritakse ja see salvestatakse, kuid standardtulemus järgib põhikeelt ning selle vastavus piirkonnale pole tagatud.

Hoidke päringu keha selles serveris 128 KiB piires. Saatke tekst UTF-8-kujul, selle asemel et esitada iga ASCII-väline märk \u-jadana, mis võib viia 20,000 märgi pikkuse päringu üle piiri.

Keha aktsepteerib ainult neid nelja välja. Kõik muud atribuudid lükatakse tagasi vastusega 400 invalid_translation_request, sealhulgas idempotency_key, omanike ID-d, tasuta töötlemise lipud ja segmentide massiivid.

Idempotentsus ja taaskasutamine

Iga esitamine nõuab Idempotency-Key-päist pikkusega 1 kuni 190 märki. Kasutage ASCII tähti, numbreid, -, _, . ja : ilma algus- ja lõputühikuteta; puuduv või vähemalt 191 märgi pikkune võti lükatakse tagasi vastusega 400. Võtmed on seotud teie konto ja tõlkimisega mõlemas serveris ning kõigi teie konto autentimisandmete puhul.

• Sama võti sama teksti, kanoniseeritud keelte ja mootoriga tagastab olemasoleva töö vastusega HTTP 200 ja duplicate: true ilma uue tasuta.
• Sama võti teise teksti, keelte või mootoriga tagastab 409 idempotency_conflict. Sama võti tagastab 409 ka siis, kui töötlemisversioon on pärast töö loomist muutunud. Sellisel juhul pärige algset tööd selle ID järgi, selle asemel et see uuesti esitada.
• Uus võti sama teksti, kanoniseeritud keelte ja mootoriga tagastab olemasoleva töö vastusega HTTP 200 ja duplicate: true ilma uue töötlemistasuta, kui sama sisu ja praeguse töötlemisversiooniga töö on järjekorras, käib, on lõpetatud või ootab makset. Taaskasutatud töö eest, mis ootab makset, tuleb endiselt tasuda. Ebaõnnestunud töid ei taaskasutata: luuakse uus töö, mille eest võetakse tasu selle lõpetamisel.

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'

Uus töö tagastab HTTP 202. Näidistekstis on 57 koodipunkti, seega hinnaga $5 miljoni koodipunkti kohta maksab see $0.000285. Lühendatud vastus (tunnus on näide):

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

Esitamine võib tagastada ka 402 insufficient_balance, kui ettemakstud saldo ei kata tööd koos teie teiste lõpetamata töödega, ning 429 translation_queue_full, kui teie kontol või teenuses on liiga palju lõpetamata töid. Vastus 503 tagastatakse järgmistel juhtudel:

• paid_translation_not_enabled, kui tasuline tõlge on keelatud.
• translation_unavailable täiustatud tõlke päringu puhul, kui täiustatud tõlge pole saadaval.
• translation_pricing_unavailable, kui valitud mootorile pole hinda seadistatud.

Vastuste 429 ja 503 järel proovige hiljem sama võtmega uuesti.

Kvaliteedi valimine

Pikka teksti töödeldakse väiksemate osadena ja ühendatakse seejärel uuesti. Reavahetused ja tühikud võivad muutuda ning lause võib töötlemispiiril kaotada konteksti. Säilitage algne tekst ja vaadake kokkupandud tulemus üle. Standardtõlge kasutab piirkondliku sildi põhikeelt; sildi aktsepteerimine ja salvestamine ei taga piirkondlikku sõnastust.

Standardtõlge töötab CPU tööprotsessides. Täiustatud tõlge saadab teksti seadistatud välisesse tehisintellektiteenusesse. Ka selle väljund tuleb üle vaadata; teenus ei taga, et üks mootor oleks iga keelepaari või tekstiliigi puhul täpsem.

Standardtõlge on mustand, mille kvaliteet ja töötlemisaeg sõltuvad keelepaarist. Täiustatud tõlge on mõeldud teksti jaoks, kus kontekst on oluline, kuid ka selles tuleb kontrollida olulisi nimesid, numbreid, eitusi ja lubadusi. Kumbki valik ei paranda algses transkriptsioonis juba esinevaid vigu, seega hoidke originaal võrdlemiseks alles.

Kasutage GET /v3/translate samas API serveris, et kontrollida praegust saadavust, toetatud standardkeeli ja seadistatud hindu. Standardpäring, mille lähte- või sihtpõhikeelt pole loendis cpuLanguages, tagastab 422 translation_language_pair_unavailable. Kui source_language on antud ja selle põhikeel on sihtkeelega sama, tagastab päring 409 translation_same_language töö loomise asemel. Täiustatud tõlge lubatakse eraldi: kui see pole saadaval, tagastavad täiustatud tõlke esitused ja hinnangud 503.

Esmalt hinnangu saamine

Serveris api.multi.tel saatke sama JSON-keha aadressile POST /v3/translate/estimate. Idempotentsusvõtit pole vaja. Hinnang kasutab sama valideerimist, sealhulgas kontrolle 422 ja 409, kuid ei loo tööd, tõlgi teksti, broneeri raha, kontrolli teie saldot ega võta kontolt tasu. See tagastab HTTP 200 väljadega estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd ja costUsd objekti data sees. Ülaltoodud näites on costUsd väärtus 0.000285000 standardhinna korral. Kui täiustatud tõlge pole saadaval, tagastab täiustatud tõlke hinnang 503 service_unavailable. Hinnangud kasutavad praegu seadistatud hinda. Töö hind fikseeritakse töö loomisel ning tasu arvutatakse selle hinna järgi.

Tõlke pärimine

Uus esitus tagastab HTTP 202 ning olemasolev või taaskasutatud töö tagastab HTTP 200. Salvestage data.id ja kasutage ühist töövoogu. Tööobjekt sisaldab järgmisi välju:

• id, status, engine, sourceLocale ja targetLocale.
• sourceCharacters, costUsd, costIsEstimate ja pricePerMillionCharactersUsd.
• progress ja createdAt.
• modelVersion, läbipaistmatu töötlemisversiooni string.
• duplicate taaskasutatud tööde vastustes.
• failureCode ebaõnnestunud tööde puhul: translation_failed, translation_timeout, input_failed või worker_lease_lost.

Ebaõnnestunud töö costUsd on null.

Lõpetatud tööl on data.result koos väljadega sourceLocale (tühi, kui lähtekeelt ei antud), targetLocale, tõlgitud text (segmentide tekstid reavahetustega ühendatuna) ja segments. Selle API kaudu esitatud teksti puhul sisaldab segments üht kirjet, milles on tõlgitud text ja sihtkeele language. Makse ootel tööde tulemusi ei väljastata enne tasumist.

api.multitel.net-i kasutamine

Ühilduvuse lõpp-punkt POST https://api.multitel.net/v3/translate aktsepteerib samu JSON-välju ja sama Idempotency-Key-päist. Kui päis puudub, aktsepteerib see ka idempotency_key-stringi JSON-kehas. Kõik muud lisaväljad lükatakse tagasi vastusega 400 unsupported_translation_option. Selles serveris võib töötlemata keha olla kuni 256,000 baiti ning üle 20,000 koodipunkti pikkune tekst tagastab 413 translation_too_large vastuse 400 asemel. Tühja source_language käsitatakse puuduvana. Vastus 429 sisaldab Retry-After: 15. See server tagastab ka järgmised vead:

• 400 json_body_required, kui keha puudub, on vigane JSON või JSON-skalaar. Saatke JSON-objekt.
• 400 invalid_translation_options, kui text, target_language või engine puudub, on tühi või pole string või source_language pole string.
• 400 invalid_translation_text üksnes tühimärkidest koosneva teksti korral.
• 400 invalid_translation_engine tundmatu mootori korral.
• 400 idempotency_key_required puuduva, tühja või liiga pika võtme korral või kui idempotency_key pole string.
• 400 invalid_job vigases vormingus töö ID korral.

Selle serveri tõlketeenuse vastused kasutavad ümbrist {"status":{"code":HTTP_STATUS},"response":{...}}, kus status on objekt. Lugege töö ID väljalt response.id ning lõpetatud tulemus väljalt response.result. Vigade korral asub kood väljal response.code ilma teate ja päringu ID-ta. Autentimisvead (401) tagastatakse serveri üldise sisselogimiskontrolli kaudu ja nende keha võib erineda, seega kontrollige enne parsimist HTTP olekut. Töid jagatakse põhiserveriga, kuid kasutage korduvpäringuteks, tasumiseks ja kasutuse pärimiseks sama serverit, et parser vastaks ümbrisele. See server aktsepteerib samu JSON-välju ka teel /v3/translate/estimate ilma idempotentsusvõtmeta ning hinnang asub objekti response sees.