Construya con la API de Wordly.

Inicio rápido

Cree una cuenta gratuita, verifique su correo electrónico usando el código de seis dígitos y copie la clave API que se muestra una vez en su panel de desarrollador.

1. 1
   Crea una cuenta

   Regístrese solo con una dirección de correo electrónico y contraseña.

2. 2
   Verifica tu correo electrónico

   Introduce el código enviado por [email protected]. La verificación otorga 50 créditos gratis.

3. 3
   Guarde su clave API

   Copiar lo generado wly_live_... key y guárdela en una variable de entorno del lado del servidor.

4. 4
   Hacer una solicitud de prueba

   Llame al punto final de la cuenta para verificar la autenticación y ver el 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 y versiones

Todos los puntos finales de producción se sirven desde la siguiente URL base versionada:

Los cambios importantes en la respuesta o el comportamiento utilizarán una nueva versión de ruta. Se podrán introducir campos adicionales dentro v1, por lo que los clientes deben ignorar las propiedades de respuesta que no reconocen.

Autenticación

Los puntos finales autenticados requieren una clave API en HTTP Authorization encabezado usando el esquema Portador.

Authorization: Bearer wly_live_your_api_key

Mensajes API localizados

Configure el idioma de respuesta con ?lang=tr o el estándar Accept-Language encabezado. Los parámetros de consulta tienen prioridad. Cada respuesta JSON declara la configuración regional seleccionada en Content-Language y meta.lang. Los códigos de error permanecen estables en inglés para el manejo programático; sólo se localiza el mensaje legible por humanos.

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

Códigos de idioma admitidos: 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 y facturación

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 y no procesa la operación.

{
  "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 de la clave API

Cree claves independientes para desarrollo, puesta en escena y producción. Wordly almacena sólo un hash criptográfico de cada clave; el valor completo se muestra una vez en el momento de la creación.

• Nombrar claves por entorno o servicio.
• Utilice variables de entorno o un almacén de secretos administrado.
• Revocar una clave inmediatamente si pudo haber quedado expuesta.
• Gire las claves sin reutilizar valores antiguos.
• No envíe claves en cadenas de consulta.

Formato de respuesta

Las respuestas exitosas utilizan un nivel superior data objeto y puede incluir un meta objeto. Los errores siempre utilizan un nivel superior error objeto con una lectura estable por máquina. code y legible por humanos message.

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

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

Mantenga el request_id al comunicarse con soporte sobre una solicitud facturada exitosamente. JSON está codificado en UTF-8 y los clientes deben enviar Accept: application/json.

Puntos finales de producción

Puntos finales de vocabulario

GET /v1/words/{word}

Devuelve una coincidencia exacta de palabras. uso languages=tr,de,fr para devolver sólo las traducciones solicitadas. El catálogo o los registros traducidos cuestan 1 crédito; Los perfiles completamente enriquecidos cuestan 5 créditos.

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

GET /v1/words/search

Buscar con q y opcional level, part_of_speech, category, limit, y cursor. Los límites varían de 1 a 50. Pasar meta.next_cursor en la siguiente solicitud.

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

GET /v1/words/random

Devuelve entre 1 y 20 palabras aleatorias. Filtrar por level, part_of_speech, o category. Cada espacio devuelto cuesta un crédito.

POST /v1/words/batch

Busca entre 1 y 50 palabras únicas en una sola solicitud. La respuesta conserva el orden de la solicitud y marca cada elemento con 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

Devuelve las 30 interfaces compatibles y configuraciones regionales de mensajes API. Las traducciones de vocabulario se devuelven solo cuando están disponibles. Este punto final es público y no cuesta créditos.

Límite de tarifa

Cada clave API está limitada a 120 solicitudes aceptadas por minuto consecutivo. Las respuestas incluyen X-RateLimit-Limit y X-RateLimit-Remaining. un 429 rate_limit_exceeded la respuesta incluye 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

Errores

Política de reintento recomendada

no lo vuelvas a intentar 401, 402, o 404 automáticamente. Para transitorio 5xx respuestas, utilice un retroceso exponencial con fluctuación y un límite estricto de reintentos. Nunca cree un ciclo de reintento ilimitado porque cada solicitud autenticada aceptada puede consumir créditos.

JavaScript/Nodo.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ón

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 / Aleteo

No envíe la clave de Wordly dentro de una aplicación Flutter. El ejemplo pertenece a una función de servidor o backend confiable de 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 verificación de producción

• Solicitudes proxy de Wordly a través de un backend confiable.
• Establezca tiempos de espera de conexión y respuesta.
• Manejar 401, 402, 404, y 5xx por separado.
• Query GET /v1/account when your application needs the current balance.
• Registrar punto final, estado, latencia y request_id sin registrar la clave API.
• Utilice claves separadas por entorno y rótelas periódicamente.
• Cache stable vocabulary responses in your backend when appropriate.