Kompiluj za pomocą Wordly API.

Szybki start

Utwórz bezpłatne konto, zweryfikuj swój adres e-mail za pomocą sześciocyfrowego kodu i skopiuj klucz API wyświetlony raz w panelu programisty.

1. 1
   Utwórz konto

   Zarejestruj się, podając jedynie adres e-mail i hasło.

2. 2
   Zweryfikuj swój adres e-mail

   Wpisz kod przesłany przez [email protected]. Weryfikacja zapewnia 50 darmowych kredytów.

3. 3
   Przechowuj swój klucz API

   Skopiuj wygenerowany wly_live_... key i przechowuj go w zmiennej środowiskowej po stronie serwera.

4. 4
   Złóż wniosek testowy

   Zadzwoń do punktu końcowego konta, aby zweryfikować uwierzytelnienie i sprawdzić pozostałe saldo.

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" }
}

Podstawowy adres URL i wersja

Wszystkie produkcyjne punkty końcowe są obsługiwane z następującego podstawowego adresu URL z wersją:

Zmiana odpowiedzi lub zachowania na przerwanie spowoduje użycie nowej wersji ścieżki. W obrębie można wprowadzić pola addytywne v1, dlatego klienci powinni ignorować właściwości odpowiedzi, których nie rozpoznają.

Uwierzytelnianie

Uwierzytelnione punkty końcowe wymagają klucza API w pliku HTTP Authorization nagłówek przy użyciu schematu Bearer.

Authorization: Bearer wly_live_your_api_key

Zlokalizowane komunikaty API

Ustaw język odpowiedzi za pomocą ?lang=tr lub standardowy Accept-Language nagłówek. Parametry zapytania mają pierwszeństwo. Każda odpowiedź JSON deklaruje wybrane ustawienia regionalne Content-Language i meta.lang. Kody błędów pozostają stabilne w języku angielskim w celu obsługi programowej; lokalizowana jest tylko wiadomość czytelna dla człowieka.

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

Obsługiwane kody języków: 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.

Kredyty i rozliczenia

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 i nie przetwarza operacji.

{
  "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"
  }
}

Cykl życia klucza API

Utwórz osobne klucze do programowania, przemieszczania i produkcji. Wordly przechowuje tylko kryptograficzny skrót każdego klucza; pełna wartość jest wyświetlana raz podczas tworzenia.

• Nazwij klucze według środowiska lub usługi.
• Użyj zmiennych środowiskowych lub zarządzanego magazynu tajnego.
• Natychmiast unieważnij klucz, jeśli mógł zostać ujawniony.
• Obracaj klucze bez ponownego używania starych wartości.
• Nie wysyłaj kluczy w ciągach zapytań.

Format odpowiedzi

Skuteczne odpowiedzi wykorzystują najwyższy poziom data obiekt i może zawierać: meta obiekt. Błędy zawsze korzystają z najwyższego poziomu error obiekt ze stabilnym odczytem maszynowym code i czytelny dla człowieka message.

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

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

Zachowaj request_id podczas kontaktowania się z pomocą techniczną w sprawie pomyślnie rozliczonego żądania. JSON jest zakodowany w formacie UTF-8 i klienci powinni wysyłać Accept: application/json.

Punkty końcowe produkcji

Punkty końcowe słownictwa

GET /v1/words/{word}

Zwraca dokładne dopasowanie słowa. Użyj languages=tr,de,fr aby zwrócić tylko zamówione tłumaczenia. Katalog lub przetłumaczone rekordy kosztują 1 punkt; w pełni wzbogacone profile kosztują 5 kredytów.

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

GET /v1/words/search

Szukaj za pomocą q i opcjonalne level, part_of_speech, category, limit, i cursor. Limity wahają się od 1 do 50. Pass meta.next_cursor w kolejnym żądaniu.

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

GET /v1/words/random

Zwraca 1–20 losowych słów. Filtruj według level, part_of_speechlub category. Każde zwrócone miejsce kosztuje jeden kredyt.

POST /v1/words/batch

Wyszukuje od 1 do 50 unikalnych słów w jednym żądaniu. Odpowiedź zachowuje kolejność żądań i oznacza każdy element znakiem 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

Zwraca wszystkie 30 obsługiwanych ustawień regionalnych interfejsu i komunikatów API. Tłumaczenia słownictwa są zwracane tylko wtedy, gdy są dostępne. Ten punkt końcowy jest publiczny i kosztuje zero kredytów.

Limit stawki

Każdy klucz API jest ograniczony do 120 zaakceptowanych żądań na minutę. Odpowiedzi obejmują X-RateLimit-Limit i X-RateLimit-Remaining. A 429 rate_limit_exceeded odpowiedź zawiera 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

Błędy

Zalecane zasady ponawiania prób

Nie próbuj ponownie 401, 402lub 404 automatycznie. Dla przejściowego 5xx odpowiedzi, użyj wykładniczego wycofywania z jitterem i ścisłym limitem ponownych prób. Nigdy nie twórz nieograniczonej pętli ponawiania prób, ponieważ każde zaakceptowane uwierzytelnione żądanie może spowodować zużycie kredytów.

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

Pyton

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

Dart / Flutter

Nie wysyłaj klucza Wordly wewnątrz aplikacji Flutter. Przykład dotyczy zaufanego backendu lub funkcji serwera 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']);
}

Lista kontrolna produkcji

• Proxy Wordly żąda za pośrednictwem zaufanego backendu.
• Ustaw limity czasu połączenia i odpowiedzi.
• Uchwyt 401, 402, 404, i 5xx osobno.
• Query GET /v1/account when your application needs the current balance.
• Rejestruj punkt końcowy, stan, opóźnienie i request_id bez logowania klucza API.
• Używaj oddzielnych kluczy dla każdego środowiska i okresowo je zmieniaj.
• Cache stable vocabulary responses in your backend when appropriate.