Mula

Gunakan PolyLingo HTTP API untuk menterjemah teks biasa, Markdown, JSON, atau HTML sambil mengekalkan struktur. Panduan ini merangkumi titik akhir produksi, pengesahan, dan permintaan pertama anda yang berjaya.

URL Asas

Semua contoh menggunakan API produksi:

Setiap laluan di bawah adalah relatif kepada asas itu (contohnya, POST /translate bermaksud POST https://api.usepolylingo.com/v1/translate).

Jika anda menjalankan instans API PolyLingo sendiri, gantikan hos dengan URL penyebaran anda dan kekalkan awalan /v1 melainkan anda telah mengkonfigurasinya sebaliknya.

Pengesahan

Titik akhir yang dilindungi mengharapkan kunci API anda dalam header Authorization:

Authorization: Bearer <your_api_key>

Mendapatkan kunci: Buat satu dalam aplikasi PolyLingo di bawah API keys. Anda hanya melihat kunci penuh sekali—simpan di tempat yang selamat (pembolehubah persekitaran atau pengurus rahsia). Kunci boleh dibatalkan dari skrin yang sama.

Keselamatan: Perlakukan kunci seperti kata laluan. Lebih baik memanggil API dari pelayan anda, bukan dari kod pelayar awam, supaya kunci tidak pernah didedahkan kepada pengguna.

Jika header hilang, salah, atau kunci tidak sah atau dibatalkan, API akan membalas dengan 401 dan error: "invalid_api_key".

Titik akhir dan kunci

Permintaan pertama (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"
  }'

Respons berjaya termasuk objek translations (satu entri bagi setiap bahasa sasaran yang anda minta) dan objek usage dengan kiraan token.

Permintaan pertama (Node.js)

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

Semak API boleh dicapai

Tiada kunci diperlukan untuk kesihatan:

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

Anda harus melihat muatan JSON kecil yang menunjukkan perkhidmatan berfungsi. Gunakan GET /languages untuk senarai kod yang boleh anda gunakan sebagai targets.

CORS dan aplikasi pelayar

API mungkin mengehadkan asal pelayar mana yang boleh memanggilnya secara langsung, supaya kunci tidak digunakan dari tapak yang tidak dipercayai. Panggilan server-side (Node, Python, fungsi edge, backend anda) tidak terhad oleh CORS.

Untuk aplikasi halaman tunggal, corak biasa adalah: frontend anda bercakap dengan backend anda, dan backend anda memanggil PolyLingo dengan kunci API.

Langkah seterusnya

• Rujukan API — bentuk permintaan dan respons, format, ralat, dan had.