Початок роботи

Використовуйте PolyLingo HTTP API для перекладу простого тексту, Markdown, JSON або HTML, зберігаючи структуру без змін. Цей посібник охоплює робочий кінцевий пункт, автентифікацію та ваш перший успішний запит.

Базовий URL

Усі приклади використовують робочий API:

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

Кожен шлях нижче відноситься до цієї бази (наприклад, POST /translate означає POST https://api.usepolylingo.com/v1/translate).

Якщо ви запускаєте власний екземпляр PolyLingo API, замініть хост на URL вашого розгортання і збережіть префікс /v1, якщо ви не налаштували інакше.

Автентифікація

Захищені кінцеві точки очікують ваш API ключ у заголовку Authorization:

Authorization: Bearer <your_api_key>

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

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

Якщо заголовок відсутній, неправильний або ключ недійсний чи відкликаний, API відповідає 401 та error: "invalid_api_key".

Кінцеві точки та ключі

Ключ не потрібен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

Для перевірки стану ключ не потрібен:

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

Ви побачите невеликий JSON, що вказує на те, що сервіс працює. Використовуйте GET /languages для списку кодів, які можна передавати як targets.

CORS та браузерні додатки

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

Для односторінкового додатку звичайна схема: ваш фронтенд спілкується з вашим бекендом, а бекенд викликає PolyLingo з API ключем.

Наступні кроки

  • API reference — форми запитів і відповідей, формати, помилки та обмеження.
Початок роботи | PolyLingo | PolyLingo