Rujukan API

Rujukan lengkap untuk setiap titik akhir, bentuk permintaan dan respons, kod ralat, dan had kadar.

Had dan tingkah laku

Peruntukan token bulanan (peringkat percuma): Sebelum memanggil model, API menganggarkan token sebagai kira-kira ceil(content_length / 4) × (number_of_targets + 1) dan, untuk peringkat free sahaja, menolak permintaan dengan 429 / token_limit_reached jika anggaran melebihi baki peruntukan bulanan (lalai 100000). Tahap berbayar tidak disekat oleh pemeriksaan awal ini; penggunaan masih direkodkan.

Had kadar: Apabila Redis dikonfigurasikan, had per minit dikenakan mengikut tahap: percuma 5, permulaan 30, pertumbuhan 60, skala 120, perusahaan tanpa had. Apabila had dicapai, respons adalah 429 dengan error: "rate_limit_reached". Jika Redis tidak dikonfigurasikan, had kadar diabaikan.

Respons had kadar yang berjaya mungkin termasuk X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GET /health

Tiada pengesahan.

Respons 200

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

GET /languages

Tiada pengesahan.

Mengembalikan senarai kanonik bahasa yang disokong (kod, nama paparan, bendera RTL). Terdapat 43 entri — 36 bahasa asas dan 7 varian serantau. Varian serantau menggunakan subtag rantau BCP-47 (contoh: fr-CA, pt-BR, es-MX). Kod dari titik akhir ini adalah satu-satunya nilai yang diterima dalam targets pada titik akhir terjemahan.

Respons 200

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

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

POST /translate

Memerlukan Authorization: Bearer <api_key>.

Menterjemah satu rentetan content ke setiap bahasa yang disenaraikan dalam targets. Respons adalah objek JSON tunggal yang kuncinya adalah kod bahasa yang diminta dan nilainya adalah rentetan terjemahan.

Badan 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 hanya muncul apabila format diabaikan dan pengesanan automatik 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 setiap item). Jika mana-mana item gagal, API mengembalikan 500 dan tidak mengembalikan hasil separa untuk permintaan itu.

Badan 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>.

Menyusun kerja terjemahan dan mengembalikan segera dengan job_id. Terjemahan berjalan di latar belakang — tiada risiko tamat masa HTTP tanpa mengira saiz kandungan. Poll GET /jobs/:id untuk keputusan.

Gunakan titik akhir ini sebagai ganti POST /translate apabila menterjemah dokumen besar (Markdown panjang, banyak bahasa sasaran) di mana tempoh permintaan mungkin melebihi tamat masa klien HTTP atau proksi anda.

Badan permintaan

Respons 202

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

GET /jobs/:id

Memerlukan Authorization: Bearer <api_key>.

Poll status kerja yang dihantar melalui POST /jobs. Poll setiap 5–10 saat. Kerja dimiliki oleh pengguna yang menghantar — 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 mengambilnya). queue_position (bermula 1) adalah berapa banyak kerja pending atau processing yang dibuat sebelum ini — gunakan untuk UI kemajuan. Diabaikan apabila pertanyaan kiraan 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. Hantar
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) }
  // Pilihan: tunjukkan kemajuan (queue_position bermula 1, diabaikan jika tidak beratur)
  if (job.queue_position != null) console.log(`Queue position: ${job.queue_position}`)
}

GET /usage

Memerlukan Authorization: Bearer <api_key> (carian kunci standard — bukan laluan bypass dalaman sahaja).

Mengembalikan penggunaan token untuk bulan kalendar semasa bagi pengguna yang disahkan.

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 (peruntukan tanpa had dalam laporan).

Format kandungan

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

RTL dan arah dalam aplikasi anda

Untuk output plain dan markdown, API hanya mengembalikan teks terjemahan — ia tidak menambah dir="rtl" atau elemen pembungkus. Tetapkan arah teks dalam UI anda (CSS direction, atribut dir elemen induk, atau susun atur i18n rangka kerja anda) apabila memaparkan bahasa Arab, Ibrani, atau Parsi.

Untuk format html, markup terjemahan mungkin termasuk dir="rtl" jika sesuai untuk sasaran RTL.

Respons ralat

Ralat adalah JSON apabila boleh:

{
  "error": "invalid_request",
  "message": "Perincian yang boleh dibaca manusia"
}

GET /usage mungkin mengembalikan 500 dengan mesej generik jika pertanyaan Supabase gagal.