Comenzando

Utiliza la API HTTP de PolyLingo para traducir texto plano, Markdown, JSON o HTML manteniendo la estructura intacta. Esta guía cubre el endpoint de producción, la autenticación y tu primera solicitud exitosa.

URL base

Todos los ejemplos usan la API de producción:

Cada ruta a continuación es relativa a esa base (por ejemplo, POST /translate significa POST https://api.usepolylingo.com/v1/translate).

Si ejecutas tu propia instancia de la API PolyLingo, reemplaza el host con la URL de tu despliegue y mantén el prefijo /v1 a menos que hayas configurado lo contrario.

Autenticación

Los endpoints protegidos esperan tu clave API en el encabezado Authorization:

Authorization: Bearer <your_api_key>

Obtener una clave: Crea una en la aplicación PolyLingo bajo API keys. Solo ves la clave completa una vez—guárdala en un lugar seguro (variable de entorno o gestor de secretos). Las claves pueden ser revocadas desde la misma pantalla.

Seguridad: Trata la clave como una contraseña. Prefiere llamar a la API desde tu servidor, no desde código público en el navegador, para que la clave nunca se exponga a los usuarios.

Si falta el encabezado, es incorrecto o la clave es inválida o revocada, la API responde con 401 y error: "invalid_api_key".

Endpoints y claves

Primera solicitud (cURL)

export POLYLINGO_API_KEY="pl_your_key_here"

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello\n\nThis is **bold**.",
    "format": "markdown",
    "targets": ["es", "fr"],
    "model": "standard"
  }'

Una respuesta exitosa incluye un objeto translations (una entrada por cada idioma destino que solicitaste) y un objeto usage con conteos de tokens.

Primera solicitud (Node.js)

Node.js 18+ incluye fetch:

const API_KEY = process.env.POLYLINGO_API_KEY
const res = await fetch('https://api.usepolylingo.com/v1/translate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    content: '# Hello\n\n**Bold** text.',
    format: 'markdown',
    targets: ['de', 'ja'],
    model: 'standard',
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error}: ${data.message}`)
console.log(data.translations)

Verificar que la API es accesible

No se necesita clave para health:

curl -sS "https://api.usepolylingo.com/v1/health"

Deberías ver una pequeña carga JSON indicando que el servicio está activo. Usa GET /languages para la lista de códigos que puedes pasar como targets.

CORS y aplicaciones en navegador

La API puede restringir qué orígenes de navegador pueden llamarla directamente, para que las claves no se usen desde sitios no confiables. Las llamadas del lado servidor (Node, Python, funciones edge, tu backend) no están limitadas por CORS.

Para una aplicación de una sola página, el patrón usual es: tu frontend habla con tu backend, y tu backend llama a PolyLingo con la clave API.

Próximos pasos

• Referencia de API — formas de solicitud y respuesta, formatos, errores y límites.