Wordly API로 구축하세요.

빠른 시작

무료 계정을 만들고, 6자리 코드를 사용하여 이메일을 확인하고, 개발자 대시보드에 한 번 표시된 API 키를 복사하세요.

1. 1
   계정 만들기

   이메일 주소와 비밀번호만으로 등록하세요.

2. 2
   이메일을 확인하세요

   에서 보낸 코드를 입력하세요. [email protected]. Verification grants 50 free credits.

3. 3
   API 키 저장

   생성된 것을 복사하세요. wly_live_... 키를 저장하고 서버 측 환경 변수에 보관하세요.

4. 4
   테스트 요청하기

   계정 엔드포인트를 호출하여 인증을 확인하고 잔액을 확인하세요.

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 및 버전 관리

모든 프로덕션 엔드포인트는 다음 버전의 기본 URL에서 제공됩니다.

주요 응답 또는 동작 변경은 새로운 경로 버전을 사용합니다. 추가 필드는 다음에 도입될 수 있습니다. v1, so clients should ignore response properties they do not recognize.

인증

인증된 엔드포인트에는 HTTP에 API 키가 필요합니다. Authorization Bearer 방식을 사용하는 헤더입니다.

Authorization: Bearer wly_live_your_api_key

현지화된 API 메시지

다음으로 응답 언어를 설정하세요. ?lang=tr 아니면 표준 Accept-Language 헤더. 쿼리 매개변수가 우선 적용됩니다. 모든 JSON 응답은 선택한 로케일을 선언합니다. Content-Language 그리고 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"

지원되는 언어 코드: 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.

크레딧 및 청구

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 작업을 처리하지 않습니다.

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

개발, 스테이징, 프로덕션을 위한 별도의 키를 만듭니다. Wordly는 각 키의 암호화 해시만 저장합니다. 전체 값은 생성 시 한 번 표시됩니다.

• 환경이나 서비스별로 키 이름을 지정합니다.
• 환경 변수 또는 관리형 비밀 저장소를 사용하세요.
• 키가 노출된 경우 즉시 키를 취소하세요.
• 이전 값을 재사용하지 않고 키를 순환합니다.
• 쿼리 문자열에 키를 보내지 마십시오.

응답 형식

성공적인 응답은 최상위 수준을 사용합니다. data 개체이며 다음을 포함할 수 있습니다. meta 개체. 오류는 항상 최상위 수준을 사용합니다. error 기계가 읽을 수 있는 안정적인 객체 code 그리고 사람이 읽을 수 있는 message.

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

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

유지 request_id 성공적인 청구 요청에 대해 지원팀에 문의할 때. JSON은 UTF-8로 인코딩되어 클라이언트가 전송해야 합니다. Accept: application/json.

생산 엔드포인트

어휘 끝점

GET /v1/words/{word}

정확한 단어 일치를 반환합니다. 사용 languages=tr,de,fr 요청된 번역만 반환합니다. 카탈로그 또는 번역된 기록의 비용은 1크레딧입니다. 완전히 강화된 프로필의 비용은 5크레딧입니다.

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

GET /v1/words/search

다음으로 검색 q 그리고 선택사항 level, part_of_speech, category, limit, and cursor. Limits range from 1 to 50. Pass meta.next_cursor 다음 요청에 들어갑니다.

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

GET /v1/words/random

1~20개의 임의의 단어를 반환합니다. 필터링 기준 level, part_of_speech, or category. Each returned slot costs one credit.

POST /v1/words/batch

단일 요청에서 1~50개의 고유 단어를 찾습니다. 응답은 요청 순서를 유지하고 모든 항목에 다음을 표시합니다. 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

지원되는 인터페이스 및 API 메시지 로캘 30개를 모두 반환합니다. 어휘 번역은 사용 가능한 경우에만 반환됩니다. 이 엔드포인트는 공개되어 있으며 크레딧 비용은 0입니다.

비율 제한

각 API 키는 분당 120개의 요청으로 제한됩니다. 응답에는 다음이 포함됩니다. X-RateLimit-Limit 그리고 X-RateLimit-Remaining. A 429 rate_limit_exceeded 응답에는 다음이 포함됩니다. 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

오류

권장 재시도 정책

다시 시도하지 않음 401, 402, or 404 자동으로. 일시적인 경우 5xx 응답이 있는 경우 지터와 엄격한 재시도 제한이 있는 지수 백오프를 사용하세요. 승인된 각 요청이 크레딧을 소비할 수 있으므로 무제한 재시도 루프를 생성하지 마십시오.

자바스크립트/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);

파이썬

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

다트/플러터

Flutter 애플리케이션 내부에 Wordly 키를 제공하지 마세요. 이 예는 신뢰할 수 있는 Dart 백엔드 또는 서버 기능에 속합니다.

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

생산 체크리스트

• 신뢰할 수 있는 백엔드를 통해 Wordly 요청을 프록시합니다.
• 연결 및 응답 시간 초과를 설정합니다.
• 핸들 401, 402, 404, and 5xx 별도로.
• Query GET /v1/account when your application needs the current balance.
• 로그 엔드포인트, 상태, 대기 시간 및 request_id API 키를 기록하지 않고.
• 환경별로 별도의 키를 사용하고 주기적으로 교체하세요.
• Cache stable vocabulary responses in your backend when appropriate.