Створення за допомогою Wordly API.

Швидкий старт

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

1. 1
   Створіть обліковий запис

   Зареєструйтесь, використовуючи лише адресу електронної пошти та пароль.

2. 2
   Підтвердьте свою електронну адресу

   Введіть надісланий код [email protected]. Перевірка надає 50 безкоштовних кредитів.

3. 3
   Зберігайте свій ключ API

   Скопіюйте створене wly_live_... ключ і зберігайте його у змінній середовища на стороні сервера.

4. 4
   Зробіть тестовий запит

   Зателефонуйте до кінцевої точки облікового запису, щоб перевірити автентифікацію та переглянути залишок балансу.

curl "https://api.wordlyenglish.com/v1/account" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept: application/json"

{
  "data": {
    "message": "Authenticated",
    "credits_remaining": 50
  },
  "meta": { "lang": "en" }
}

Базова URL-адреса та версії

Усі робочі кінцеві точки обслуговуються з такої версії базової URL-адреси:

Порушення відповіді або зміни поведінки використовуватиме нову версію шляху. Додаткові поля можуть бути введені всередині v1, тому клієнти повинні ігнорувати властивості відповіді, які вони не розпізнають.

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

Для автентифікованих кінцевих точок потрібен ключ API у HTTP Authorization заголовок за схемою Bearer.

Authorization: Bearer wly_live_your_api_key

Локалізовані повідомлення API

Установіть мову відповіді за допомогою ?lang=tr або стандарт Accept-Language заголовок. Параметри запиту мають пріоритет. Кожна відповідь JSON оголошує вибрану мову Content-Language і meta.lang. Коди помилок залишаються стабільними англійською мовою для програмної обробки; локалізовано лише повідомлення, яке читається людиною.

curl "https://api.wordlyenglish.com/v1/account?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept-Language: tr-TR"

Підтримувані мовні коди: en, tr, de, fr, es, it, pt, nl, pl, ru, uk, ar, fa, he, hi, bn, ur, zh, ja, ko, id, ms, vi, th, sv, no, da, fi, cs, ro.

Кредити та виставлення рахунків

Each successful metered request consumes the documented number of credits. Email-verified accounts receive 50 free credits once. Credits are deducted atomically, so concurrent requests cannot spend the same balance twice. Balance lookup through GET /v1/account is free.

Use GET /v1/account when you need the current balance. Other endpoint responses include the operation charge but omit the remaining balance. When the balance is insufficient, the API returns HTTP 402 і не обробляє операцію.

{
  "error": {
    "code": "credits_exhausted",
    "message": "Your credit balance is exhausted. Add a package or enable pay-as-you-go to continue.",
    "upgrade_url": "/app.php?page=billing"
  }
}

Життєвий цикл ключа API

Створіть окремі ключі для розробки, постановки та виробництва. Wordly зберігає лише криптографічний хеш кожного ключа; повне значення відображається один раз під час створення.

• Назвіть ключі за середовищем або послугою.
• Використовуйте змінні середовища або кероване секретне сховище.
• Негайно анулюйте ключ, якщо він міг бути розкритий.
• Обертайте ключі без повторного використання старих значень.
• Не надсилайте ключі в рядках запиту.

Формат відповіді

Успішні відповіді використовують верхній рівень data об'єкт і може включати a meta об'єкт. Помилки завжди використовують верхній рівень error об'єкт зі стабільним машинозчитуваним code і зрозумілий для людини message.

{
  "data": { ... },
  "meta": {
    "credits_used": 1,
    "request_id": "..."
  }
}

{
  "error": {
    "code": "invalid_api_key",
    "message": "..."
  }
}

Тримайте request_id під час звернення до служби підтримки щодо успішного запиту на оплату. JSON має кодування UTF-8, і клієнти повинні надсилати його Accept: application/json.

Кінцеві точки виробництва

Кінцеві точки словникового запасу

GET /v1/words/{word}

Повертає точний збіг слова. використання languages=tr,de,fr щоб повернути лише запитувані переклади. Каталог або перекладені записи коштують 1 кредит; повністю збагачені профілі коштують 5 кредитів.

curl "https://api.wordlyenglish.com/v1/words/water?languages=tr,de" \
  -H "Authorization: Bearer $WORDLY_API_KEY"

GET /v1/words/search

Пошук за допомогою q і необов'язковий level, part_of_speech, category, limit, і cursor. Ліміти варіюються від 1 до 50. Пас meta.next_cursor у наступний запит.

curl "https://api.wordlyenglish.com/v1/words/search?q=app&level=advanced&limit=20" \
  -H "Authorization: Bearer $WORDLY_API_KEY"

GET /v1/words/random

Повертає 1–20 випадкових слів. Фільтрувати за level, part_of_speech, або category. Кожен повернутий слот коштує один кредит.

POST /v1/words/batch

Шукає від 1 до 50 унікальних слів в одному запиті. Відповідь зберігає порядок запитів і позначає кожен елемент found.

curl -X POST "https://api.wordlyenglish.com/v1/words/batch?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"words":["water","opportunity"],"languages":["tr","de"]}'

GET /v1/languages

Повертає всі 30 підтримуваних локалей інтерфейсу та API-повідомлень. Переклади словника повертаються лише за наявності. Ця кінцева точка є загальнодоступною та не коштує нульових кредитів.

Ліміт тарифу

Кожен ключ API обмежено 120 прийнятими запитами на хвилину. Відповіді включають X-RateLimit-Limit і X-RateLimit-Remaining. А 429 rate_limit_exceeded відповідь включає Retry-After: 60.

Response field reference

Every stable response variable is described below. Additive fields may appear later, so clients should ignore fields they do not recognize.

Vocabulary object

Meta object

Error object

Помилки

Рекомендована політика повторних спроб

Не повторюйте 401, 402, або 404 автоматично. Для тимчасових 5xx відповіді, використовуйте експоненціальне відставання з тремтінням і суворим обмеженням повторних спроб. Ніколи не створюйте необмежений цикл повторних спроб, оскільки кожен прийнятий автентифікований запит може споживати кредити.

JavaScript / Node.js

const response = await fetch('https://api.wordlyenglish.com/v1/account', {
  headers: {
    Authorization: `Bearer ${process.env.WORDLY_API_KEY}`,
    Accept: 'application/json'
  }
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

console.log(body.data.credits_remaining);

Python

import os
import requests

response = requests.get(
    'https://api.wordlyenglish.com/v1/account',
    headers={
        'Authorization': f'Bearer {os.environ["WORDLY_API_KEY"]}',
        'Accept': 'application/json',
    },
    timeout=15,
)
response.raise_for_status()
print(response.json()['data']['credits_remaining'])

PHP

$curl = curl_init('https://api.wordlyenglish.com/v1/account');
curl_setopt_array($curl, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 15,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WORDLY_API_KEY'),
    'Accept: application/json',
  ],
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

if ($status >= 400) {
  throw new RuntimeException('Wordly API request failed');
}
$data = json_decode($body, true, flags: JSON_THROW_ON_ERROR);

Дарт / Флаттер

Не надсилайте ключ Worldly у програму Flutter. Приклад належить до надійної функції Dart backend або сервера.

final response = await http.get(
  Uri.parse('https://api.wordlyenglish.com/v1/account'),
  headers: {
    'Authorization': 'Bearer ${Platform.environment['WORDLY_API_KEY']}',
    'Accept': 'application/json',
  },
);

final body = jsonDecode(response.body) as Map<String, dynamic>;
if (response.statusCode >= 400) {
  throw Exception((body['error'] as Map)['code']);
}

Контрольний лист виробництва

• Проксі-сервер запитує Worldly через надійну серверну частину.
• Встановіть тайм-аути підключення та відповіді.
• Ручка 401, 402, 404, і 5xx окремо.
• Query GET /v1/account when your application needs the current balance.
• Журнал кінцевої точки, статусу, затримки та request_id без реєстрації ключа API.
• Використовуйте окремі ключі для кожного середовища та періодично змінюйте їх.
• Cache stable vocabulary responses in your backend when appropriate.