API për përkthimin e tekstit

Ky API përkthen tekst si punë në radhë, me një gjuhë të synuar për çdo punë. Dërgoni tekst, ruani ID-në e kthyer të punës dhe lexojeni punën derisa përpunimi të ketë përfunduar. Dërgoni çdo kërkesë përmes HTTPS me kredencialet e llogarisë suaj, ose kredenciale HTTP Basic si në shembuj, ose një token API, siç përshkruhet te Autentikimi. Mbajini kredencialet në serverin tuaj.

Pikat fundore

Dy hostet API, https://api.multi.tel dhe hosti i përputhshmërisë https://api.multitel.net, ndajnë të njëjtat punë, çelësa idempotence, kufij dhe faturim të lidhur me llogarinë. Ato ndryshojnë në mbështjellësin e përgjigjes, prandaj përdorni vazhdimisht një host me analizuesin përkatës të përgjigjeve.

Në api.multi.tel, çdo shteg është gjithashtu i disponueshëm me prefiksin /v1/translate në vend të /v3/translate. Në api.multitel.net, përdorni shtigjet /v3/translate.

Përgjigjja me informacionin e shërbimit raporton enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages dhe ratesNanosPerCharacter. cpuLanguages rendit kodet bazë të gjuhëve që pranohen për përkthimin standard. ratesNanosPerCharacter jep çmimin e konfiguruar për çdo pikë kodi të tekstit burim për secilin motor, në të miliardtat e një dollari amerikan: një vlerë 5000 do të thotë $5 për milion pika kodi. Përgjigjja nuk raporton nëse përkthimi i përmirësuar është aktualisht i disponueshëm; një vlerësim për përkthim të përmirësuar kthen 503 kur ai është i padisponueshëm. Leximi është falas.

Përktheni tekst

Dërgoni JSON me Content-Type: application/json te POST https://api.multi.tel/v3/translate. Çdo punë ka një gjuhë të synuar, prandaj dërgoni një punë të veçantë për secilën gjuhë të synuar.

Kodet gjuhësore dhe rajonale janë etiketa BCP 47 me 2 deri në 63 shkronja, shifra dhe viza lidhëse. Ato kanonizohen, kështu që en-us regjistrohet si en-US. Etiketat e pavlefshme, si dhe und, mul ose zxx, kthejnë 400 invalid_translation_language. Disponueshmëria e përkthimit standard kontrollohet sipas gjuhës bazë dhe nb dhe nn llogariten si no. Një gjuhë e synuar me kod rajonal si fr-CA pranohet dhe regjistrohet, por rezultati standard ndjek gjuhën bazë dhe nuk garantohet që të pasqyrojë rajonin.

Mbajeni trupin e kërkesës brenda 128 KiB në këtë host. Dërgojeni tekstin si UTF-8 në vend që të shkruani çdo shenjë jo-ASCII në formën e një sekuence \u, gjë që mund ta çojë një kërkesë me 20,000 shenja përtej kufirit.

Trupi pranon vetëm këto katër fusha. Çdo veti tjetër refuzohet me 400 invalid_translation_request, përfshirë idempotency_key, ID-të e pronarëve, sinjalizuesit e përpunimit falas dhe masivët e segmenteve.

Idempotenca dhe ripërdorimi

Çdo dërgim kërkon një fushë të kreut HTTP Idempotency-Key me 1 deri në 190 shenja. Përdorni shkronja ASCII, shifra, -, _, . dhe :, pa hapësira në fillim ose fund; një çelës që mungon ose një çelës me 191 a më shumë shenja refuzohet me 400. Çelësat lidhen me llogarinë tuaj dhe shërbimin e përkthimit, në të dy hostet dhe për të gjitha kredencialet e llogarisë suaj.

• I njëjti çelës me të njëjtin tekst, gjuhë të kanonizuara dhe motor kthen punën ekzistuese me HTTP 200 dhe duplicate: true, pa një tarifë tjetër.
• I njëjti çelës me tekst, gjuhë ose motor tjetër kthen 409 idempotency_conflict. I njëjti çelës kthen gjithashtu 409 nëse versioni i përpunimit ka ndryshuar që nga krijimi i punës së tij. Në atë rast, lexojeni punën origjinale sipas ID-së së saj në vend që ta ridërgoni.
• Një çelës i ri me të njëjtin tekst, gjuhë të kanonizuara dhe motor kthen punën ekzistuese me HTTP 200 dhe duplicate: true, pa tarifë të re përpunimi, nëse një punë me atë përmbajtje dhe versionin aktual të përpunimit është në radhë, në ekzekutim, e përfunduar ose në pritje të pagesës. Një punë e ripërdorur që pret pagesën duhet ende të shlyhet. Punët e dështuara nuk ripërdoren: krijohet një punë e re dhe tarifohet kur përfundon.

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'

Një punë e re kthen HTTP 202. Teksti shembull ka 57 pika kodi, prandaj me $5 për milion pika kodi kushton $0.000285. Një përgjigje e shkurtuar (identifikuesi është shembull):

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

Një dërgim mund të kthejë edhe 402 insufficient_balance kur bilanci i parapaguar nuk e mbulon punën së bashku me punët tuaja të tjera të papërfunduara, dhe 429 translation_queue_full kur llogaria juaj ose shërbimi ka tepër punë të papërfunduara. Kthen 503 në këto raste:

• paid_translation_not_enabled kur përkthimi me pagesë është i çaktivizuar.
• translation_unavailable për një kërkesë të përmirësuar kur përkthimi i përmirësuar është i padisponueshëm.
• translation_pricing_unavailable kur motori i zgjedhur nuk ka një tarifë të konfiguruar.

Riprovoni më vonë kërkesat me përgjigje 429 dhe 503 duke përdorur të njëjtin çelës.

Zgjidhni cilësinë

Teksti i gjatë përpunohet në pjesë më të vogla dhe bashkohet përsëri. Ndërprerjet e rreshtave dhe hapësirat mund të ndryshojnë dhe një fjali mund të humbasë kontekstin në kufirin midis pjesëve të përpunimit. Mbajeni tekstin origjinal dhe shqyrtoni rezultatin e bashkuar. Përkthimi standard përdor gjuhën bazë të një etikete rajonale; pranimi dhe regjistrimi i një etikete nuk garanton formulim rajonal.

Përkthimi standard ekzekutohet në procese përpunimi CPU. Përkthimi i përmirësuar e dërgon tekstin te shërbimi i jashtëm AI i konfiguruar. Rezultati i tij ende ka nevojë për shqyrtim; shërbimi nuk garanton se njëri motor është më i saktë për çdo çift gjuhësh ose lloj teksti.

Përkthimi standard është një draft, cilësia dhe koha e përpunimit të të cilit ndryshojnë sipas çiftit të gjuhëve. Përkthimi i përmirësuar synon tekstin ku konteksti ka rëndësi, por ende kërkon shqyrtim të emrave, numrave, mohimeve dhe zotimeve të rëndësishme. Asnjëra alternativë nuk ndreq gabime që janë tashmë në një transkript origjinal, prandaj mbajeni origjinalin për krahasim.

Përdorni GET /v3/translate në të njëjtin host API për të kontrolluar disponueshmërinë aktuale, gjuhët e mbështetura për përkthim standard dhe tarifat e konfiguruara. Një kërkesë standarde, gjuha bazë burimore ose e synuar e së cilës nuk është në cpuLanguages, kthen 422 translation_language_pair_unavailable. Kur source_language jepet dhe ka të njëjtën gjuhë bazë si gjuha e synuar, kërkesa kthen 409 translation_same_language në vend që të krijojë një punë. Përkthimi i përmirësuar aktivizohet veçmas: kur është i padisponueshëm, dërgimet dhe vlerësimet për përkthim të përmirësuar kthejnë 503.

Vlerësoni fillimisht

Në api.multi.tel, dërgojeni të njëjtin trup JSON te POST /v3/translate/estimate. Nuk kërkohet çelës idempotence. Një vlerësim zbaton të njëjtin verifikim, përfshirë kontrollet 422 dhe 409, por nuk krijon një punë, nuk përkthen tekst, nuk rezervon fonde, nuk kontrollon bilancin tuaj dhe nuk tarifon llogarinë tuaj. Kthen HTTP 200 me estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd dhe costUsd brenda data. Për shembullin më sipër, costUsd është 0.000285000 me tarifën standarde. Kur përkthimi i përmirësuar është i padisponueshëm, një vlerësim për të kthen 503 service_unavailable. Vlerësimet përdorin tarifën e konfiguruar aktualisht. Tarifa e një pune fiksohet kur krijohet puna dhe tarifimi i saj përdor atë tarifë.

Merrni përkthimin

Një dërgim i ri kthen HTTP 202 dhe një punë ekzistuese ose e ripërdorur kthen HTTP 200. Ruani data.id dhe përdorni rrjedhën e përbashkët të punëve. Objekti i punës përmban këto fusha:

• id, status, engine, sourceLocale dhe targetLocale.
• sourceCharacters, costUsd, costIsEstimate dhe pricePerMillionCharactersUsd.
• progress dhe createdAt.
• modelVersion, një varg opak i versionit të përpunimit.
• duplicate në përgjigjet e ripërdorura.
• failureCode për punët e dështuara: translation_failed, translation_timeout, input_failed ose worker_lease_lost.

Një punë e dështuar tregon costUsd me vlerë zero.

Një punë e përfunduar ka data.result me sourceLocale (bosh nëse nuk është dhënë gjuhë burimore), targetLocale, fushën e përkthyer text (tekstet e segmenteve të bashkuara me ndërprerje rreshtash), dhe segments. Për tekstin e dërguar përmes këtij API-je, segments përmban një hyrje me fushën e përkthyer text dhe fushën e gjuhës së synuar language. Rezultatet e punëve që presin pagesën mbahen të fshehura deri në shlyerje.

Përdorimi i api.multitel.net

Pika fundore e përputhshmërisë POST https://api.multitel.net/v3/translate pranon të njëjtat fusha JSON dhe të njëjtën fushë të kreut HTTP Idempotency-Key. Nëse kjo fushë mungon, pranon gjithashtu një varg idempotency_key në trupin JSON. Çdo fushë tjetër shtesë refuzohet me 400 unsupported_translation_option. Në këtë host, trupi i papërpunuar mund të jetë deri në 256,000 bajte dhe teksti mbi 20,000 pika kodi kthen 413 translation_too_large në vend të 400. Një source_language bosh trajtohet si i lënë jashtë. Një përgjigje 429 përfshin Retry-After: 15. Ky host kthen edhe këto gabime:

• 400 json_body_required kur trupi mungon, është JSON i pavlefshëm ose një vlerë skalare JSON. Dërgoni një objekt JSON.
• 400 invalid_translation_options kur text, target_language ose engine mungon, është bosh ose nuk është varg, ose source_language nuk është varg.
• 400 invalid_translation_text për tekst të përbërë vetëm nga karaktere të hapësirës së bardhë.
• 400 invalid_translation_engine për një motor të panjohur.
• 400 idempotency_key_required për një çelës që mungon, është bosh ose tepër i gjatë, ose për një idempotency_key që nuk është varg.
• 400 invalid_job për një ID pune me format të pavlefshëm.

Përgjigjet nga shërbimi i përkthimit i këtij hosti përdorin mbështjellësin {"status":{"code":HTTP_STATUS},"response":{...}}, ku status është një objekt. Lexojeni ID-në e punës nga response.id dhe rezultatin e përfunduar nga response.result. Gabimet e vendosin kodin te response.code, pa mesazh ose ID kërkese. Dështimet e autentikimit (401) kthehen nga kontrolli i përgjithshëm i hyrjes së hostit dhe mund të kenë një trup tjetër, prandaj kontrolloni statusin HTTP përpara analizimit të përgjigjes. Punët ndahen me hostin kryesor, por përdorni të njëjtin host për kërkesat periodike, shlyerjen dhe përdorimin, në mënyrë që analizuesi juaj të përputhet me mbështjellësin. Ky host pranon të njëjtat fusha JSON edhe te /v3/translate/estimate pa çelës idempotence dhe vlerësimi i tij është brenda response.