---
slug: "yandex-translate"
name: "Yandex Translate API"
vendor: "Яндекс"
industry: "ai"
docsUrl: "https://aistudio.yandex.ru/ru/docs/translate/"
version: 2
updatedAt: "2026-10-24"
---

# Yandex Translate 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 млн символов в час: большие объёмы разбивай на пачки.

```bash
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.

```bash
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; названия языков в нём на английском.

```bash
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

- Боевой: `https://translate.api.cloud.yandex.net`

## Авторизация

Тип: Bearer-токен

- IAM-токен (пользовательский или сервисный аккаунт): `Authorization: Bearer <IAM-токен>`
- API-ключ (сервисный аккаунт): `Authorization: Api-Key <API-ключ>`

Пользовательский аккаунт авторизуется только 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"
}
```

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

```json
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 каталога (для пользовательского аккаунта) |

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

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

## Нюансы

- Если `sourceLanguageCode` не передан, исходный язык определяется автоматически.
- Глоссарий передаётся только в теле запроса (`glossaryData`): до 50 пар и до 20 000 символов Unicode.
- Коды языков в основном ISO 639-1, но формат этим не ограничен; названия языков — на английском.

## Ошибки

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

## Ограничения

- 20 вызовов одного метода API в секунду.
- 1 млн символов на перевод или определение языка в час.
- Глоссарий: до 50 пар, до 20 000 символов.

## Источники

- [Translate — метод translate](https://aistudio.yandex.ru/ru/docs/translate/api-ref/Translation/translate)
- [Translate — метод detectLanguage](https://aistudio.yandex.ru/ru/docs/translate/api-ref/Translation/detectLanguage)
- [Translate — метод listLanguages](https://aistudio.yandex.ru/ru/docs/translate/api-ref/Translation/listLanguages)
- [Перевод текста](https://aistudio.yandex.ru/ru/docs/translate/operations/translate)
- [Квоты и лимиты](https://aistudio.yandex.ru/ru/docs/ai-studio/concepts/limits)
- [Обработка ошибок в API Yandex Cloud](https://yandex.cloud/ru/docs/api-design-guide/concepts/errors)

---

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