Premiers pas

Utilisez l'API HTTP PolyLingo pour traduire du texte brut, du Markdown, du JSON ou du HTML tout en conservant la structure intacte. Ce guide couvre le point de terminaison de production, l'authentification et votre première requête réussie.

URL de base

Tous les exemples utilisent l'API de production :

URL
Productionhttps://api.usepolylingo.com/v1

Chaque chemin ci-dessous est relatif à cette base (par exemple, POST /translate signifie POST https://api.usepolylingo.com/v1/translate).

Si vous exécutez votre propre instance de l'API PolyLingo, remplacez l'hôte par l'URL de votre déploiement et conservez le préfixe /v1 sauf configuration contraire.

Authentification

Les points de terminaison protégés attendent votre clé API dans l'en-tête Authorization :

Authorization: Bearer <your_api_key>

Obtenir une clé : Créez-en une dans l'application PolyLingo sous API keys. Vous ne voyez la clé complète qu'une seule fois—stockez-la en lieu sûr (variable d'environnement ou gestionnaire de secrets). Les clés peuvent être révoquées depuis le même écran.

Sécurité : Traitez la clé comme un mot de passe. Préférez appeler l'API depuis votre serveur, pas depuis du code public dans le navigateur, afin que la clé ne soit jamais exposée aux utilisateurs.

Si l'en-tête est manquant, incorrect ou si la clé est invalide ou révoquée, l'API répond avec 401 et error: "invalid_api_key".

Points de terminaison et clés

Pas de clé requiseGET /health — vérification rapide de disponibilité
GET /languages — codes de langues supportés
Clé requisePOST /translate — traduire du contenu
POST /translate/batch — traduire plusieurs éléments
POST /jobs — mettre en file une traduction longue (retourne 202 immédiatement)
GET /jobs/:id — interroger le statut du travail ; inclut queue_position pendant l'attente
GET /usage — utilisation pour le compte authentifié

Première requête (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"
  }'

Une réponse réussie inclut un objet translations (une entrée par langue cible demandée) et un objet usage avec les comptes de jetons.

Première requête (Node.js)

Node.js 18+ inclut 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)

Vérifier que l'API est accessible

Aucune clé n'est nécessaire pour health :

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

Vous devriez voir une petite charge JSON indiquant que le service est opérationnel. Utilisez GET /languages pour la liste des codes que vous pouvez passer en targets.

CORS et applications navigateur

L'API peut restreindre quels origines de navigateur peuvent l'appeler directement, afin que les clés ne soient pas utilisées depuis des sites non fiables. Les appels côté serveur (Node, Python, fonctions edge, votre backend) ne sont pas limités par CORS.

Pour une application monopage, le schéma habituel est : votre frontend communique avec votre backend, et votre backend appelle PolyLingo avec la clé API.

Étapes suivantes

  • Référence API — formes des requêtes et réponses, formats, erreurs et limites.
Commencer | PolyLingo | PolyLingo