Iniziare

Usa l'API HTTP di PolyLingo per tradurre testo semplice, Markdown, JSON o HTML mantenendo intatta la struttura. Questa guida copre l'endpoint di produzione, l'autenticazione e la tua prima richiesta riuscita.

URL base

Tutti gli esempi utilizzano l'API di produzione:

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

Ogni percorso qui sotto è relativo a questa base (ad esempio, POST /translate significa POST https://api.usepolylingo.com/v1/translate).

Se gestisci una tua istanza dell'API PolyLingo, sostituisci l'host con l'URL del tuo deployment e mantieni il prefisso /v1 a meno che tu non abbia configurato diversamente.

Autenticazione

Gli endpoint protetti si aspettano la tua chiave API nell'intestazione Authorization:

Authorization: Bearer <your_api_key>

Ottenere una chiave: Creane una nell'app PolyLingo sotto API keys. Vedi la chiave completa solo una volta—salvala in un posto sicuro (variabile d'ambiente o gestore segreti). Le chiavi possono essere revocate dalla stessa schermata.

Sicurezza: Tratta la chiave come una password. Preferisci chiamare l'API dal tuo server, non dal codice pubblico del browser, così la chiave non sarà mai esposta agli utenti.

Se l'intestazione manca, è errata, o la chiave è invalida o revocata, l'API risponde con 401 e error: "invalid_api_key".

Endpoint e chiavi

Nessuna chiave richiestaGET /health — controllo rapido dello stato
GET /languages — codici lingua supportati
Chiave richiestaPOST /translate — traduci contenuti
POST /translate/batch — traduci più elementi
POST /jobs — metti in coda una traduzione lunga (restituisce subito 202)
GET /jobs/:id — controlla lo stato del lavoro; include queue_position durante l'attesa
GET /usage — utilizzo per l'account autenticato

Prima richiesta (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 risposta riuscita include un oggetto translations (una voce per ogni lingua di destinazione richiesta) e un oggetto usage con il conteggio dei token.

Prima richiesta (Node.js)

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

Verifica che l'API sia raggiungibile

Non serve la chiave per la salute:

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

Dovresti vedere un piccolo payload JSON che indica che il servizio è attivo. Usa GET /languages per la lista dei codici che puoi passare come targets.

CORS e app browser

L'API potrebbe limitare quali origini browser possono chiamarla direttamente, così le chiavi non vengono usate da siti non affidabili. Le chiamate server-side (Node, Python, funzioni edge, il tuo backend) non sono limitate da CORS.

Per un'app single-page, il modello usuale è: il tuo frontend parla con il tuo backend, e il backend chiama PolyLingo con la chiave API.

Passi successivi

  • API reference — forme di richiesta e risposta, formati, errori e limiti.
Iniziare | PolyLingo | PolyLingo