Создайте с помощью 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 объект и может включать в себя 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);

Питон

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);

Дротик / Флаттер

Не отправляйте ключ Wordly внутри приложения Flutter. Пример относится к доверенному серверу Dart или функции сервера.

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']);
}

Контрольный список производства

• Прокси-запросы Wordly через доверенный сервер.
• Установите таймауты соединения и ответа.
• Ручка 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.