Bangun dengan Wordly API.

Mulai cepat

Buat akun gratis, verifikasi email Anda menggunakan kode enam digit, dan salin kunci API yang ditampilkan satu kali di dasbor pengembang Anda.

1. 1
   Buat akun

   Daftar hanya dengan alamat email dan kata sandi.

2. 2
   Verifikasi email Anda

   Masukkan kode yang dikirimkan oleh [email protected]. Verification grants 50 free credits.

3. 3
   Simpan kunci API Anda

   Salin yang dihasilkan wly_live_... kunci dan simpan dalam variabel lingkungan sisi server.

4. 4
   Buat permintaan tes

   Hubungi titik akhir akun untuk memverifikasi otentikasi dan melihat sisa saldo.

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 dasar dan pembuatan versi

Semua titik akhir produksi dilayani dari URL dasar berversi berikut:

Menghentikan respons atau perubahan perilaku akan menggunakan versi jalur baru. Bidang aditif dapat diperkenalkan di dalamnya v1, so clients should ignore response properties they do not recognize.

Otentikasi

Titik akhir yang diautentikasi memerlukan kunci API di HTTP Authorization header menggunakan skema Bearer.

Authorization: Bearer wly_live_your_api_key

Pesan API yang dilokalkan

Atur bahasa respons dengan ?lang=tr atau standar Accept-Language tajuk. Parameter kueri diutamakan. Setiap respons JSON mendeklarasikan lokal yang dipilih 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"

Kode bahasa yang didukung: 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 penagihan

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

Buat kunci terpisah untuk pengembangan, pementasan, dan produksi. Wordly hanya menyimpan hash kriptografi dari setiap kunci; nilai lengkap ditampilkan satu kali saat pembuatan.

• Kunci nama berdasarkan lingkungan atau layanan.
• Gunakan variabel lingkungan atau penyimpanan rahasia yang dikelola.
• Segera cabut kunci jika mungkin telah terbuka.
• Putar kunci tanpa menggunakan kembali nilai lama.
• Jangan mengirim kunci dalam string kueri.

Format tanggapan

Respons yang berhasil menggunakan tingkat atas data objek dan dapat mencakup a meta objek. Kesalahan selalu menggunakan tingkat atas error objek dengan stabil yang dapat dibaca mesin code dan dapat dibaca manusia message.

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

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

Pertahankan request_id saat menghubungi dukungan tentang permintaan penagihan yang berhasil. JSON dikodekan UTF-8 dan klien harus mengirim Accept: application/json.

Titik akhir produksi

Titik akhir kosakata

GET /v1/words/{word}

Mengembalikan kata yang sama persis. Gunakan languages=tr,de,fr untuk mengembalikan hanya terjemahan yang diminta. Katalog atau catatan yang diterjemahkan 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 opsional level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor ke permintaan berikutnya.

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 kata acak. Saring berdasarkan level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

Mencari antara 1 dan 50 kata unik dalam satu permintaan. Responsnya mempertahankan urutan permintaan dan menandai 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 30 antarmuka yang didukung dan lokal pesan API. Terjemahan kosakata dikembalikan hanya jika tersedia. Titik akhir ini bersifat publik dan tidak memerlukan biaya kredit.

Batas tarif

Setiap kunci API dibatasi hingga 120 permintaan yang diterima per menit berjalan. Tanggapannya meliputi X-RateLimit-Limit dan X-RateLimit-Remaining. A 429 rate_limit_exceeded respon 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

Kesalahan

Kebijakan percobaan ulang yang disarankan

Jangan mencoba lagi 401, 402, or 404 secara otomatis. Untuk sementara 5xx respons, gunakan backoff eksponensial dengan jitter dan batas coba lagi yang ketat. Jangan pernah membuat putaran percobaan ulang tanpa batas karena setiap permintaan terotentikasi yang diterima dapat menghabiskan 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 piton

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

Panah / Berkibar

Jangan mengirimkan kunci Wordly di dalam aplikasi Flutter. Contohnya termasuk dalam fungsi server atau backend Dart yang tepercaya.

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

Daftar periksa produksi

• Permintaan Proxy Wordly melalui backend tepercaya.
• Tetapkan batas waktu koneksi dan respons.
• Tangani 401, 402, 404, and 5xx secara terpisah.
• Query GET /v1/account when your application needs the current balance.
• Catat titik akhir, status, latensi, dan request_id tanpa mencatat kunci API.
• Gunakan kunci terpisah per lingkungan dan putar secara berkala.
• Cache stable vocabulary responses in your backend when appropriate.