Erstellen Sie mit der Wordly-API.

Schnellstart

Erstellen Sie ein kostenloses Konto, bestätigen Sie Ihre E-Mail-Adresse mit dem sechsstelligen Code und kopieren Sie den API-Schlüssel, der einmal in Ihrem Entwickler-Dashboard angezeigt wird.

1. 1
   Erstellen Sie ein Konto

   Registrieren Sie sich nur mit einer E-Mail-Adresse und einem Passwort.

2. 2
   Bestätigen Sie Ihre E-Mail

   Geben Sie den von gesendeten Code ein [email protected]. Durch die Verifizierung werden 50 kostenlose Credits gewährt.

3. 3
   Speichern Sie Ihren API-Schlüssel

   Kopieren Sie das generierte wly_live_... Schlüssel und bewahren Sie ihn in einer serverseitigen Umgebungsvariablen auf.

4. 4
   Stellen Sie eine Testanfrage

   Rufen Sie den Kontoendpunkt an, um die Authentifizierung zu überprüfen und den Restbetrag anzuzeigen.

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

Basis-URL und Versionierung

Alle Produktionsendpunkte werden von der folgenden versionierten Basis-URL bedient:

Bei Unterbrechungsreaktionen oder Verhaltensänderungen wird eine neue Pfadversion verwendet. Additive Felder können darin eingeführt werden v1Daher sollten Clients Antworteigenschaften ignorieren, die sie nicht erkennen.

Authentifizierung

Authentifizierte Endpunkte erfordern einen API-Schlüssel im HTTP Authorization Header mithilfe des Bearer-Schemas.

Authorization: Bearer wly_live_your_api_key

Lokalisierte API-Nachrichten

Stellen Sie die Antwortsprache mit ein ?lang=tr oder der Standard Accept-Language Kopfzeile. Abfrageparameter haben Vorrang. Jede JSON-Antwort deklariert das ausgewählte Gebietsschema in Content-Language und meta.lang. Fehlercodes bleiben für die programmgesteuerte Behandlung in Englisch stabil; Nur die für Menschen lesbare Nachricht wird lokalisiert.

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

Unterstützte Sprachcodes: 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.

Gutschriften und Abrechnung

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 und verarbeitet den Vorgang nicht.

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

Lebenszyklus des API-Schlüssels

Erstellen Sie separate Schlüssel für Entwicklung, Staging und Produktion. Wordly speichert nur einen kryptografischen Hash jedes Schlüssels; Der vollständige Wert wird einmalig bei der Erstellung angezeigt.

• Benennen Sie Schlüssel nach Umgebung oder Dienst.
• Verwenden Sie Umgebungsvariablen oder einen verwalteten Secret Store.
• Ziehen Sie einen Schlüssel sofort zurück, wenn er möglicherweise offengelegt wurde.
• Schlüssel rotieren, ohne alte Werte wiederzuverwenden.
• Senden Sie keine Schlüssel in Abfragezeichenfolgen.

Antwortformat

Erfolgreiche Antworten verwenden eine oberste Ebene data Objekt und kann Folgendes umfassen: meta Objekt. Fehler verwenden immer eine oberste Ebene error Objekt mit einer stabilen maschinenlesbaren code und eine für Menschen lesbare message.

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

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

Behalten Sie die request_id wenn Sie den Support wegen einer erfolgreichen Rechnungsanfrage kontaktieren. JSON ist UTF-8-codiert und sollte von Clients gesendet werden Accept: application/json.

Produktionsendpunkte

Vokabelendpunkte

GET /v1/words/{word}

Gibt eine genaue Wortübereinstimmung zurück. Benutzen languages=tr,de,fr um nur angeforderte Übersetzungen zurückzugeben. Kataloge oder übersetzte Datensätze kosten 1 Credit; Vollständig angereicherte Profile kosten 5 Credits.

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

GET /v1/words/search

Suchen mit q und optional level, part_of_speech, category, limit, und cursor. Die Limits liegen zwischen 1 und 50. Bestehen meta.next_cursor in die nächste Anfrage ein.

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

GET /v1/words/random

Gibt 1–20 zufällige Wörter zurück. Filtern nach level, part_of_speech, oder category. Jeder zurückgegebene Slot kostet ein Guthaben.

POST /v1/words/batch

Sucht zwischen 1 und 50 eindeutigen Wörtern in einer einzigen Anfrage. Die Antwort behält die Reihenfolge der Anfragen bei und markiert jedes Element mit 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

Gibt alle 30 unterstützten Schnittstellen- und API-Nachrichtengebietsschemas zurück. Vokabelübersetzungen werden nur zurückgegeben, wenn sie verfügbar sind. Dieser Endpunkt ist öffentlich und kostet keine Credits.

Ratenbegrenzung

Jeder API-Schlüssel ist auf 120 akzeptierte Anfragen pro laufender Minute begrenzt. Zu den Antworten gehören: X-RateLimit-Limit und X-RateLimit-Remaining. A 429 rate_limit_exceeded Antwort umfasst 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

Fehler

Empfohlene Wiederholungsrichtlinie

Versuchen Sie es nicht erneut 401, 402, oder 404 automatisch. Für Durchreisende 5xx Verwenden Sie für Antworten einen exponentiellen Backoff mit Jitter und eine strikte Wiederholungsobergrenze. Erstellen Sie niemals eine unbegrenzte Wiederholungsschleife, da jede akzeptierte authentifizierte Anfrage möglicherweise Credits verbraucht.

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 / Flattern

Versenden Sie den Wordly-Schlüssel nicht innerhalb einer Flutter-Anwendung. Das Beispiel gehört in eine vertrauenswürdige Dart-Backend- oder Serverfunktion.

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

Checkliste für die Produktion

• Proxy-Wordly-Anfragen über ein vertrauenswürdiges Backend.
• Legen Sie Verbindungs- und Antwort-Timeouts fest.
• Griff 401, 402, 404, und 5xx separat.
• Query GET /v1/account when your application needs the current balance.
• Endpunkt, Status, Latenz usw. protokollieren request_id ohne den API-Schlüssel zu protokollieren.
• Verwenden Sie separate Schlüssel pro Umgebung und wechseln Sie diese regelmäßig.
• Cache stable vocabulary responses in your backend when appropriate.