入门指南

使用 PolyLingo HTTP API 翻译纯文本、Markdown、JSON或HTML，同时保持结构完整。本指南涵盖生产端点、身份验证以及您的第一个成功请求。

基础 URL

所有示例均使用生产 API：

URL
生产环境https://api.usepolylingo.com/v1

以下每个路径均相对于该基础 URL（例如，POST /translate 即指 POST https://api.usepolylingo.com/v1/translate）。

如果您运行自己的 PolyLingo API 实例，请将主机替换为您的部署 URL，并保持 /v1 前缀，除非您另有配置。

身份验证

受保护的端点期望您在 Authorization 头中提供 API 密钥：

Authorization: Bearer <your_api_key>

获取密钥： 在 PolyLingo 应用的 API keys 下创建一个。您只会看到完整密钥一次——请妥善保存（环境变量或秘密管理器）。密钥可在同一界面撤销。

安全性： 将密钥视为密码。建议从您的服务器调用 API，而非公开的浏览器代码，以确保密钥不会暴露给用户。

如果缺少头部、错误或密钥无效或已撤销，API 会返回 401 和 error: "invalid_api_key"。

端点和密钥

无需密钥GET /health — 快速运行状态检查
GET /languages — 支持的语言代码
需要密钥POST /translate — 翻译内容
POST /translate/batch — 批量翻译
POST /jobs — 排队长时间运行的翻译（立即返回 202）
GET /jobs/:id — 查询任务状态；等待时包含 queue_position
GET /usage — 已认证账户的使用情况

第一次请求（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"
  }'

成功响应包含一个 translations 对象（每个目标语言一个条目）和一个带有令牌计数的 usage 对象。

第一次请求（Node.js）

Node.js 18+ 内置了 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)

检查 API 是否可访问

健康检查无需密钥：

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

您应看到一个小的 JSON 负载，表明服务正在运行。使用 GET /languages 获取可作为 targets 传递的代码列表。

CORS 和浏览器应用

API 可能限制哪些浏览器来源可以直接调用，以防止密钥被不受信任的网站使用。服务器端调用（Node、Python、边缘函数、您的后端）不受 CORS 限制。

对于单页应用，常见模式是：您的前端与您的后端通信，后端使用 API 密钥调用 PolyLingo。

后续步骤

  • API 参考 — 请求和响应格式、格式、错误和限制。
入门指南 | PolyLingo | PolyLingo