Memulai

Gunakan PolyLingo HTTP API untuk menerjemahkan teks biasa, Markdown, JSON, atau HTML sambil menjaga struktur tetap utuh. Panduan ini mencakup endpoint produksi, autentikasi, dan permintaan sukses pertama Anda.

URL Dasar

Semua contoh menggunakan API produksi:

Setiap jalur di bawah ini relatif terhadap basis tersebut (misalnya, POST /translate berarti POST https://api.usepolylingo.com/v1/translate).

Jika Anda menjalankan instance PolyLingo API milik Anda sendiri, ganti host dengan URL deployment Anda dan pertahankan prefix /v1 kecuali Anda telah mengonfigurasi sebaliknya.

Autentikasi

Endpoint yang dilindungi mengharapkan kunci API Anda di header Authorization:

Authorization: Bearer <your_api_key>

Mendapatkan kunci: Buat satu di aplikasi PolyLingo di bawah API keys. Anda hanya melihat kunci lengkap sekali—simpan di tempat yang aman (variabel lingkungan atau pengelola rahasia). Kunci dapat dicabut dari layar yang sama.

Keamanan: Perlakukan kunci seperti kata sandi. Lebih baik memanggil API dari server Anda, bukan dari kode browser publik, agar kunci tidak pernah terekspos ke pengguna.

Jika header hilang, salah, atau kunci tidak valid atau dicabut, API merespons dengan 401 dan error: "invalid_api_key".

Endpoint 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 yang berhasil mencakup objek translations (satu entri per bahasa target yang Anda minta) dan objek usage dengan hitungan token.

Permintaan pertama (Node.js)

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

Periksa bahwa API dapat dijangkau

Tidak perlu kunci untuk health:

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

Anda harus melihat payload JSON kecil yang menunjukkan layanan aktif. Gunakan GET /languages untuk daftar kode yang dapat Anda berikan sebagai targets.

CORS dan aplikasi browser

API mungkin membatasi origin browser mana yang dapat memanggilnya langsung, sehingga kunci tidak digunakan dari situs yang tidak dipercaya. Panggilan server-side (Node, Python, fungsi edge, backend Anda) tidak dibatasi oleh CORS.

Untuk aplikasi single-page, pola umum adalah: frontend Anda berbicara ke backend Anda, dan backend Anda memanggil PolyLingo dengan kunci API.

Langkah selanjutnya

• API reference — bentuk permintaan dan respons, format, kesalahan, dan batasan.