Bắt đầu

Sử dụng PolyLingo HTTP API để dịch văn bản thuần túy, Markdown, JSON, hoặc HTML trong khi giữ nguyên cấu trúc. Hướng dẫn này bao gồm điểm cuối sản xuất, xác thực và yêu cầu thành công đầu tiên của bạn.

URL cơ sở

Tất cả ví dụ sử dụng API sản xuất:

URL
Sản xuấthttps://api.usepolylingo.com/v1

Mỗi đường dẫn dưới đây là tương đối so với cơ sở đó (ví dụ, POST /translate nghĩa là POST https://api.usepolylingo.com/v1/translate).

Nếu bạn chạy phiên bản PolyLingo API riêng của bạn, hãy thay thế host bằng URL triển khai của bạn và giữ tiền tố /v1 trừ khi bạn đã cấu hình khác.

Xác thực

Các điểm cuối được bảo vệ yêu cầu khóa API của bạn trong header Authorization:

Authorization: Bearer <your_api_key>

Lấy khóa: Tạo một khóa trong ứng dụng PolyLingo dưới mục API keys. Bạn chỉ thấy khóa đầy đủ một lần—hãy lưu nó ở nơi an toàn (biến môi trường hoặc trình quản lý bí mật). Khóa có thể bị thu hồi từ cùng màn hình.

Bảo mật: Xử lý khóa như mật khẩu. Ưu tiên gọi API từ máy chủ của bạn, không phải từ mã trình duyệt công khai, để khóa không bao giờ bị lộ với người dùng.

Nếu header bị thiếu, sai hoặc khóa không hợp lệ hoặc bị thu hồi, API sẽ phản hồi với 401 và error: "invalid_api_key".

Điểm cuối và khóa

Không cần khóaGET /health — kiểm tra thời gian hoạt động nhanh
GET /languages — mã ngôn ngữ được hỗ trợ
Cần khóaPOST /translate — dịch nội dung
POST /translate/batch — dịch nhiều mục
POST /jobs — xếp hàng dịch dài hạn (trả về 202 ngay lập tức)
GET /jobs/:id — kiểm tra trạng thái công việc; bao gồm queue_position khi chờ
GET /usage — sử dụng cho tài khoản đã xác thực

Yêu cầu đầu tiên (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"
  }'

Phản hồi thành công bao gồm một đối tượng translations (một mục cho mỗi ngôn ngữ mục tiêu bạn yêu cầu) và một đối tượng usage với số lượng token.

Yêu cầu đầu tiên (Node.js)

Node.js 18+ bao gồm 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)

Kiểm tra API có thể truy cập được

Không cần khóa cho kiểm tra sức khỏe:

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

Bạn sẽ thấy một payload JSON nhỏ cho biết dịch vụ đang hoạt động. Sử dụng GET /languages để lấy danh sách mã bạn có thể truyền làm targets.

CORS và ứng dụng trình duyệt

API có thể giới hạn những nguồn trình duyệt nào có thể gọi trực tiếp, để khóa không bị sử dụng từ các trang không đáng tin cậy. Các cuộc gọi phía máy chủ (Node, Python, hàm edge, backend của bạn) không bị giới hạn bởi CORS.

Đối với một ứng dụng một trang, mẫu thông thường là: frontend của bạn nói chuyện với backend của bạn, và backend gọi PolyLingo với khóa API.

Bước tiếp theo

  • Tham khảo API — hình dạng yêu cầu và phản hồi, định dạng, lỗi và giới hạn.
Bắt đầu | PolyLingo | PolyLingo