Creați cu API-ul Wordly.

Pornire rapidă

Creați un cont gratuit, verificați-vă e-mailul folosind codul din șase cifre și copiați cheia API afișată o dată în tabloul de bord pentru dezvoltatori.

1. 1
   Creați un cont

   Înregistrați-vă doar cu o adresă de e-mail și o parolă.

2. 2
   Verificați-vă adresa de e-mail

   Introdu codul trimis de [email protected]. Verification grants 50 free credits.

3. 3
   Stocați-vă cheia API

   Copiați cel generat wly_live_... cheie și păstrați-o într-o variabilă de mediu pe partea serverului.

4. 4
   Faceți o cerere de testare

   Apelați punctul final al contului pentru a verifica autentificarea și a vedea soldul rămas.

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

Adresa URL de bază și versiunea

Toate punctele finale de producție sunt difuzate de la următoarea adresă URL de bază versiunea:

Răspunsul de întrerupere sau schimbările de comportament vor folosi o nouă versiune de cale. Câmpurile aditive pot fi introduse în interior v1, so clients should ignore response properties they do not recognize.

Autentificare

Punctele finale autentificate necesită o cheie API în HTTP Authorization antet folosind schema Bearer.

Authorization: Bearer wly_live_your_api_key

Mesaje API localizate

Setați limba de răspuns cu ?lang=tr sau standardul Accept-Language antet. Parametrii de interogare au prioritate. Fiecare răspuns JSON declară localitatea selectată în Content-Language şi 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"

Codurile de limbă acceptate: 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.

Credite și facturare

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 nu prelucrează operațiunea.

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

Creați chei separate pentru dezvoltare, punere în scenă și producție. Wordly stochează doar un hash criptografic al fiecărei chei; valoarea completă este afișată o dată la creare.

• Denumiți cheile după mediu sau serviciu.
• Utilizați variabile de mediu sau un depozit secret gestionat.
• Revocați imediat o cheie dacă este posibil să fi fost expusă.
• Rotiți cheile fără a reutiliza valorile vechi.
• Nu trimiteți chei în șiruri de interogare.

Formatul de răspuns

Răspunsurile de succes folosesc un nivel superior data obiect și poate include a meta obiect. Erorile folosesc întotdeauna un nivel superior error obiect cu un dispozitiv stabil, care poate fi citit de mașină code și un citibil de om message.

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

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

Păstrați request_id atunci când contactați asistența în legătură cu o solicitare facturată reușită. JSON este codificat UTF-8 și clienții ar trebui să trimită Accept: application/json.

Puncte finale de producție

Finalizări ale vocabularului

GET /v1/words/{word}

Returnează o potrivire exactă a cuvântului. Utilizați languages=tr,de,fr pentru a returna numai traducerile solicitate. Înregistrările de catalog sau traduse costă 1 credit; profilurile complet îmbogățite costă 5 credite.

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

GET /v1/words/search

Caută cu q și opțional level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor în următoarea cerere.

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

GET /v1/words/random

Returnează 1–20 de cuvinte aleatorii. Filtrați după level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

Caută între 1 și 50 de cuvinte unice într-o singură solicitare. Răspunsul păstrează ordinea cererii și marchează fiecare articol cu 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

Returnează toate cele 30 de interfețe acceptate și localuri de mesaje API. Traducerile de vocabular sunt returnate numai atunci când sunt disponibile. Acest punct final este public și costă zero credite.

Limită de rată

Fiecare cheie API este limitată la 120 de solicitări acceptate pe minut. Răspunsurile includ X-RateLimit-Limit şi X-RateLimit-Remaining. A 429 rate_limit_exceeded răspunsul include 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

Erori

Politica de reîncercare recomandată

Nu reîncercați 401, 402, or 404 automat. Pentru tranzitoriu 5xx răspunsuri, utilizați backoff exponențial cu jitter și o limită strictă de reîncercare. Nu creați niciodată o buclă de reîncercare nelimitată, deoarece fiecare cerere autentificată acceptată poate consuma credite.

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

Dart / Flutter

Nu expediați cheia Wordly într-o aplicație Flutter. Exemplul aparține unei funcții de server sau backend Dart de încredere.

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 de verificare a producției

• Solicitări Proxy Wordly printr-un backend de încredere.
• Setați conexiuni și timpi de răspuns.
• Mâner 401, 402, 404, and 5xx separat.
• Query GET /v1/account when your application needs the current balance.
• Înregistrați punctul final, starea, latența și request_id fără a înregistra cheia API.
• Utilizați taste separate pentru fiecare mediu și rotiți-le periodic.
• Cache stable vocabulary responses in your backend when appropriate.