Construa com API Wordly.

Início rápido

Crie uma conta gratuita, verifique seu e-mail usando o código de seis dígitos e copie a chave API mostrada uma vez no painel do desenvolvedor.

1. 1
   Crie uma conta

   Registre-se apenas com um endereço de e-mail e senha.

2. 2
   Verifique seu e-mail

   Digite o código enviado por [email protected]. A verificação concede 50 créditos gratuitos.

3. 3
   Armazene sua chave de API

   Copie o gerado wly_live_... chave e mantê-la em uma variável de ambiente do lado do servidor.

4. 4
   Faça uma solicitação de teste

   Ligue para o endpoint da conta para verificar a autenticação e ver o saldo restante.

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 base e controle de versão

Todos os endpoints de produção são servidos a partir do seguinte URL base com versão:

Quebrar respostas ou mudanças de comportamento usará uma nova versão do caminho. Campos aditivos podem ser introduzidos dentro v1, portanto, os clientes devem ignorar as propriedades de resposta que não reconhecem.

Autenticação

Endpoints autenticados exigem uma chave de API no HTTP Authorization cabeçalho usando o esquema Bearer.

Authorization: Bearer wly_live_your_api_key

Mensagens de API localizadas

Defina o idioma de resposta com ?lang=tr ou o padrão Accept-Language cabeçalho. Os parâmetros de consulta têm precedência. Cada resposta JSON declara a localidade selecionada em Content-Language e meta.lang. Os códigos de erro permanecem estáveis ​​em inglês para tratamento programático; apenas a mensagem legível por humanos é localizada.

curl "https://api.wordlyenglish.com/v1/account?lang=tr" \
  -H "Authorization: Bearer $WORDLY_API_KEY" \
  -H "Accept-Language: tr-TR"

Códigos de idioma suportados: 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.

Créditos e cobrança

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 e não processa a operação.

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

Ciclo de vida da chave de API

Crie chaves separadas para desenvolvimento, preparação e produção. O Wordly armazena apenas um hash criptográfico de cada chave; o valor completo é exibido uma vez na criação.

• Nomeie as chaves por ambiente ou serviço.
• Use variáveis de ambiente ou um armazenamento secreto gerenciado.
• Revogue uma chave imediatamente se ela tiver sido exposta.
• Gire as chaves sem reutilizar valores antigos.
• Não envie chaves em strings de consulta.

Formato de resposta

As respostas bem-sucedidas usam um nível superior data objeto e pode incluir um meta objeto. Erros sempre usam um nível superior error objeto com um legível por máquina estável code e um legível por humanos message.

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

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

Mantenha o request_id ao entrar em contato com o suporte sobre uma solicitação faturada com sucesso. JSON é codificado em UTF-8 e os clientes devem enviar Accept: application/json.

Pontos de extremidade de produção

Pontos finais de vocabulário

GET /v1/words/{word}

Retorna uma correspondência exata de palavras. Usar languages=tr,de,fr para retornar apenas as traduções solicitadas. Registros catalogados ou traduzidos custam 1 crédito; perfis totalmente enriquecidos custam 5 créditos.

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

GET /v1/words/search

Pesquisar com q e opcional level, part_of_speech, category, limite cursor. Os limites variam de 1 a 50. Aprovado meta.next_cursor na próxima solicitação.

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

GET /v1/words/random

Retorna de 1 a 20 palavras aleatórias. Filtrar por level, part_of_speech, ou category. Cada slot devolvido custa um crédito.

POST /v1/words/batch

Procura entre 1 e 50 palavras únicas em uma única solicitação. A resposta preserva a ordem da solicitação e marca cada item com 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

Retorna todas as 30 interfaces suportadas e localidades de mensagens de API. As traduções de vocabulário são retornadas somente quando disponíveis. Este endpoint é público e não custa nenhum crédito.

Limite de taxa

Cada chave de API é limitada a 120 solicitações aceitas por minuto contínuo. As respostas incluem X-RateLimit-Limit e X-RateLimit-Remaining. Um 429 rate_limit_exceeded a resposta inclui 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

Erros

Política de repetição recomendada

Não tente novamente 401, 402, ou 404 automaticamente. Para transitório 5xx respostas, use espera exponencial com jitter e um limite estrito de novas tentativas. Nunca crie um loop de repetição ilimitado porque cada solicitação autenticada aceita pode consumir créditos.

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

Pitão

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

Dardo / vibração

Não envie a chave do Wordly dentro de um aplicativo Flutter. O exemplo pertence a um back-end ou função de servidor confiável do 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']);
}

Lista de verificação de produção

• Solicitações proxy do Wordly por meio de um back-end confiável.
• Defina tempos limite de conexão e resposta.
• Alça 401, 402, 404e 5xx separadamente.
• Query GET /v1/account when your application needs the current balance.
• Registrar endpoint, status, latência e request_id sem registrar a chave API.
• Use chaves separadas por ambiente e alterne-as periodicamente.
• Cache stable vocabulary responses in your backend when appropriate.