API-K Агрегатор - доступ к API реесторв и сервисов

Введение

Эндпоинт POST /api/translate является частью AI Translate API и предоставляет программный доступ к мощному сервису машинного перевода. Он предназначен для автоматического перевода одного или нескольких текстовых фрагментов с поддержкой 75 языков. Эндпоинт использует современные модели искусственного интеллекта для обеспечения высококачественного и быстрого перевода.

Основные возможности: * Пакетный перевод: За один запрос можно передать массив текстов для перевода. * Автоопределение языка: Исходный язык текста определяется автоматически. * Широкоязыковая поддержка: Перевод между 75 языками.

Эндпоинт возвращает ответ в формате JSON.

Детали запроса

HTTP-метод: POST URL: https://api-k.ru/api/translate

Заголовки (Headers)

Заголовок	Значение	Обязательный	Описание
`Content-Type`	`application/json`	Да	Указывает, что тело запроса передается в формате JSON.
`X-API-Key`	Ваш API-ключ	Да	Используется для аутентификации и авторизации. Ключ можно получить в личном кабинете разработчика.

Параметры тела запроса (Body Parameters)

Тело запроса должно быть объектом в формате JSON.

Параметр	Тип	Обязательный	По умолчанию	Описание
`texts`	Массив строк	Да	-	Массив строк, которые требуется перевести. Максимальное количество элементов и общая длина текста ограничены (см. раздел “Ограничения и лимиты”).
`targetLanguageCode`	Строка	Да	`"en"`	Язык, на который необходимо перевести текст. Должен быть передан в формате ISO 639-1 (например, `"en"` для английского, `"es"` для испанского, `"zh"` для китайского). Полный список поддерживаемых языков доступен в отдельной документации.

Детали ответа

Успешный ответ (HTTP Status 200 OK)

В случае успешного выполнения запроса сервер возвращает объект JSON с массивом translations. Порядок элементов в массиве ответа строго соответствует порядку текстов в массиве texts исходного запроса.

Структура ответа:

{
  "translations": [
    {
      "text": "Переведенный текст 1",
      "detectedLanguageCode": "ru"
    },
    {
      "text": "Переведенный текст 2",
      "detectedLanguageCode": "ru"
    }
  ]
}

translations[]: Массив объектов с результатами перевода.
- text: Строка, содержащая переведенный текст.
- detectedLanguageCode: Строка, содержащая код языка (ISO 639-1), который был автоматически определен для исходного текста.

Примечание: В предоставленном примере “Пустой ответ” содержится тот же текст, что и в успешном. Вероятно, имеется в виду ответ на запрос с пустым массивом texts. В таком случае логично ожидать ответ с пустым массивом translations: {"translations": []}.

Обработка ошибок (HTTP Status 4xx/5xx)

В случае ошибки сервер возвращает объект JSON с деталями проблемы.

Структура ответа об ошибке:

{
  "error": {
    "code": 404,
    "message": "Данные не найдены"
  },
  "status": "error"
}

error: Объект, описывающий ошибку.
- code: Числовой код ошибки (совпадает с HTTP статусом).
- message: Человекочитаемое сообщение, объясняющее причину ошибки.
status: Строка "error", указывающая на статус выполнения запроса.

Распространенные коды ошибок: * 400 Bad Request: Неверный формат запроса (например, невалидный JSON, отсутствует обязательный параметр texts). * 401 Unauthorized: Не предоставлен или неверный API-ключ (заголовок X-API-Key). * 404 Not Found: Указанный ресурс (эндпоинт) не найден. Может также означать, что запрошенный targetLanguageCode не поддерживается. * 429 Too Many Requests: Превышено допустимое количество запросов в единицу времени (лимит Rate Limiting). * 500 Internal Server Error: Внутренняя ошибка сервера.

Примеры использования

Пример 1: Базовый запрос с использованием cURL

curl -X POST "https://api-k.ru/api/translate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-api-key-here" \
  -d '{
    "texts": ["Привет, мир!", "Как дела?"],
    "targetLanguageCode": "en"
  }'

Ожидаемый ответ:

{
  "translations": [
    {
      "text": "Hello, World!",
      "detectedLanguageCode": "ru"
    },
    {
      "text": "How are you?",
      "detectedLanguageCode": "ru"
    }
  ]
}

Пример 2: Запрос на JavaScript (Fetch API)

const url = 'https://api-k.ru/api/translate';
const apiKey = 'your-secret-api-key-here';
const requestBody = {
  texts: ['Добро пожаловать в наш сервис.', 'Мы рады вас видеть.'],
  targetLanguageCode: 'es' // Перевод на испанский
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey
  },
  body: JSON.stringify(requestBody)
})
.then(response => {
  if (!response.ok) {
    throw new Error(`Ошибка HTTP: ${response.status}`);
  }
  return response.json();
})
.then(data => {
  console.log('Переводы:', data.translations);
  data.translations.forEach((translation, index) => {
    console.log(`Оригинал (${translation.detectedLanguageCode}): ${requestBody.texts[index]}`);
    console.log(`Перевод (${requestBody.targetLanguageCode}): ${translation.text}`);
  });
})
.catch(error => console.error('Ошибка:', error));

Best Practices (Рекомендации по использованию)

Обработка ошибок: Всегда реализуйте обработку ошибок на стороне клиента. Проверяйте HTTP-статус ответа и анализируйте объект ошибки для корректного информирования пользователя.
Пакетная обработка: Для перевода большого количества небольших текстов используйте возможность передавать массив в параметре texts. Это эффективнее, чем отправлять множество отдельных запросов, и помогает не превысить лимиты по RPS (запросам в секунду).
Кэширование: Если приложение часто переводит одни и те же фразы, рассмотрите возможность кэширования результатов на своей стороне, чтобы уменьшить количество запросов к API и снизить задержку.
Подготовка текста: Убедитесь, что передаваемый текст не содержит лишних пробелов, специальных символов (если они не требуются) и имеет корректную кодировку (UTF-8).
Безопасность ключа: Никогда не храните и не передавайте ваш X-API-Key на фронтенде (в коде, доступном пользователям). Используйте ключ только в защищенной серверной среде.

Ограничения и лимиты

Для обеспечения стабильной работы сервиса действуют следующие ограничения:

Rate Limiting: Количество запросов к API в минуту ограничено для каждого API-ключа. “`

Техническая документация: : REST API Эндпоинт `/api/translate`