Sestavte pomocí Wordly API.

Rychlý start

Vytvořte si bezplatný účet, ověřte svůj e-mail pomocí šestimístného kódu a zkopírujte klíč API zobrazený jednou na vašem vývojářském panelu.

1. 1
   Vytvořte si účet

   Zaregistrujte se pouze pomocí e-mailové adresy a hesla.

2. 2
   Ověřte svůj e-mail

   Zadejte kód odeslaný uživatelem [email protected]. Verification grants 50 free credits.

3. 3
   Uložte si svůj API klíč

   Zkopírujte vygenerované wly_live_... klíč a ponechte jej v proměnné prostředí na straně serveru.

4. 4
   Požádejte o test

   Zavolejte na koncový bod účtu a ověřte ověření a podívejte se na zbývající zůstatek.

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

Základní URL a verzování

Všechny produkční koncové body jsou obsluhovány z následující verze základní adresy URL:

Při porušení odezvy nebo změn chování se použije nová verze cesty. Mohou být zavedena aditivní pole v1, so clients should ignore response properties they do not recognize.

Autentizace

Ověřené koncové body vyžadují klíč API v HTTP Authorization záhlaví pomocí schématu Nosič.

Authorization: Bearer wly_live_your_api_key

Lokalizované zprávy API

Nastavte jazyk odezvy pomocí ?lang=tr nebo standard Accept-Language záhlaví. Parametry dotazu mají přednost. Každá odpověď JSON deklaruje vybrané národní prostředí Content-Language a meta.lang. Error codes remain stable in English for programmatic handling; only the human-readable message is localized.

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

Podporované kódy jazyků: 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.

Kredity a fakturace

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 a nezpracuje operaci.

{
  "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 key lifecycle

Vytvořte samostatné klíče pro vývoj, přípravu a produkci. Wordly ukládá pouze kryptografický hash každého klíče; kompletní hodnota se zobrazí jednou při vytvoření.

• Pojmenujte klíče podle prostředí nebo služby.
• Použijte proměnné prostředí nebo spravované tajné úložiště.
• Okamžitě zrušte klíč, pokud mohl být odhalen.
• Otočte klíče bez opětovného použití starých hodnot.
• Neposílejte klíče v řetězcích dotazu.

Formát odpovědi

Úspěšné odpovědi používají nejvyšší úroveň data objekt a může zahrnovat a meta objekt. Chyby vždy používají nejvyšší úroveň error objekt se stabilním strojově čitelným code a lidsky čitelný message.

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

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

Udržujte request_id při kontaktování podpory ohledně úspěšného fakturovaného požadavku. JSON je kódován UTF-8 a klienti by měli odesílat Accept: application/json.

Výrobní koncové body

Koncové body slovní zásoby

GET /v1/words/{word}

Vrátí přesnou shodu slova. Použijte languages=tr,de,fr vrátit pouze požadované překlady. Katalog nebo přeložené záznamy stojí 1 kredit; plně obohacené profily stojí 5 kreditů.

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

GET /v1/words/search

Hledat pomocí q a volitelné level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor do další žádosti.

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

GET /v1/words/random

Vrátí 1–20 náhodných slov. Filtrovat podle level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

V jednom požadavku vyhledá 1 až 50 jedinečných slov. Odpověď zachová pořadí požadavku a označí každou položku 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

Vrátí všech 30 podporovaných rozhraní a národních prostředí zpráv API. Překlady slovní zásoby jsou vráceny pouze tehdy, jsou-li k dispozici. Tento koncový bod je veřejný a nestojí žádné kredity.

Limit sazby

Každý klíč API je omezen na 120 přijatých požadavků za klouzavou minutu. Odpovědi zahrnují X-RateLimit-Limit a X-RateLimit-Remaining. A 429 rate_limit_exceeded odpověď zahrnuje 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

Chyby

Doporučené zásady opakování

Nezkoušejte to znovu 401, 402, or 404 automaticky. Pro přechodné 5xx odpovědi, použijte exponenciální ústup s jitterem a přísným omezením opakování. Nikdy nevytvářejte neomezenou smyčku opakování, protože každý přijatý ověřený požadavek může spotřebovat kredity.

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

Šipka / Flutter

Nezasílejte klíč Wordly uvnitř aplikace Flutter. Příklad patří do důvěryhodného backendu nebo funkce serveru 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']);
}

Kontrolní seznam výroby

• Proxy Wordly požadavky prostřednictvím důvěryhodného backendu.
• Nastavte časové limity připojení a odezvy.
• Rukojeť 401, 402, 404, and 5xx samostatně.
• Query GET /v1/account when your application needs the current balance.
• Zaznamenat koncový bod, stav, latenci a request_id bez přihlášení klíče API.
• Používejte samostatné klíče pro každé prostředí a pravidelně je střídejte.
• Cache stable vocabulary responses in your backend when appropriate.