Referensi API

Referensi lengkap untuk setiap endpoint, bentuk permintaan dan respons, kode kesalahan, dan batas laju.

Batas dan perilaku

Kuota token bulanan (tingkat gratis): Sebelum memanggil model, API memperkirakan token kira-kira ceil(content_length / 4) × (number_of_targets + 1) dan, hanya untuk tingkat free, menolak permintaan dengan 429 / token_limit_reached jika perkiraan melebihi kuota bulanan yang tersisa (default 100000). Tingkat berbayar tidak diblokir oleh pemeriksaan awal ini; penggunaan tetap dicatat.

Batas laju: Saat Redis dikonfigurasi, batas per menit berlaku berdasarkan tingkat: free 5, starter 30, growth 60, scale 120, enterprise tanpa batas. Saat mencapai batas, respons adalah 429 dengan error: "rate_limit_reached". Jika Redis tidak dikonfigurasi, pembatasan laju dilewati.

Respons yang berhasil dengan batas laju dapat menyertakan X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GET /health

Tanpa autentikasi.

Respons 200

{
  "status": "ok",
  "timestamp": "2025-03-23T12:00:00.000Z"
}

GET /languages

Tanpa autentikasi.

Mengembalikan daftar kanonik bahasa yang didukung (kode, nama tampilan, flag RTL). Ada 43 entri — 36 bahasa dasar dan 7 varian regional. Varian regional menggunakan subtag wilayah BCP-47 (mis. fr-CA, pt-BR, es-MX). Kode dari endpoint ini adalah satu-satunya nilai yang diterima dalam targets pada endpoint terjemahan.

Respons 200

{
  "languages": [
    { "code": "en", "name": "English", "rtl": false },
    { "code": "ar", "name": "Arabic", "rtl": true }
  ]
}

Daftar langsung juga tersedia melalui GET /languages — lihat di bawah.

POST /translate

Memerlukan Authorization: Bearer <api_key>.

Menerjemahkan satu string content ke setiap bahasa yang tercantum dalam targets. Respons adalah objek JSON tunggal yang kuncinya adalah kode bahasa yang diminta dan nilainya adalah string terjemahan.

Body permintaan

Respons 200

{
  "translations": {
    "es": "...",
    "fr": "..."
  },
  "usage": {
    "input_tokens": 120,
    "output_tokens": 340,
    "total_tokens": 460,
    "model": "standard",
    "detected_format": "markdown",
    "detection_confidence": 0.95
  }
}

detected_format dan detection_confidence muncul hanya ketika format dihilangkan dan deteksi otomatis dijalankan.

Contoh (cURL)

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "{\"title\":\"Hello\"}",
    "format": "json",
    "targets": ["fr", "de"]
  }'

Contoh (Python 3)

pip install requests

import os, requests

url = "https://api.usepolylingo.com/v1/translate"
headers = {
    "Authorization": f"Bearer {os.environ['POLYLINGO_API_KEY']}",
    "Content-Type": "application/json",
}
r = requests.post(url, json={
    "content": "<p>Hello <strong>world</strong></p>",
    "format": "html",
    "targets": ["es"],
}, timeout=120)
r.raise_for_status()
print(r.json()["translations"]["es"])

POST /translate/batch

Memerlukan Authorization: Bearer <api_key>.

Memproses setiap item secara berurutan (satu panggilan model per item). Jika ada item yang gagal, API mengembalikan 500 dan tidak mengembalikan hasil parsial untuk permintaan tersebut.

Body permintaan

Respons 200

{
  "results": [
    { "id": "welcome", "translations": { "fr": "...", "de": "..." } },
    { "id": "goodbye", "translations": { "fr": "...", "de": "..." } }
  ],
  "usage": {
    "total_tokens": 900,
    "input_tokens": 400,
    "output_tokens": 500,
    "model": "standard"
  }
}

Contoh

curl -sS -X POST "https://api.usepolylingo.com/v1/translate/batch" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "a", "content": "Hello", "format": "plain" },
      { "id": "b", "content": "## Title", "format": "markdown" }
    ],
    "targets": ["es", "it"]
  }'

POST /jobs

Memerlukan Authorization: Bearer <api_key>.

Mengantri pekerjaan terjemahan dan mengembalikan segera dengan job_id. Terjemahan berjalan di latar belakang — tanpa risiko timeout HTTP terlepas dari ukuran konten. Poll GET /jobs/:id untuk hasil.

Gunakan endpoint ini sebagai pengganti POST /translate saat menerjemahkan dokumen besar (Markdown panjang, banyak bahasa target) di mana durasi permintaan mungkin melebihi timeout klien HTTP atau proxy Anda.

Body permintaan

Respons 202

{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "created_at": "2025-03-23T12:00:00.000Z"
}

GET /jobs/:id

Memerlukan Authorization: Bearer <api_key>.

Memantau status pekerjaan yang dikirim melalui POST /jobs. Poll setiap 5–10 detik. Pekerjaan dimiliki oleh pengguna yang mengirimnya — pengguna lain menerima 404.

Respons (pending / processing)

{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "created_at": "2025-03-23T12:00:00.000Z",
  "updated_at": "2025-03-23T12:00:00.000Z",
  "completed_at": null,
  "queue_position": 3
}

status adalah pending (menunggu pekerja) atau processing (pekerja telah mengklaimnya). queue_position (berbasis 1) adalah berapa banyak pekerjaan pending atau processing yang dibuat sebelum ini — gunakan untuk UI progres. Dihilangkan saat query hitungan gagal.

Respons (completed)

{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "created_at": "2025-03-23T12:00:00.000Z",
  "updated_at": "2025-03-23T12:00:02.000Z",
  "completed_at": "2025-03-23T12:00:02.000Z",
  "translations": {
    "es": "...",
    "fr": "..."
  },
  "usage": {
    "input_tokens": 120,
    "output_tokens": 340,
    "total_tokens": 460,
    "model": "standard"
  }
}

Respons (failed)

{
  "job_id": "a1b2c3d4-...",
  "status": "failed",
  "error": "Model returned invalid JSON"
}

Contoh (JavaScript)

const API = 'https://api.usepolylingo.com/v1'
const headers = {
  'Authorization': `Bearer ${process.env.POLYLINGO_API_KEY}`,
  'Content-Type': 'application/json',
}

// 1. Kirim
const submit = await fetch(`${API}/jobs`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ content: longMarkdown, format: 'markdown', targets: ['de', 'fr'] }),
})
const { job_id } = await submit.json()

// 2. Poll
while (true) {
  await new Promise(r => setTimeout(r, 10_000))
  const poll = await fetch(`${API}/jobs/${job_id}`, { headers })
  const job = await poll.json()
  if (job.status === 'completed') { console.log(job.translations); break }
  if (job.status === 'failed')    { throw new Error(job.error) }
  // Opsional: tampilkan progres (queue_position berbasis 1, dihilangkan saat tidak dalam antrean)
  if (job.queue_position != null) console.log(`Queue position: ${job.queue_position}`)
}

GET /usage

Memerlukan Authorization: Bearer <api_key> (pencarian kunci standar — bukan jalur bypass internal saja).

Mengembalikan penggunaan token untuk bulan kalender saat ini untuk pengguna yang diautentikasi.

Respons 200

{
  "period_start": "2025-03-01T00:00:00.000Z",
  "period_end": "2025-03-31T23:59:59.000Z",
  "tokens_used": 12000,
  "tokens_included": 100000,
  "tokens_remaining": 88000,
  "overage_tokens": 0,
  "tier": "free"
}

tokens_included dan tokens_remaining adalah null untuk enterprise (kuota tak terbatas dalam pelaporan).

Format konten

Nilai format yang didukung: plain, markdown, json, html.

RTL dan arah di aplikasi Anda

Untuk output plain dan markdown, API hanya mengembalikan teks terjemahan — tidak menambahkan dir="rtl" atau elemen pembungkus. Tetapkan arah teks di UI Anda (CSS direction, atribut dir elemen induk, atau layout i18n framework Anda) saat menampilkan bahasa Arab, Ibrani, atau Persia.

Untuk format html, markup terjemahan dapat menyertakan dir="rtl" di tempat yang sesuai untuk target RTL.

Respons kesalahan

Kesalahan berupa JSON bila memungkinkan:

{
  "error": "invalid_request",
  "message": "Detail yang dapat dibaca manusia"
}

GET /usage dapat mengembalikan 500 dengan pesan umum jika query Supabase gagal.