Yandex Translate API API

Отрасль: AI и нейросети. Актуально на 2026-10-24.

API машинного перевода Yandex Translate (Yandex Cloud / AI Studio): перевод текста и HTML с автоматическим определением исходного языка, глоссарии и пользовательские модели, проверка орфографии, определение языка текста и список поддерживаемых языков. Запросы и ответы — JSON.

Сценарии

Перевести тексты на нужный язык

Перевод описаний товаров, сообщений поддержки, интерфейса — пачкой строк за один запрос.

  1. Создай сервисный аккаунт и API-ключ; передавай его в заголовке Authorization: Api-Key <ключ>. С пользовательским IAM-токеном нужно ещё передавать folderId в теле.
  2. Отправь тексты: POST /translate/v2/translate с targetLanguageCode (например, en) и texts — массивом строк, суммарно до 10 000 символов.
  3. Исходный язык определится автоматически; в ответе для каждой строки — text (перевод) и detectedLanguageCode.
  4. Лимит — 20 вызовов в секунду и 1 млн символов в час: большие объёмы разбивай на пачки.
curl -X POST https://translate.api.cloud.yandex.net/translate/v2/translate \
  -H "Authorization: Api-Key $YANDEX_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"targetLanguageCode": "en", "texts": ["Кружка керамическая, 330 мл", "Можно мыть в посудомоечной машине"]}'

Перевести HTML с терминами из глоссария

Перевод страниц и писем с разметкой, где названия продуктов и термины должны переводиться одинаково.

  1. Отправь запрос: POST /translate/v2/translate с format = HTML — разметка сохранится, переведётся только текст.
  2. Для глоссария обязательно укажи sourceLanguageCode и передай glossaryConfig.glossaryData.glossaryPairs — до 50 пар sourceText и translatedText (до 20 000 символов).
  3. Чтобы термин переводился ровно как в глоссарии, поставь exact = true.
curl -X POST https://translate.api.cloud.yandex.net/translate/v2/translate \
  -H "Authorization: Api-Key $YANDEX_API_KEY" -H 'Content-Type: application/json' \
  -d '{
        "sourceLanguageCode": "ru",
        "targetLanguageCode": "en",
        "format": "HTML",
        "texts": ["<p>Оформите <b>Подписку Плюс</b> и получайте бесплатную доставку.</p>"],
        "glossaryConfig": {"glossaryData": {"glossaryPairs": [{"sourceText": "Подписка Плюс", "translatedText": "Plus Membership", "exact": true}]}}
      }'

Определить язык текста

Направить обращение нужной команде поддержки или выбрать язык ответа бота.

  1. Отправь текст: POST /translate/v2/detect с text (до 1000 символов). Если знаешь вероятные языки, передай их в languageCodeHints — определение станет точнее.
  2. В ответе languageCode — код языка, в основном ISO 639-1.
  3. Список всех поддерживаемых языков — POST /translate/v2/languages; названия языков в нём на английском.
curl -X POST https://translate.api.cloud.yandex.net/translate/v2/detect \
  -H "Authorization: Api-Key $YANDEX_API_KEY" -H 'Content-Type: application/json' \
  -d '{"text": "Сәлеметсіз бе, тапсырысым қайда?", "languageCodeHints": ["kk", "ru"]}'

Базовые URL

Авторизация

Тип: Bearer-токен

Пользовательский аккаунт авторизуется только IAM-токеном и обязательно передаёт folderId в теле запроса; для сервисного аккаунта folderId не указывается.

Методы

POST /translate/v2/translate — Перевод текста

Пример тела:

В ответе — массив translations: text (перевод) и detectedLanguageCode (язык исходного текста).

Параметр Где Тип Обяз. Описание
targetLanguageCode body string да Язык перевода, до 3 символов (обычно ISO 639-1)
texts body array да Строки для перевода, суммарно до 10 000 символов
sourceLanguageCode body string нет Язык исходного текста; нужен для перевода с глоссарием
format body string нет PLAIN_TEXT (по умолчанию) или HTML
folderId body string нет ID каталога; обязателен для пользовательского аккаунта
model body string нет ID пользовательской модели
glossaryConfig.glossaryData.glossaryPairs body array нет Пары глоссария: от 1 до 50
glossaryConfig.glossaryData.glossaryPairs[].sourceText body string да Текст на исходном языке
glossaryConfig.glossaryData.glossaryPairs[].translatedText body string да Текст на целевом языке
glossaryConfig.glossaryData.glossaryPairs[].exact body boolean нет Точный перевод термина (нейроглоссарий)
speller body boolean нет Проверка орфографии

Пример запроса:

{
    "folderId": "<идентификатор_каталога>",
    "texts": ["Hello", "World"],
    "targetLanguageCode": "ru"
}

Пример ответа:

export API_KEY=<API-ключ>
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Api-Key ${API_KEY}" \
  --data '@body.json' \
  "https://translate.api.cloud.yandex.net/translate/v2/translate"

POST /translate/v2/detect — Определение языка

В ответе — languageCode.

Параметр Где Тип Обяз. Описание
text body string да Текст, до 1000 символов
languageCodeHints body array нет Наиболее вероятные языки, до 10 кодов
folderId body string нет ID каталога (для пользовательского аккаунта)

POST /translate/v2/languages — Список поддерживаемых языков

Параметр Где Тип Обяз. Описание
folderId body string нет ID каталога (для пользовательского аккаунта)

Пример ответа:

{"languages": [{"code": "string", "name": "string"}]}

Нюансы

Ошибки

Код Описание
400 Некорректные параметры запроса
401 Нужна аутентификация
403 Недостаточно прав
429 Превышена квота запросов
500 Внутренняя ошибка
503 Сервис временно недоступен

Ограничения

Источники

Если этого недостаточно — официальная документация: https://aistudio.yandex.ru/ru/docs/translate/ JSON: https://mcp-everything.ru/api/integrations/yandex-translate. MCP: https://mcp-everything.ru/mcp