Xây dựng với API Wordly.

Bắt đầu nhanh

Tạo một tài khoản miễn phí, xác minh email của bạn bằng mã gồm sáu chữ số và sao chép khóa API được hiển thị một lần trong trang tổng quan dành cho nhà phát triển của bạn.

1. 1
   Tạo một tài khoản

   Đăng ký chỉ với một địa chỉ email và mật khẩu.

2. 2
   Xác minh email của bạn

   Nhập mã được gửi bởi [email protected]. Verification grants 50 free credits.

3. 3
   Lưu trữ khóa API của bạn

   Sao chép được tạo wly_live_... key và giữ nó trong biến môi trường phía máy chủ.

4. 4
   Đưa ra yêu cầu kiểm tra

   Gọi tới điểm cuối tài khoản để xác minh xác thực và xem số dư còn lại.

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 cơ sở và phiên bản

Tất cả các điểm cuối sản xuất đều được phân phối từ URL cơ sở được phiên bản sau:

Các thay đổi về phản hồi hoặc hành vi sẽ sử dụng phiên bản đường dẫn mới. Các trường bổ sung có thể được giới thiệu trong v1, so clients should ignore response properties they do not recognize.

Xác thực

Điểm cuối được xác thực yêu cầu khóa API trong HTTP Authorization tiêu đề bằng cách sử dụng lược đồ Bearer.

Authorization: Bearer wly_live_your_api_key

Thông báo API được bản địa hóa

Đặt ngôn ngữ phản hồi với ?lang=tr hoặc tiêu chuẩn Accept-Language tiêu đề. Các tham số truy vấn được ưu tiên. Mọi phản hồi JSON đều khai báo ngôn ngữ đã chọn trong Content-Language và 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"

Mã ngôn ngữ được hỗ 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.

Tín dụng và thanh toán

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 và không xử lý hoạt động.

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

Tạo các khóa riêng biệt để phát triển, dàn dựng và sản xuất. Wordly chỉ lưu trữ hàm băm mật mã của mỗi khóa; giá trị hoàn chỉnh được hiển thị một lần khi tạo.

• Đặt tên cho các khóa theo môi trường hoặc dịch vụ.
• Sử dụng các biến môi trường hoặc một kho lưu trữ bí mật được quản lý.
• Thu hồi chìa khóa ngay lập tức nếu nó có thể bị lộ.
• Xoay phím mà không sử dụng lại giá trị cũ.
• Không gửi khóa trong chuỗi truy vấn.

Định dạng phản hồi

Phản hồi thành công sử dụng cấp cao nhất data đối tượng và có thể bao gồm một meta đối tượng. Lỗi luôn sử dụng mức cao nhất error đối tượng có thể đọc được bằng máy ổn định code và con người có thể đọc được message.

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

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

Giữ request_id khi liên hệ với bộ phận hỗ trợ về yêu cầu thanh toán thành công. JSON được mã hóa UTF-8 và khách hàng nên gửi Accept: application/json.

Điểm cuối sản xuất

Điểm cuối từ vựng

GET /v1/words/{word}

Trả về một từ khớp chính xác. sử dụng languages=tr,de,fr chỉ trả lại các bản dịch được yêu cầu. Danh mục hoặc bản dịch có giá 1 tín chỉ; hồ sơ được làm giàu đầy đủ có giá 5 tín chỉ.

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

GET /v1/words/search

Tìm kiếm với q và tùy chọn level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor vào yêu cầu tiếp theo.

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

GET /v1/words/random

Trả về 1–20 từ ngẫu nhiên. Lọc theo level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

Tra cứu từ 1 đến 50 từ duy nhất trong một yêu cầu. Phản hồi duy trì thứ tự yêu cầu và đánh dấu mọi mục bằng 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

Trả về tất cả 30 ngôn ngữ giao diện và thông báo API được hỗ trợ. Bản dịch từ vựng chỉ được trả lại khi có sẵn. Điểm cuối này là công khai và không tốn tín dụng.

Giới hạn tỷ lệ

Mỗi khóa API được giới hạn ở 120 yêu cầu được chấp nhận mỗi phút. Phản hồi bao gồm X-RateLimit-Limit và X-RateLimit-Remaining. A 429 rate_limit_exceeded phản ứng bao gồm 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

Lỗi

Chính sách thử lại được đề xuất

Đừng thử lại 401, 402, or 404 tự động. Dành cho thoáng qua 5xx phản hồi, hãy sử dụng thời gian chờ theo cấp số nhân với jitter và giới hạn thử lại nghiêm ngặt. Không bao giờ tạo vòng thử lại không giới hạn vì mỗi yêu cầu được xác thực được chấp nhận có thể tiêu tốn tín dụng.

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

Phi tiêu / rung

Không gửi khóa Wordly bên trong ứng dụng Flutter. Ví dụ này thuộc về chức năng máy chủ hoặc chương trình phụ trợ Dart đáng tin cậy.

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

Danh sách kiểm tra sản xuất

• Proxy Wordly yêu cầu thông qua một chương trình phụ trợ đáng tin cậy.
• Đặt thời gian chờ kết nối và phản hồi.
• xử lý 401, 402, 404, and 5xx riêng biệt.
• Query GET /v1/account when your application needs the current balance.
• Ghi nhật ký điểm cuối, trạng thái, độ trễ và request_id mà không cần đăng nhập khóa API.
• Sử dụng các khóa riêng biệt cho mỗi môi trường và xoay chúng theo định kỳ.
• Cache stable vocabulary responses in your backend when appropriate.