Начало работы

Используйте HTTP API PolyLingo для перевода простого текста, Markdown, JSON или HTML, сохраняя структуру. Это руководство охватывает рабочий endpoint, аутентификацию и ваш первый успешный запрос.

Базовый URL

Все примеры используют рабочий API:

URL
Рабочийhttps://api.usepolylingo.com/v1

Каждый путь ниже относителен этой базе (например, POST /translate означает POST https://api.usepolylingo.com/v1/translate).

Если вы запускаете собственный экземпляр API PolyLingo, замените хост на URL вашего развертывания и сохраните префикс /v1, если не настроено иначе.

Аутентификация

Защищённые endpoints ожидают ваш API ключ в заголовке Authorization:

Authorization: Bearer <your_api_key>

Получение ключа: Создайте его в приложении PolyLingo в разделе API keys. Полный ключ виден только один раз — сохраните его в безопасном месте (переменная окружения или менеджер секретов). Ключи можно отозвать на той же странице.

Безопасность: Обращайтесь с ключом как с паролем. Предпочитайте вызывать API с вашего сервера, а не из публичного кода браузера, чтобы ключ не был доступен пользователям.

Если заголовок отсутствует, неверен, или ключ недействителен или отозван, API отвечает 401 и error: "invalid_api_key".

Endpoints и ключи

Ключ не требуетсяGET /health — быстрая проверка доступности
GET /languages — поддерживаемые языковые коды
Требуется ключPOST /translate — перевод контента
POST /translate/batch — перевод нескольких элементов
POST /jobs — поставить в очередь долгий перевод (возвращает 202 сразу)
GET /jobs/:id — опрос статуса задачи; включает queue_position во время ожидания
GET /usage — использование для аутентифицированного аккаунта

Первый запрос (cURL)

export POLYLINGO_API_KEY="pl_your_key_here"

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello\n\nThis is **bold**.",
    "format": "markdown",
    "targets": ["es", "fr"],
    "model": "standard"
  }'

Успешный ответ включает объект translations (одна запись на каждый целевой язык) и объект usage с подсчётом токенов.

Первый запрос (Node.js)

Node.js 18+ включает fetch:

const API_KEY = process.env.POLYLINGO_API_KEY
const res = await fetch('https://api.usepolylingo.com/v1/translate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    content: '# Hello\n\n**Bold** text.',
    format: 'markdown',
    targets: ['de', 'ja'],
    model: 'standard',
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error}: ${data.message}`)
console.log(data.translations)

Проверьте доступность API

Ключ не нужен для health:

curl -sS "https://api.usepolylingo.com/v1/health"

Вы увидите небольшой JSON с информацией о работе сервиса. Используйте GET /languages для списка кодов, которые можно передавать как targets.

CORS и браузерные приложения

API может ограничивать, какие браузерные источники могут вызывать его напрямую, чтобы ключи не использовались с ненадёжных сайтов. Вызовы с сервера (Node, Python, edge-функции, ваш бэкенд) не ограничены CORS.

Для одностраничного приложения обычный паттерн: ваш фронтенд общается с вашим бэкендом, а бэкенд вызывает PolyLingo с API ключом.

Следующие шаги

  • Справочник API — формы запросов и ответов, форматы, ошибки и ограничения.
Начало работы | PolyLingo | PolyLingo