Wordly API を使用して構築します。

クイックスタート

無料アカウントを作成し、6 桁のコードを使用して電子メールを認証し、開発者ダッシュボードに一度表示された API キーをコピーします。

1. 1
   アカウントを作成する

   メールアドレスとパスワードのみでご登録いただけます。

2. 2
   メールアドレスを確認してください

   から送られてきたコードを入力してください [email protected]. Verification grants 50 free credits.

3. 3
   API キーを保存する

   生成されたものをコピーする wly_live_... キーを取得し、サーバー側の環境変数に保持します。

4. 4
   テストリクエストをする

   アカウント エンドポイントを呼び出して認証を確認し、残高を確認します。

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 とバージョン管理

すべての運用エンドポイントは、次のバージョン管理されたベース URL から提供されます。

重大な応答または動作の変更には、新しいパス バージョンが使用されます。加算フィールドは内に導入される可能性があります v1, so clients should ignore response properties they do not recognize.

認証

認証されたエンドポイントには HTTP の API キーが必要です Authorization Bearer スキームを使用したヘッダー。

Authorization: Bearer wly_live_your_api_key

ローカライズされた API メッセージ

応答言語を設定します ?lang=tr または標準 Accept-Language ヘッダー。クエリパラメータが優先されます。すべての JSON 応答は、選択されたロケールを次のように宣言します。 Content-Language そして 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"

サポートされている言語コード: 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.

クレジットと請求

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 操作を処理しません。

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

開発、ステージング、本番用に個別のキーを作成します。 Wordly は各キーの暗号ハッシュのみを保存します。完全な値は作成時に一度表示されます。

• 環境またはサービスごとにキーに名前を付けます。
• 環境変数またはマネージド シークレット ストアを使用します。
• キーが公開された可能性がある場合は、直ちにキーを取り消してください。
• 古い値を再利用せずにキーをローテーションします。
• クエリ文字列でキーを送信しないでください。

応答フォーマット

成功した応答ではトップレベルが使用されます。 data オブジェクトであり、 meta オブジェクト。エラーは常にトップレベルを使用します error 安定した機械可読性を持つオブジェクト code そして人間が読める形式 message.

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

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

保管してください request_id 成功した請求リクエストについてサポートに連絡するとき。 JSON は UTF-8 でエンコードされており、クライアントは送信する必要があります。 Accept: application/json.

実稼働エンドポイント

語彙のエンドポイント

GET /v1/words/{word}

完全に一致する単語を返します。使用する languages=tr,de,fr 要求された翻訳のみを返します。カタログまたは翻訳されたレコードには 1 クレジットがかかります。完全に充実したプロファイルには 5 クレジットがかかります。

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

GET /v1/words/search

で検索 q そしてオプションの level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor 次のリクエストに移ります。

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

GET /v1/words/random

1 ～ 20 個のランダムな単語を返します。フィルター条件 level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

1 回のリクエストで 1 ～ 50 個の一意の単語を検索します。応答では要求の順序が保持され、すべての項目にマークが付けられます。 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

サポートされている 30 のインターフェイスおよび API メッセージ ロケールをすべて返します。語彙の翻訳は、利用可能な場合にのみ返されます。このエンドポイントはパブリックであり、クレジットの費用はゼロです。

レート制限

各 API キーは、ローリング 1 分あたり受け入れられるリクエストの数が 120 に制限されています。応答には次のものが含まれます X-RateLimit-Limit そして X-RateLimit-Remaining. A 429 rate_limit_exceeded 応答には以下が含まれます 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

エラー

推奨される再試行ポリシー

再試行しないでください 401, 402, or 404 自動的に。過渡用 5xx 応答には、ジッターと厳格な再試行制限を伴う指数バックオフを使用します。承認された認証リクエストごとにクレジットが消費される可能性があるため、無制限の再試行ループを作成しないでください。

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

パイソン

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

ダーツ/フラッター

Wordly キーを Flutter アプリケーション内に同梱しないでください。この例は、信頼できる 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']);
}

製作チェックリスト

• Wordly リクエストは信頼できるバックエンドを通じてプロキシされます。
• 接続と応答のタイムアウトを設定します。
• ハンドル 401, 402, 404, and 5xx 別に。
• Query GET /v1/account when your application needs the current balance.
• エンドポイント、ステータス、遅延、および request_id API キーをログに記録しないでください。
• 環境ごとに個別のキーを使用し、定期的にローテーションします。
• Cache stable vocabulary responses in your backend when appropriate.