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.