Rakenna Wordly API:lla.

Pika-aloitus

Luo ilmainen tili, vahvista sähköpostisi kuusinumeroisella koodilla ja kopioi kerran kehittäjän hallintapaneelissa näkyvä API-avain.

1. 1
   Luo tili

   Rekisteröidy vain sähköpostiosoitteella ja salasanalla.

2. 2
   Vahvista sähköpostiosoitteesi

   Syötä lähettämä koodi [email protected]. Verification grants 50 free credits.

3. 3
   Tallenna API-avaimesi

   Kopioi luotu wly_live_... avain ja säilytä se palvelinpuolen ympäristömuuttujassa.

4. 4
   Tee testipyyntö

   Soita tilin päätepisteeseen vahvistaaksesi todennus ja katsoaksesi jäljellä olevan saldon.

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

Perus-URL-osoite ja versiointi

Kaikki tuotannon päätepisteet palvellaan seuraavasta versioidusta perus-URL-osoitteesta:

Reaktion tai käyttäytymisen muutosten rikkominen käyttää uutta polkuversiota. Sisään voidaan lisätä lisäkenttiä v1, so clients should ignore response properties they do not recognize.

Todennus

Autentikoidut päätepisteet vaativat API-avaimen HTTP:ssä Authorization otsikko Bearer-mallilla.

Authorization: Bearer wly_live_your_api_key

Lokalisoidut API-viestit

Aseta vastauskieli painamalla ?lang=tr tai standardi Accept-Language otsikko. Kyselyparametrit ovat etusijalla. Jokainen JSON-vastaus ilmoittaa valitun alueen Content-Language ja 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"

Tuetut kielikoodit: 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.

Luotto ja laskutus

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 eikä käsittele toimenpidettä.

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

Luo erilliset avaimet kehitystä, lavastusta ja tuotantoa varten. Wordly tallentaa vain salaustiivisteen jokaisesta avaimesta; koko arvo näytetään kerran luonnin yhteydessä.

• Nimeä avaimet ympäristön tai palvelun mukaan.
• Käytä ympäristömuuttujia tai hallittua salasäilöä.
• Peruuta avain välittömästi, jos se on saattanut paljastua.
• Pyöritä avaimia käyttämättä uudelleen vanhoja arvoja.
• Älä lähetä avaimia kyselymerkkijonoissa.

Vastauksen muoto

Onnistuneet vastaukset käyttävät huipputasoa data objekti ja voi sisältää a meta esine. Virheissä käytetään aina huipputasoa error esine vakaalla koneellisesti luettavalla code ja ihmisen luettava message.

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

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

Pidä request_id kun otat yhteyttä tukeen onnistuneen laskutetun pyynnön johdosta. JSON on UTF-8-koodattu, ja asiakkaiden tulee lähettää Accept: application/json.

Tuotannon päätepisteet

Sanaston päätepisteet

GET /v1/words/{word}

Palauttaa tarkan sanahaun. Käytä languages=tr,de,fr palauttaa vain pyydetyt käännökset. Luettelo tai käännetyt tietueet maksavat 1 pisteen; täysin rikastetut profiilit maksavat 5 krediittiä.

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

GET /v1/words/search

Hae sovelluksella q ja valinnainen level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor seuraavaan pyyntöön.

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

GET /v1/words/random

Palauttaa 1–20 satunnaista sanaa. Suodatusperuste level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

Etsii 1–50 ainutlaatuista sanaa yhdestä pyynnöstä. Vastaus säilyttää pyyntöjärjestyksen ja merkitsee jokaisen kohteen 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

Palauttaa kaikki 30 tuettua käyttöliittymä- ja API-viestien aluetta. Sanaston käännökset palautetaan vain, kun niitä on saatavilla. Tämä päätepiste on julkinen ja maksaa nolla krediittiä.

Hintarajoitus

Jokainen API-avain on rajoitettu 120 hyväksyttyyn pyyntöön liikkuvaa minuuttia kohti. Vastaukset sisältävät X-RateLimit-Limit ja X-RateLimit-Remaining. A 429 rate_limit_exceeded vastaus sisältää 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

Virheet

Suositeltu uudelleenyrityskäytäntö

Älä yritä uudelleen 401, 402, or 404 automaattisesti. Ohimenevälle 5xx Vastauksissa käytä eksponentiaalista perääntymistä värinän ja tiukan uudelleenyritysrajoituksen kanssa. Älä koskaan luo rajatonta uudelleenyrityssilmukkaa, koska jokainen hyväksytty todennettu pyyntö voi kuluttaa krediittejä.

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

Dart / Flutter

Älä lähetä Wordly-avainta Flutter-sovelluksen sisällä. Esimerkki kuuluu luotettuun Dart-taustajärjestelmään tai palvelintoimintoon.

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

Tuotannon tarkistuslista

• Proxy Wordly pyytää luotettavan taustajärjestelmän kautta.
• Aseta yhteyden ja vasteen aikakatkaisut.
• Kahva 401, 402, 404, and 5xx erikseen.
• Query GET /v1/account when your application needs the current balance.
• Kirjaa päätepiste, tila, latenssi ja request_id kirjaamatta API-avainta.
• Käytä erillisiä avaimia ympäristöä kohden ja kierrä niitä säännöllisesti.
• Cache stable vocabulary responses in your backend when appropriate.