Byg med Wordly API.

Quickstart

Opret en gratis konto, bekræft din e-mail ved hjælp af den sekscifrede kode, og kopier API-nøglen, der vises én gang i dit udvikler-dashboard.

1. 1
   Opret en konto

   Tilmeld dig kun med en e-mailadresse og adgangskode.

2. 2
   Bekræft din e-mail

   Indtast koden sendt af [email protected]. Verification grants 50 free credits.

3. 3
   Gem din API-nøgle

   Kopier den genererede wly_live_... nøgle og hold den i en miljøvariabel på serversiden.

4. 4
   Lav en testanmodning

   Ring til kontoslutpunktet for at bekræfte godkendelsen og se den resterende 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" }
}

Basis URL og versionering

Alle produktionsendepunkter betjenes fra følgende versionerede basis-URL:

Brydende svar eller adfærdsændringer vil bruge en ny stiversion. Additive felter kan indføres inden for v1, so clients should ignore response properties they do not recognize.

Autentificering

Godkendte slutpunkter kræver en API-nøgle i HTTP Authorization header ved hjælp af Bærer-skemaet.

Authorization: Bearer wly_live_your_api_key

Lokaliserede API-meddelelser

Indstil svarsproget med ?lang=tr eller standarden Accept-Language overskrift. Forespørgselsparametre har forrang. Hvert JSON-svar erklærer den valgte lokalitet i Content-Language og 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"

Understøttede sprogkoder: 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.

Kreditering og fakturering

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 og behandler ikke operationen.

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

Opret separate nøgler til udvikling, iscenesættelse og produktion. Wordly gemmer kun en kryptografisk hash af hver nøgle; den fulde værdi vises én gang ved oprettelsen.

• Navngiv nøgler efter miljø eller tjeneste.
• Brug miljøvariabler eller en administreret hemmelig butik.
• Tilbagekald straks en nøgle, hvis den kan være blevet blotlagt.
• Roter nøgler uden at genbruge gamle værdier.
• Send ikke nøgler i forespørgselsstrenge.

Svarformat

Succesfulde svar bruger et topniveau data genstand og kan omfatte en meta objekt. Fejl bruger altid et topniveau error objekt med en stabil maskinlæsbar code og en menneskelig læsbar message.

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

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

Behold request_id når du kontakter support om en vellykket faktureret anmodning. JSON er UTF-8-kodet, og klienter skal sende Accept: application/json.

Produktions slutpunkter

Ordforråds endepunkter

GET /v1/words/{word}

Returnerer et nøjagtigt ordmatch. Brug languages=tr,de,fr kun at returnere ønskede oversættelser. Katalog eller oversatte poster koster 1 kredit; fuldt berigede profiler koster 5 kreditter.

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

GET /v1/words/search

Søg med q og valgfrit level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor til næste anmodning.

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

GET /v1/words/random

Returnerer 1-20 tilfældige ord. Filtrer efter level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

Slår op mellem 1 og 50 unikke ord i en enkelt anmodning. Svaret bevarer anmodningsrækkefølgen og markerer hver vare med 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

Returnerer alle 30 understøttede grænseflader og API-meddelelseslokaliteter. Ordforrådsoversættelser returneres kun, når de er tilgængelige. Dette endepunkt er offentligt og koster nul kreditter.

Satsgrænse

Hver API-nøgle er begrænset til 120 accepterede anmodninger pr. rullende minut. Svar inkluderer X-RateLimit-Limit og X-RateLimit-Remaining. A 429 rate_limit_exceeded svar omfatter 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

Fejl

Anbefalet politik for genforsøg

Forsøg ikke igen 401, 402, or 404 automatisk. Til forbigående 5xx svar, brug eksponentiel backoff med jitter og en streng genforsøgsgrænse. Opret aldrig en ubegrænset genforsøgsløkke, fordi hver accepteret godkendt anmodning kan forbruge kreditter.

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

Send ikke Wordly-nøglen i en Flutter-applikation. Eksemplet hører hjemme i en pålidelig Dart-backend eller serverfunktion.

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

Produktionstjekliste

• Proxy Wordly-anmodninger via en betroet backend.
• Indstil forbindelse og svar timeouts.
• Håndtag 401, 402, 404, and 5xx separat.
• Query GET /v1/account when your application needs the current balance.
• Log slutpunkt, status, latens og request_id uden at logge API-nøglen.
• Brug separate nøgler pr. miljø og roter dem med jævne mellemrum.
• Cache stable vocabulary responses in your backend when appropriate.