API перекладу тексту

Цей API перекладає текст як завдання в черзі, з однією цільовою мовою на завдання. Надішліть текст, збережіть повернений ID завдання й запитуйте завдання, доки обробку не буде завершено. Надсилайте всі запити через 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, ID власників, прапорці безкоштовної обробки та масиви сегментів.

Ідемпотентність і повторне використання

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

• Той самий ключ із тим самим текстом, канонізованими мовами та рушієм повертає наявне завдання з HTTP 200 і duplicate: true без повторної плати.
• Той самий ключ з іншим текстом, мовами або рушієм повертає 409 idempotency_conflict. Той самий ключ також повертає 409, якщо версія обробки змінилася після створення завдання. У такому разі отримайте початкове завдання за його ID замість повторного надсилання.
• Новий ключ із тим самим текстом, канонізованими мовами та рушієм повертає наявне завдання з 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. Покращений переклад надсилає текст до налаштованого зовнішнього сервісу ШІ. Його результат усе одно потребує перевірки; сервіс не гарантує, що один рушій точніший для кожної мовної пари чи типу тексту.

Стандартний переклад — це чернетка, якість і час обробки якої залежать від мовної пари. Покращений переклад призначений для тексту, де важливий контекст, але все одно потрібно перевіряти важливі імена, числа, заперечення та зобов’язання. Жоден варіант не виправляє помилок, уже наявних у початковій транскрипції, тому збережіть оригінал для порівняння.

Використовуйте 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, якщо ID завдання має неправильний формат.

Відповіді сервісу перекладу на цьому сервері використовують обгортку {"status":{"code":HTTP_STATUS},"response":{...}}, де status є об’єктом. Прочитайте ID завдання з response.id, а завершений результат — з response.result. У разі помилки код міститься в response.code без повідомлення чи ID запиту. Помилки автентифікації (401) повертає загальна перевірка входу сервера, і вони можуть мати інше тіло, тому перевіряйте статус HTTP перед розбором. Завдання спільні з основним сервером, але для періодичного опитування, оплати та використання застосовуйте той самий сервер, щоб парсер відповідав обгортці. Цей сервер також приймає ті самі поля JSON за шляхом /v3/translate/estimate без ключа ідемпотентності, а оцінка міститься в response.