API za prevođenje teksta

Ovaj API prevodi tekst kao zadatke u redu za obradu, s jednim ciljnim jezikom po zadatku. Pošaljite tekst, sačuvajte vraćeni ID zadatka i dohvaćajte zadatak dok obrada ne završi. Svaki zahtjev šaljite putem HTTPS-a s vjerodajnicama svojeg računa: vjerodajnicama za HTTP Basic kao u primjerima ili API tokenom, kako je opisano u odjeljku Autentifikacija. Vjerodajnice čuvajte na svojem poslužitelju.

Krajnje točke

Dva API poslužitelja, https://api.multi.tel i poslužitelj za kompatibilnost https://api.multitel.net, dijele iste zadatke, ključeve idempotentnosti, ograničenja i naplatu unutar računa. Razlikuju se po omotnici odgovora, pa dosljedno koristite jedan poslužitelj s odgovarajućim parserom.

Na poslužitelju api.multi.tel svaka je putanja dostupna i s prefiksom /v1/translate umjesto /v3/translate. Na poslužitelju api.multitel.net koristite putanje /v3/translate.

Odgovor s informacijama o usluzi navodi enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages i ratesNanosPerCharacter. cpuLanguages navodi kodove osnovnih jezika prihvaćenih za standardni prijevod. ratesNanosPerCharacter navodi postavljenu cijenu po kodnoj točki izvornog teksta za svaki mehanizam, u milijarditim dijelovima američkog dolara: vrijednost 5000 znači $5 po milijunu kodnih točaka. Odgovor ne navodi je li poboljšani prijevod trenutačno dostupan; procjena za poboljšani prijevod vraća 503 kada nije dostupan. Dohvat je besplatan.

Prevođenje teksta

Pošaljite JSON sa zaglavljem Content-Type: application/json na POST https://api.multi.tel/v3/translate. Svaki zadatak ima jedan ciljni jezik, pa pošaljite zaseban zadatak za svaki ciljni jezik.

Jezično-regionalni kodovi su BCP 47 oznake duljine od 2 do 63 znaka, sastavljene od slova, znamenki i spojnica. Pretvaraju se u kanonski oblik, pa se en-us bilježi kao en-US. Nevaljane oznake, kao i und, mul ili zxx, vraćaju 400 invalid_translation_language. Dostupnost standardnog prijevoda provjerava se prema osnovnom jeziku, a nb i nn računaju se kao no. Regionalni ciljni kod poput fr-CA prihvaća se i bilježi, ali standardni rezultat slijedi osnovni jezik i nije zajamčeno da će odražavati regiju.

Na ovom poslužitelju ograničite tijelo zahtjeva na 128 KiB. Šaljite tekst u kodiranju UTF-8 umjesto da svaki znak izvan skupa ASCII zapišete kao slijed \u, što zahtjev s 20,000 znakova može dovesti iznad ograničenja.

Tijelo prihvaća samo ova četiri polja. Svako drugo svojstvo odbija se uz 400 invalid_translation_request, uključujući idempotency_key, ID-jeve vlasnika, oznake za besplatnu obradu i nizove segmenata.

Idempotentnost i ponovna upotreba

Za svako slanje potrebno je zaglavlje Idempotency-Key duljine od 1 do 190 znakova. Koristite ASCII slova, znamenke, -, _, . i :, bez početnih ili završnih razmaka; ključ koji nedostaje ili ima 191 ili više znakova odbija se uz 400. Ključevi su ograničeni na vaš račun i uslugu prevođenja, na oba poslužitelja i za sve vjerodajnice vašeg računa.

• Isti ključ s istim tekstom, kanonskim jezicima i mehanizmom vraća postojeći zadatak uz HTTP 200 i duplicate: true, bez ponovne naplate.
• Isti ključ s drukčijim tekstom, jezicima ili mehanizmom vraća 409 idempotency_conflict. Isti ključ vraća 409 i ako se verzija obrade promijenila od stvaranja njegova zadatka. U tom slučaju dohvatite izvorni zadatak prema njegovu ID-ju umjesto ponovnog slanja.
• Novi ključ s istim tekstom, kanonskim jezicima i mehanizmom vraća postojeći zadatak uz HTTP 200 i duplicate: true, bez nove naplate obrade, ako je zadatak s tim sadržajem i trenutačnom verzijom obrade u redu za obradu, izvršava se, dovršen je ili čeka plaćanje. Ponovno upotrijebljen zadatak koji čeka plaćanje i dalje zahtijeva podmirivanje. Neuspješni zadaci ne koriste se ponovno: stvara se novi zadatak koji se naplaćuje kada završi.

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'

Novi zadatak vraća HTTP 202. Primjer teksta ima 57 kodnih točaka, pa uz cijenu od $5 po milijunu kodnih točaka košta $0.000285. Skraćeni odgovor (identifikator služi kao primjer):

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

Slanje može vratiti i 402 insufficient_balance kada unaprijed plaćeno stanje ne može pokriti zadatak zajedno s vašim ostalim nedovršenim zadacima te 429 translation_queue_full kada vaš račun ili usluga ima previše nedovršenih zadataka. Vraća 503 u sljedećim slučajevima:

• paid_translation_not_enabled dok je prijevod koji se naplaćuje onemogućen.
• translation_unavailable za zahtjev za poboljšani prijevod dok poboljšani prijevod nije dostupan.
• translation_pricing_unavailable dok odabrani mehanizam nema postavljenu cijenu.

Za odgovore 429 i 503 pokušajte ponovno kasnije s istim ključem.

Odabir kvalitete

Dugi tekst obrađuje se u manjim dijelovima i ponovno spaja. Prijelomi redaka i razmaci mogu se promijeniti, a rečenica može izgubiti kontekst na granici između dijelova obrade. Sačuvajte izvorni tekst i provjerite spojeni rezultat. Standardni prijevod koristi osnovni jezik regionalne oznake; prihvaćanje i bilježenje oznake ne jamči regionalne formulacije.

Standardni prijevod izvršava se na CPU radnim procesima. Poboljšani prijevod šalje tekst postavljenoj vanjskoj AI usluzi. Njegov rezultat i dalje treba provjeriti; usluga ne jamči da je jedan mehanizam točniji za svaki jezični par ili vrstu teksta.

Standardni prijevod nacrt je čija kvaliteta i vrijeme obrade ovise o jezičnom paru. Poboljšani prijevod namijenjen je tekstu u kojem je kontekst važan, ali i dalje zahtijeva provjeru važnih imena, brojeva, negacija i obveza. Nijedna opcija ne ispravlja pogreške koje su već prisutne u izvornom transkriptu, pa sačuvajte izvornik radi usporedbe.

Koristite GET /v3/translate na istom API poslužitelju kako biste provjerili trenutačnu dostupnost, podržane jezike za standardni prijevod i postavljene cijene. Standardni zahtjev čiji izvorni ili ciljni osnovni jezik nije na popisu cpuLanguages vraća 422 translation_language_pair_unavailable. Kada je source_language naveden i ima isti osnovni jezik kao ciljni jezik, zahtjev vraća 409 translation_same_language umjesto stvaranja zadatka. Poboljšani prijevod omogućuje se zasebno: dok je nedostupan, slanja zadataka i procjene za poboljšani prijevod vraćaju 503.

Najprije zatražite procjenu

Na poslužitelju api.multi.tel pošaljite isto JSON tijelo na POST /v3/translate/estimate. Ključ idempotentnosti nije potreban. Procjena primjenjuje istu provjeru valjanosti, uključujući provjere za 422 i 409, ali ne stvara zadatak, ne prevodi tekst, ne rezervira sredstva, ne provjerava vaše stanje i ne tereti vaš račun. Vraća HTTP 200 s poljima estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd i costUsd unutar objekta data. Za prethodni primjer, costUsd je 0.000285000 po standardnoj cijeni. Dok poboljšani prijevod nije dostupan, procjena za poboljšani prijevod vraća 503 service_unavailable. Procjene koriste trenutačno postavljenu cijenu. Cijena zadatka utvrđuje se pri stvaranju zadatka i ta se cijena koristi za njegovu naplatu.

Dohvat prijevoda

Novo slanje vraća HTTP 202, a postojeći ili ponovno upotrijebljen zadatak vraća HTTP 200. Sačuvajte data.id i slijedite zajednički tijek rada sa zadacima. Objekt zadatka sadrži ova polja:

• id, status, engine, sourceLocale i targetLocale.
• sourceCharacters, costUsd, costIsEstimate i pricePerMillionCharactersUsd.
• progress i createdAt.
• modelVersion, neproziran niz znakova koji označava verziju obrade.
• duplicate u odgovorima za ponovno upotrijebljene zadatke.
• failureCode za neuspješne zadatke: translation_failed, translation_timeout, input_failed ili worker_lease_lost.

Neuspješan zadatak prikazuje costUsd s vrijednošću nula.

Dovršeni zadatak ima data.result koji sadrži sourceLocale (prazno ako izvorni jezik nije naveden), targetLocale, prevedeni text (tekstovi segmenata spojeni prijelomima redaka) i segments. Za tekst poslan putem ovog API-ja, segments sadrži jedan unos s prevedenim poljem text i ciljnim poljem language. Rezultati zadataka koji čekaju plaćanje zadržavaju se do podmirivanja.

Korištenje poslužitelja api.multitel.net

Krajnja točka za kompatibilnost POST https://api.multitel.net/v3/translate prihvaća ista JSON polja i isto zaglavlje Idempotency-Key. Ako zaglavlje nedostaje, prihvaća i niz znakova idempotency_key u JSON tijelu. Svako drugo dodatno polje odbija se uz 400 unsupported_translation_option. Na ovom poslužitelju sirovo tijelo može imati najviše 256,000 bajtova, a tekst s više od 20,000 kodnih točaka vraća 413 translation_too_large umjesto 400. Prazno polje source_language smatra se izostavljenim. Odgovor 429 uključuje Retry-After: 15. Ovaj poslužitelj vraća i sljedeće pogreške:

• 400 json_body_required kada tijelo nedostaje, nije valjan JSON ili je JSON skalarna vrijednost. Pošaljite JSON objekt.
• 400 invalid_translation_options kada text, target_language ili engine nedostaje, prazno je ili nije niz znakova, ili source_language nije niz znakova.
• 400 invalid_translation_text za tekst koji sadrži samo bjeline.
• 400 invalid_translation_engine za nepoznat mehanizam.
• 400 idempotency_key_required za ključ koji nedostaje, prazan je ili predugačak, ili za idempotency_key koji nije niz znakova.
• 400 invalid_job za neispravno oblikovan ID zadatka.

Odgovori usluge prevođenja s ovog poslužitelja koriste omotnicu {"status":{"code":HTTP_STATUS},"response":{...}}, u kojoj je status objekt. ID zadatka pročitajte iz response.id i dovršeni rezultat iz response.result. U slučaju pogreške kod se nalazi u response.code, bez poruke ili ID-ja zahtjeva. Neuspjelu autentifikaciju (401) vraća opća provjera prijave na poslužitelju i tijelo odgovora može biti drukčije, pa provjerite HTTP status prije parsiranja. Zadaci se dijele s primarnim poslužiteljem, ali koristite isti poslužitelj za periodični dohvat, podmirivanje i potrošnju kako bi vaš parser odgovarao omotnici. Ovaj poslužitelj prihvaća ista JSON polja i na /v3/translate/estimate bez ključa idempotentnosti, a procjena je unutar objekta response.