Bina dengan Wordly API.

Mula pantas

Buat akaun percuma, sahkan e-mel anda menggunakan kod enam digit dan salin kunci API yang ditunjukkan sekali dalam papan pemuka pembangun anda.

1. 1
   Buat akaun

   Daftar dengan hanya alamat e-mel dan kata laluan.

2. 2
   Sahkan e-mel anda

   Masukkan kod yang dihantar oleh [email protected]. Verification grants 50 free credits.

3. 3
   Simpan kunci API anda

   Salin yang dihasilkan wly_live_... kunci dan simpannya dalam pembolehubah persekitaran sebelah pelayan.

4. 4
   Buat permintaan ujian

   Hubungi titik akhir akaun untuk mengesahkan pengesahan dan melihat baki yang tinggal.

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 asas dan versi

Semua titik akhir pengeluaran disajikan daripada URL asas versi berikut:

Memecah tindak balas atau perubahan tingkah laku akan menggunakan versi laluan baharu. Medan aditif boleh diperkenalkan dalam v1, so clients should ignore response properties they do not recognize.

Pengesahan

Titik akhir yang disahkan memerlukan kunci API dalam HTTP Authorization pengepala menggunakan skema Pembawa.

Authorization: Bearer wly_live_your_api_key

Mesej API setempat

Tetapkan bahasa respons dengan ?lang=tr atau piawaian Accept-Language pengepala. Parameter pertanyaan diutamakan. Setiap respons JSON mengisytiharkan tempat yang dipilih masuk Content-Language dan 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"

Kod bahasa yang disokong: 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.

Kredit dan pengebilan

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 dan tidak memproses operasi.

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

Cipta kunci berasingan untuk pembangunan, pementasan dan pengeluaran. Wordly hanya menyimpan cincangan kriptografi bagi setiap kunci; nilai lengkap dipaparkan sekali semasa penciptaan.

• Namakan kunci mengikut persekitaran atau perkhidmatan.
• Gunakan pembolehubah persekitaran atau stor rahsia terurus.
• Batalkan kunci serta-merta jika ia mungkin telah terdedah.
• Putar kekunci tanpa menggunakan semula nilai lama.
• Jangan hantar kunci dalam rentetan pertanyaan.

Format jawapan

Respons yang berjaya menggunakan tahap teratas data objek dan mungkin termasuk a meta objek. Ralat sentiasa menggunakan peringkat atasan error objek dengan mesin yang stabil boleh dibaca code dan boleh dibaca manusia message.

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

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

Simpan request_id apabila menghubungi sokongan tentang permintaan bil yang berjaya. JSON dikodkan UTF-8 dan pelanggan harus menghantar Accept: application/json.

Titik akhir pengeluaran

Titik akhir perbendaharaan kata

GET /v1/words/{word}

Mengembalikan padanan perkataan yang tepat. guna languages=tr,de,fr untuk mengembalikan terjemahan yang diminta sahaja. Katalog atau rekod terjemahan berharga 1 kredit; profil yang diperkaya sepenuhnya berharga 5 kredit.

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

GET /v1/words/search

Cari dengan q dan pilihan level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor ke dalam permintaan seterusnya.

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

GET /v1/words/random

Mengembalikan 1–20 perkataan rawak. Tapis mengikut level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

Mencari antara 1 dan 50 perkataan unik dalam satu permintaan. Respons mengekalkan pesanan permintaan dan menandakan setiap item dengan 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

Mengembalikan kesemua 30 antara muka yang disokong dan tempat mesej API. Terjemahan kosa kata dikembalikan hanya apabila tersedia. Titik akhir ini adalah awam dan kos sifar kredit.

Had kadar

Setiap kunci API dihadkan kepada 120 permintaan yang diterima setiap minit bergulir. Jawapan termasuk X-RateLimit-Limit dan X-RateLimit-Remaining. A 429 rate_limit_exceeded tindak balas termasuk 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

Kesilapan

Dasar cuba semula yang disyorkan

Jangan cuba semula 401, 402, or 404 secara automatik. Untuk sementara 5xx respons, gunakan backoff eksponen dengan jitter dan had cuba semula yang ketat. Jangan sekali-kali membuat gelung percubaan semula tanpa had kerana setiap permintaan disahkan yang diterima boleh menggunakan kredit.

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

Ular sawa

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

Jangan hantar kunci Wordly di dalam aplikasi Flutter. Contohnya terdapat dalam bahagian belakang Dart atau fungsi pelayan yang dipercayai.

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

Senarai semak pengeluaran

• Permintaan Proxy Wordly melalui bahagian belakang yang dipercayai.
• Tetapkan sambungan dan tamat masa tindak balas.
• pegang 401, 402, 404, and 5xx secara berasingan.
• Query GET /v1/account when your application needs the current balance.
• Log titik akhir, status, kependaman dan request_id tanpa mengelog kunci API.
• Gunakan kekunci berasingan bagi setiap persekitaran dan putarkannya secara berkala.
• Cache stable vocabulary responses in your backend when appropriate.