Teksta tulkošanas API

Šis API tulko tekstu kā rindā ievietotus darbus ar vienu mērķvalodu katrā darbā. Iesniedziet tekstu, saglabājiet atgriezto darba ID un izgūstiet darbu, līdz apstrāde ir pabeigta. Sūtiet visus pieprasījumus, izmantojot HTTPS un sava konta autentifikācijas datus: piemēros parādītos HTTP Basic datus vai API pilnvaru, kā aprakstīts sadaļā Autentifikācija. Glabājiet autentifikācijas datus savā serverī.

Galapunkti

Abi API serveri — https://api.multi.tel un saderības serveris https://api.multitel.net — koplieto vienus un tos pašus konta darbus, idempotences atslēgas, ierobežojumus un norēķinus. Atbildes ietvars atšķiras, tāpēc konsekventi izmantojiet vienu serveri ar atbilstošu parsētāju.

Serverī api.multi.tel visi ceļi ir pieejami arī ar prefiksu /v1/translate šī prefiksa vietā: /v3/translate. Serverī api.multitel.net izmantojiet /v3/translate ceļus.

Pakalpojuma informācijas atbildē ir norādīti enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages un ratesNanosPerCharacter. cpuLanguages uzskaita pamatvalodu kodus, kas tiek pieņemti standarta tulkošanai. ratesNanosPerCharacter norāda katram dzinējam konfigurēto cenu par avota teksta kodpunktu ASV dolāra miljarddaļās: vērtība 5000 nozīmē $5 par miljonu kodpunktu. Atbilde nenorāda, vai uzlabotā tulkošana pašlaik ir pieejama; uzlabotās tulkošanas tāme atgriež 503, ja tā nav pieejama. Informācijas izgūšana ir bez maksas.

Tulkojiet tekstu

Sūtiet JSON ar galveni Content-Type: application/json uz POST https://api.multi.tel/v3/translate. Katram darbam ir viena mērķvaloda, tāpēc katrai mērķvalodai iesniedziet atsevišķu darbu.

Lokalizācijas kodi ir BCP 47 birkas ar 2 līdz 63 burtiem, cipariem un defisēm. Tie tiek kanonizēti, tāpēc en-us tiek ierakstīts kā en-US. Nederīgas birkas, kā arī und, mul vai zxx atgriež 400 invalid_translation_language. Standarta pieejamība tiek pārbaudīta pēc pamatvalodas, un nb un nn tiek uzskatīti par no. Reģionāla mērķvaloda, piemēram, fr-CA, tiek pieņemta un ierakstīta, bet standarta rezultāts atbilst pamatvalodai, un netiek garantēts, ka tas atspoguļos reģionu.

Šajā serverī pieprasījuma pamatdaļa nedrīkst pārsniegt 128 KiB. Sūtiet tekstu UTF-8 kodējumā, nevis katru rakstzīmi ārpus ASCII aizstājot ar \u secību, jo tas var izraisīt 20,000 rakstzīmju pieprasījuma limita pārsniegšanu.

Pamatdaļā tiek pieņemti tikai šie četri lauki. Jebkurš cits rekvizīts tiek noraidīts ar 400 invalid_translation_request, tostarp idempotency_key, īpašnieku ID, bezmaksas apstrādes karodziņi un segmentu masīvi.

Idempotence un atkārtota izmantošana

Katram iesniegumam nepieciešama Idempotency-Key galvene ar 1 līdz 190 rakstzīmēm. Izmantojiet ASCII burtus, ciparus, -, _, . un : bez atstarpēm sākumā vai beigās; trūkstoša atslēga vai atslēga ar 191 vai vairāk rakstzīmēm tiek noraidīta ar 400. Atslēgas ir piesaistītas jūsu kontam un tulkošanai abos serveros un ar visiem jūsu konta autentifikācijas datiem.

• Tā pati atslēga ar to pašu tekstu, kanonizētajām valodām un dzinēju atgriež esošo darbu ar HTTP 200 un duplicate: true bez atkārtotas maksas.
• Tā pati atslēga ar citu tekstu, valodām vai dzinēju atgriež 409 idempotency_conflict. Tā pati atslēga atgriež 409 arī tad, ja apstrādes versija kopš darba izveides ir mainījusies. Šādā gadījumā izgūstiet sākotnējo darbu pēc tā ID, nevis iesniedziet to atkārtoti.
• Jauna atslēga ar to pašu tekstu, kanonizētajām valodām un dzinēju atgriež esošo darbu ar HTTP 200 un duplicate: true bez jaunas apstrādes maksas, ja darbs ar šo saturu un pašreizējo apstrādes versiju ir rindā, tiek apstrādāts, ir pabeigts vai gaida maksājumu. Atkārtoti izmantots darbs, kas gaida maksājumu, joprojām ir jāapmaksā. Neveiksmīgi darbi netiek izmantoti atkārtoti: tiek izveidots jauns darbs, par kuru maksa tiek iekasēta pēc pabeigšanas.

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'

Jauns darbs atgriež HTTP 202. Piemēra tekstā ir 57 kodpunkti, tāpēc pie $5 par miljonu kodpunktu tā maksa ir $0.000285. Saīsināta atbilde (identifikators ir piemērs):

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

Iesniegums var atgriezt arī 402 insufficient_balance, ja priekšapmaksas atlikums nevar segt šo darbu kopā ar citiem jūsu nepabeigtajiem darbiem, un 429 translation_queue_full, ja jūsu kontā vai pakalpojumā ir pārāk daudz nepabeigtu darbu. Tā atgriež 503 šādos gadījumos:

• paid_translation_not_enabled, kamēr maksas tulkošana ir atspējota.
• translation_unavailable uzlabotās tulkošanas pieprasījumam, kamēr uzlabotā tulkošana nav pieejama.
• translation_pricing_unavailable, kamēr izvēlētajam dzinējam nav konfigurēta tarifa.

Pēc atbildēm 429 un 503 mēģiniet vēlāk vēlreiz ar to pašu atslēgu.

Izvēlieties kvalitāti

Garš teksts tiek apstrādāts mazākās daļās un atkal apvienots. Rindu pārtraukumi un atstarpes var mainīties, un teikums var zaudēt kontekstu pie apstrādes robežas. Saglabājiet sākotnējo tekstu un pārskatiet apvienoto rezultātu. Standarta tulkošana izmanto reģionālās birkas pamatvalodu; birkas pieņemšana un ierakstīšana negarantē reģionālu formulējumu.

Standarta tulkošana darbojas CPU darba procesos. Uzlabotā tulkošana nosūta tekstu konfigurētajam ārējam MI pakalpojumam. Arī tā rezultāts ir jāpārskata; pakalpojums negarantē, ka viens dzinējs būs precīzāks katram valodu pārim vai teksta veidam.

Standarta tulkojums ir melnraksts, kura kvalitāte un apstrādes laiks atšķiras atkarībā no valodu pāra. Uzlabotā tulkošana ir paredzēta tekstam, kurā nozīme ir kontekstam, taču arī tajā ir jāpārbauda svarīgi vārdi, skaitļi, noliegumi un saistības. Neviena iespēja neizlabo sākotnējā transkripcijā jau esošās kļūdas, tāpēc saglabājiet oriģinālu salīdzināšanai.

Izmantojiet GET /v3/translate tajā pašā API serverī, lai pārbaudītu pašreizējo pieejamību, atbalstītās standarta valodas un konfigurētos tarifus. Standarta pieprasījums, kura avota vai mērķa pamatvaloda nav sarakstā cpuLanguages, atgriež 422 translation_language_pair_unavailable. Ja source_language ir norādīts un tam ir tā pati pamatvaloda kā mērķvalodai, pieprasījums atgriež 409 translation_same_language, nevis izveido darbu. Uzlabotā tulkošana tiek iespējota atsevišķi: kamēr tā nav pieejama, uzlabotās tulkošanas iesniegumi un tāmes atgriež 503.

Vispirms iegūstiet tāmi

Serverī api.multi.tel sūtiet to pašu JSON pamatdaļu uz POST /v3/translate/estimate. Idempotences atslēga nav nepieciešama. Tāmei tiek piemērota tā pati validācija, tostarp 422 un 409 pārbaudes, taču tā neizveido darbu, netulko tekstu, nerezervē līdzekļus, nepārbauda atlikumu un neiekasē maksu no jūsu konta. Tā atgriež HTTP 200 ar laukiem estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd un costUsd objektā data. Iepriekšējā piemērā costUsd ir 0.000285000 pēc standarta tarifa. Kamēr uzlabotā tulkošana nav pieejama, uzlabotās tulkošanas tāme atgriež 503 service_unavailable. Tāmes izmanto pašlaik konfigurēto tarifu. Darba tarifs tiek fiksēts darba izveides brīdī, un maksa tiek aprēķināta pēc šī tarifa.

Izgūstiet tulkojumu

Jauns iesniegums atgriež HTTP 202, bet esošs vai atkārtoti izmantots darbs atgriež HTTP 200. Saglabājiet data.id un izmantojiet kopīgo darbu plūsmu. Darba objekts satur šādus laukus:

• id, status, engine, sourceLocale un targetLocale.
• sourceCharacters, costUsd, costIsEstimate un pricePerMillionCharactersUsd.
• progress un createdAt.
• modelVersion — necaurspīdīga apstrādes versijas virkne.
• duplicate atkārtoti izmantotu darbu atbildēs.
• failureCode neveiksmīgiem darbiem: translation_failed, translation_timeout, input_failed vai worker_lease_lost.

Neveiksmīgam darbam costUsd ir nulle.

Pabeigtam darbam ir data.result ar sourceLocale (tukšs, ja avota valoda netika norādīta), targetLocale, tulkotais text (segmentu teksti, savienoti ar rindu pārtraukumiem) un segments. Tekstam, kas iesniegts caur šo API, segments satur vienu ierakstu ar tulkoto text un mērķa language. Darbu, kas gaida maksājumu, rezultāti tiek aizturēti līdz apmaksai.

api.multitel.net izmantošana

Saderības galapunkts POST https://api.multitel.net/v3/translate pieņem tos pašus JSON laukus un to pašu Idempotency-Key galveni. Ja galvenes nav, tas pieņem arī idempotency_key virkni JSON pamatdaļā. Jebkurš cits papildu lauks tiek noraidīts ar 400 unsupported_translation_option. Šajā serverī neapstrādātā pamatdaļa var būt līdz 256,000 baitiem, un teksts ar vairāk nekā 20,000 kodpunktiem atgriež 413 translation_too_large, nevis 400. Tukšs source_language tiek uzskatīts par izlaistu. Atbilde 429 ietver Retry-After: 15. Šis serveris atgriež arī šādas kļūdas:

• 400 json_body_required, ja pamatdaļas nav, tā ir nederīgs JSON vai JSON skalārs. Sūtiet JSON objektu.
• 400 invalid_translation_options, ja text, target_language vai engine nav norādīts, ir tukšs vai nav virkne, vai source_language nav virkne.
• 400 invalid_translation_text tekstam, kas sastāv tikai no atstarpju rakstzīmēm.
• 400 invalid_translation_engine nezināmam dzinējam.
• 400 idempotency_key_required trūkstošai, tukšai vai pārāk garai atslēgai vai ja idempotency_key nav virkne.
• 400 invalid_job nepareizi formatētam darba ID.

Šī servera tulkošanas pakalpojuma atbildēs tiek izmantots ietvars {"status":{"code":HTTP_STATUS},"response":{...}}, kurā status ir objekts. Nolasiet darba ID no response.id un pabeigto rezultātu no response.result. Kļūdu gadījumā kods ir laukā response.code bez ziņojuma vai pieprasījuma ID. Autentifikācijas kļūdas (401) atgriež servera vispārējā pierakstīšanās pārbaude, un to pamatdaļa var atšķirties, tāpēc pirms parsēšanas pārbaudiet HTTP statusu. Darbi tiek koplietoti ar primāro serveri, taču periodiskai izgūšanai, apmaksai un lietojumam izmantojiet to pašu serveri, lai parsētājs atbilstu ietvaram. Šis serveris pieņem tos pašus JSON laukus arī ceļā /v3/translate/estimate bez idempotences atslēgas, un tāme atrodas objektā response.