Construisez avec l'API Wordly.

Démarrage rapide

Créez un compte gratuit, vérifiez votre e-mail à l'aide du code à six chiffres et copiez la clé API affichée une fois dans votre tableau de bord de développeur.

1. 1
   Créer un compte

   Inscrivez-vous avec seulement une adresse e-mail et un mot de passe.

2. 2
   Vérifiez votre email

   Entrez le code envoyé par [email protected]. La vérification accorde 50 crédits gratuits.

3. 3
   Stockez votre clé API

   Copiez le généré wly_live_... clé et conservez-la dans une variable d’environnement côté serveur.

4. 4
   Faire une demande de test

   Appelez le point de terminaison du compte pour vérifier l’authentification et voir le solde restant.

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 de base et gestion des versions

Tous les points de terminaison de production sont servis à partir de l'URL de base versionnée suivante :

Les changements de réponse ou de comportement en cas de rupture utiliseront une nouvelle version du chemin. Des champs supplémentaires peuvent être introduits dans v1, les clients doivent donc ignorer les propriétés de réponse qu'ils ne reconnaissent pas.

Authentification

Les points de terminaison authentifiés nécessitent une clé API dans le protocole HTTP Authorization en-tête utilisant le schéma Bearer.

Authorization: Bearer wly_live_your_api_key

Messages API localisés

Définissez la langue de réponse avec ?lang=tr ou la norme Accept-Language en-tête. Les paramètres de requête sont prioritaires. Chaque réponse JSON déclare les paramètres régionaux sélectionnés dans Content-Language et meta.lang. Les codes d'erreur restent stables en anglais pour la gestion programmatique ; seul le message lisible par l'homme est localisé.

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

Codes de langue pris en charge : 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.

Crédits et facturation

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 et ne traite pas l'opération.

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

Cycle de vie de la clé API

Créez des clés distinctes pour le développement, la préparation et la production. Wordly stocke uniquement un hachage cryptographique de chaque clé ; la valeur complète est affichée une fois à la création.

• Nommez les clés par environnement ou service.
• Utilisez des variables d'environnement ou un magasin de secrets géré.
• Révoquez immédiatement une clé si elle a pu être exposée.
• Faites pivoter les clés sans réutiliser les anciennes valeurs.
• N'envoyez pas de clés dans les chaînes de requête.

Format de réponse

Les réponses réussies utilisent un niveau supérieur data objet et peut inclure un meta objet. Les erreurs utilisent toujours un niveau supérieur error objet avec un stable lisible par machine code et un lisible par l'homme message.

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

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

Gardez le request_id lorsque vous contactez l'assistance au sujet d'une demande facturée réussie. JSON est codé en UTF-8 et les clients doivent envoyer Accept: application/json.

Points finaux de production

Points finaux du vocabulaire

GET /v1/words/{word}

Renvoie une correspondance de mot exacte. Utiliser languages=tr,de,fr pour renvoyer uniquement les traductions demandées. Le catalogue ou les documents traduits coûtent 1 crédit ; les profils entièrement enrichis coûtent 5 crédits.

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

GET /v1/words/search

Rechercher avec q et en option level, part_of_speech, category, limit, et cursor. Les limites vont de 1 à 50. Réussir meta.next_cursor dans la prochaine demande.

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

GET /v1/words/random

Renvoie 1 à 20 mots aléatoires. Filtrer par level, part_of_speech, ou category. Chaque emplacement retourné coûte un crédit.

POST /v1/words/batch

Recherche entre 1 et 50 mots uniques en une seule requête. La réponse préserve l'ordre des requêtes et marque chaque élément avec 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

Renvoie les 30 paramètres régionaux d'interface et de message API pris en charge. Les traductions de vocabulaire sont renvoyées uniquement lorsqu'elles sont disponibles. Ce point de terminaison est public et ne coûte aucun crédit.

Limite de taux

Chaque clé API est limitée à 120 requêtes acceptées par minute glissante. Les réponses incluent X-RateLimit-Limit et X-RateLimit-Remaining. Un 429 rate_limit_exceeded la réponse comprend 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

Erreurs

Politique de nouvelle tentative recommandée

Ne réessayez pas 401, 402, ou 404 automatiquement. Pour transitoire 5xx réponses, utilisez une interruption exponentielle avec une gigue et un plafond de nouvelle tentative strict. Ne créez jamais de boucle de nouvelle tentative illimitée, car chaque demande authentifiée acceptée peut consommer des crédits.

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

Fléchette / Battement

N'envoyez pas la clé Wordly dans une application Flutter. L'exemple appartient à une fonction backend ou serveur Dart de confiance.

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

Liste de contrôle de production

• Requêtes proxy Wordly via un backend de confiance.
• Définissez les délais d’attente de connexion et de réponse.
• Poignée 401, 402, 404, et 5xx séparément.
• Query GET /v1/account when your application needs the current balance.
• Consigner le point de terminaison, l'état, la latence et request_id sans enregistrer la clé API.
• Utilisez des clés distinctes par environnement et faites-les pivoter périodiquement.
• Cache stable vocabulary responses in your backend when appropriate.