使用 Wordly API 构建。

快速入门

创建一个免费帐户，使用六位数代码验证您的电子邮件，然后复制开发人员仪表板中显示的 API 密钥。

1. 1
   创建帐户

   仅使用电子邮件地址和密码进行注册。

2. 2
   验证您的电子邮件

   输入发送者发送的代码 [email protected]. Verification grants 50 free credits.

3. 3
   存储您的 API 密钥

   复制生成的 wly_live_... key 并将其保存在服务器端环境变量中。

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 使用承载方案的标头。

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 到 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 密钥每滚动分钟最多只能接受 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);

飞镖/颤振

不要在 Flutter 应用程序中发送 Wordly 密钥。该示例属于受信任的 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.