API за превод на текст

Този API превежда текст чрез задачи на опашка, с един целеви език за всяка задача. Подайте текст, запазете върнатия идентификатор на задачата и извличайте задачата, докато обработката приключи. Изпращайте всяка заявка по HTTPS с данните за удостоверяване на профила си — чрез HTTP Basic, както е показано в примерите, или с API токен, както е описано в Удостоверяване. Пазете данните за удостоверяване на сървъра си.

Крайни точки

Двата API хоста, https://api.multi.tel и хостът за съвместимост https://api.multitel.net, споделят едни и същи задачи, ключове за идемпотентност, ограничения и таксуване в рамките на профила. Те се различават по обвивката на отговора, затова използвайте последователно един хост със съответстващ анализатор на отговорите.

На api.multi.tel всеки път е достъпен и с префикса /v1/translate вместо /v3/translate. На api.multitel.net използвайте пътищата /v3/translate.

Отговорът с информация за услугата съдържа enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages и ratesNanosPerCharacter. cpuLanguages изброява кодовете на основните езици, приемани за стандартен превод. ratesNanosPerCharacter дава конфигурираната цена за всяка кодова точка от изходния текст за всеки механизъм, в милиардни части от щатски долар: стойност 5000 означава $5 за милион кодови точки. Отговорът не посочва дали подобреният превод е достъпен в момента; оценка за подобрен превод връща 503, когато той е недостъпен. Прочитането е безплатно.

Превод на текст

Изпратете JSON с Content-Type: application/json към POST https://api.multi.tel/v3/translate. Всяка задача има един целеви език, затова подайте отделна задача за всеки целеви език.

Кодовете на локализация са BCP 47 тагове от 2 до 63 букви, цифри и тирета. Те се канонизират, така че en-us се записва като en-US. Невалидните тагове, както и und, mul или zxx, връщат 400 invalid_translation_language. Наличността на стандартния превод се проверява по основния език, като nb и nn се считат за no. Регионален целеви код като fr-CA се приема и записва, но стандартният резултат следва основния език и не е гарантирано, че отразява региона.

На този хост ограничавайте тялото на заявката до 128 KiB. Изпращайте текста като UTF-8, вместо да екранирате всеки знак извън ASCII като последователност \u, което може да доведе до надвишаване на лимита при заявка с 20,000 знака.

Тялото приема само тези четири полета. Всяко друго свойство се отхвърля с 400 invalid_translation_request, включително idempotency_key, идентификатори на собственици, флагове за безплатна обработка и масиви от сегменти.

Идемпотентност и повторно използване

Всяко подаване изисква хедър Idempotency-Key с дължина от 1 до 190 знака. Използвайте ASCII букви, цифри, -, _, . и :, без начални или крайни интервали; липсващ ключ или ключ от 191 или повече знака се отхвърля с 400. Ключовете са обвързани с профила ви и услугата за превод, за двата хоста и всички данни за удостоверяване на профила.

• Същият ключ със същия текст, канонизирани езици и механизъм връща съществуващата задача с HTTP 200 и duplicate: true, без нова такса.
• Същият ключ с различен текст, езици или механизъм връща 409 idempotency_conflict. Същият ключ връща 409 и ако версията на обработката е променена след създаването на задачата. В такъв случай прочетете първоначалната задача по идентификатора ѝ, вместо да я подавате отново.
• Нов ключ със същия текст, канонизирани езици и механизъм връща съществуващата задача с HTTP 200 и duplicate: true, без нова такса за обработка, ако задача с това съдържание и текущата версия на обработката е на опашка, изпълнява се, завършена е или очаква плащане. Повторно използвана задача, която очаква плащане, все още трябва да бъде платена. Неуспешни задачи не се използват повторно: създава се нова задача, която се таксува при завършване.

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'

Нова задача връща HTTP 202. Примерният текст има 57 кодови точки, затова при $5 за милион кодови точки цената му е $0.000285. Съкратен отговор (идентификаторът е примерен):

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

Подаването може да върне и 402 insufficient_balance, когато предплатеното салдо не покрива задачата заедно с останалите ви неприключени задачи, и 429 translation_queue_full, когато профилът ви или услугата има твърде много неприключени задачи. Връща 503 в следните случаи:

• paid_translation_not_enabled, докато платеният превод е изключен.
• translation_unavailable за заявка за подобрен превод, когато подобреният превод е недостъпен.
• translation_pricing_unavailable, когато за избрания механизъм няма конфигурирана тарифа.

Повторете заявките с отговори 429 и 503 по-късно със същия ключ.

Избор на качество

Дългият текст се обработва на по-малки части, които след това се съединяват. Новите редове и интервалите може да се променят, а изречение може да загуби контекст на границата между обработваните части. Запазете оригиналния текст и прегледайте съединения резултат. Стандартният превод използва основния език на регионалния таг; приемането и записването на таг не гарантира регионална формулировка.

Стандартният превод се изпълнява от CPU обработващи процеси. Подобреният превод изпраща текста към конфигурираната външна AI услуга. Резултатът му също изисква преглед; услугата не гарантира, че единият механизъм е по-точен за всяка езикова двойка или вид текст.

Стандартният превод е чернова, чието качество и време за обработка варират според езиковата двойка. Подобреният превод е предназначен за текст, при който контекстът е важен, но все пак изисква проверка на важни имена, числа, отрицания и ангажименти. Нито една опция не поправя грешки, които вече присъстват в първоначалната транскрипция, затова запазете оригинала за сравнение.

Използвайте GET /v3/translate на същия API хост, за да проверите текущата наличност, поддържаните езици за стандартен превод и конфигурираните тарифи. Стандартна заявка, чийто изходен или целеви основен език не е в cpuLanguages, връща 422 translation_language_pair_unavailable. Когато source_language е посочено и има същия основен език като целевия, заявката връща 409 translation_same_language, вместо да създаде задача. Подобреният превод се включва отделно: докато е недостъпен, подаването на задачи и оценките за подобрен превод връщат 503.

Първо направете оценка

На api.multi.tel изпратете същото JSON тяло към POST /v3/translate/estimate. Не е необходим ключ за идемпотентност. Оценката прилага същата валидация, включително проверките за 422 и 409, но не създава задача, не превежда текст, не резервира средства, не проверява салдото ви и не таксува профила ви. Връща HTTP 200 с estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd и costUsd в data. За примера по-горе costUsd е 0.000285000 при стандартната тарифа. Когато подобреният превод е недостъпен, оценката за подобрен превод връща 503 service_unavailable. Оценките използват текущата конфигурирана тарифа. Тарифата на задачата се фиксира при създаването ѝ и таксата използва тази тарифа.

Извличане на превода

Ново подаване връща HTTP 202, а съществуваща или повторно използвана задача връща HTTP 200. Запазете data.id и използвайте общия работен процес за задачи. Обектът на задачата съдържа следните полета:

• id, status, engine, sourceLocale и targetLocale.
• sourceCharacters, costUsd, costIsEstimate и pricePerMillionCharactersUsd.
• progress и createdAt.
• modelVersion, непрозрачен низ за версията на обработката.
• duplicate при отговори за повторно използвани задачи.
• failureCode за неуспешни задачи: translation_failed, translation_timeout, input_failed или worker_lease_lost.

Неуспешна задача показва costUsd със стойност нула.

Завършена задача има data.result с sourceLocale (празно, ако не е посочен изходен език), targetLocale, преведения text (текстовете на сегментите, съединени с нови редове), и segments. За текст, подаден чрез този API, segments съдържа един запис с преведения text и целевия language. Резултатите от задачи, които очакват плащане, се задържат до плащането.

Използване на api.multitel.net

Крайната точка за съвместимост POST https://api.multitel.net/v3/translate приема същите JSON полета и същия хедър Idempotency-Key. Ако хедърът липсва, приема и низ idempotency_key в JSON тялото. Всяко друго допълнително поле се отхвърля с 400 unsupported_translation_option. На този хост необработеното тяло може да е до 256,000 байта, а текст над 20,000 кодови точки връща 413 translation_too_large вместо 400. Празно source_language се приема за пропуснато. Отговор 429 включва Retry-After: 15. Този хост връща и следните грешки:

• 400 json_body_required, когато тялото липсва, е невалиден JSON или е JSON скаларна стойност. Изпратете JSON обект.
• 400 invalid_translation_options, когато text, target_language или engine липсва, е празно или не е низ, или source_language не е низ.
• 400 invalid_translation_text за текст само от празни знаци.
• 400 invalid_translation_engine за непознат механизъм.
• 400 idempotency_key_required за липсващ, празен или прекалено дълъг ключ или за idempotency_key, което не е низ.
• 400 invalid_job за неправилно оформен идентификатор на задача.

Отговорите от услугата за превод на този хост използват обвивката {"status":{"code":HTTP_STATUS},"response":{...}}, където status е обект. Прочетете идентификатора на задачата от response.id и завършения резултат от response.result. При грешки кодът се поставя в response.code, без съобщение или идентификатор на заявката. Неуспешното удостоверяване (401) се връща от общата проверка за вход на хоста и може да има различно тяло, затова проверявайте HTTP статуса преди анализа на отговора. Задачите са споделени с основния хост, но използвайте един и същ хост за периодично извличане, плащане и потребление, за да съответства анализаторът ви на обвивката. Този хост приема същите JSON полета и на /v3/translate/estimate без ключ за идемпотентност, а оценката му е в response.