Python SDK (polylingo)

PolyLingo REST API 的官方 Python 客户端。它使用 httpx 并提供具有相同方法名称的同步和异步客户端。

有关原始 HTTP 详情，请参见 API reference。

安装

pip install polylingo

Python: >= 3.9

同步客户端

import os
import polylingo

client = polylingo.PolyLingo(
    api_key=os.environ["POLYLINGO_API_KEY"],
    base_url="https://api.usepolylingo.com/v1",  # 可选；显示默认值
    timeout=120.0,  # 可选；每个请求的秒数（默认120）
)

result = client.translate(content="# Hello", targets=["es", "fr"], format="markdown")
print(result["translations"]["es"])

client.close()

上下文管理器：

with polylingo.PolyLingo(api_key="...") as client:
    print(client.languages())
参数必需描述
api_key是API 密钥 (Authorization: Bearer …)。
base_url否包含 /v1 的 API 前缀。默认 https://api.usepolylingo.com/v1。
timeout否httpx 超时时间，单位为秒。默认 120.0。

异步客户端

import polylingo

async with polylingo.AsyncPolyLingo(api_key="...") as client:
    r = await client.translate(content="Hi", targets=["de"])

如果不使用 async with，请使用 await client.aclose()。

方法名称与同步客户端匹配；所有网络方法均为 async def。

方法（同步和异步）

health() / await health()

GET /health

h = client.health()
# async: h = await client.health()

languages() / await languages()

GET /languages

data = client.languages()
langs = data["languages"]

translate(...)

POST /translate

r = client.translate(
    content="# Hello",
    targets=["es", "fr"],
    format="markdown",  # 可选
    source="en",        # 可选
    model="standard",   # 可选: "standard" | "advanced"
)
r["translations"]["es"]
r["usage"]["total_tokens"]

batch(...)

POST /translate/batch

b = client.batch(
    items=[
        {"id": "a", "content": "Hello"},
        {"id": "b", "content": "## Title", "format": "markdown"},
    ],
    targets=["de"],
)
b["results"][0]["translations"]["de"]

usage() / await usage()

GET /usage

u = client.usage()

任务 — client.jobs

create / await create

POST /jobs — 返回 202 响应体（job_id，status，…）。

job = client.jobs.create(content=long_md, targets=["de", "fr"], format="markdown")
# 也接受 kwargs: client.jobs.create(**{"content": ..., "targets": [...]})

get(job_id) / await get(job_id)

GET /jobs/:id。当 status == "completed" 时，响应在顶层包含 translations 和 usage。

translate(...) — 便捷方法

轮询直到 completed 或 failed，或直到超时。

done = client.jobs.translate(
    content=long_md,
    targets=["de", "fr", "es"],
    format="markdown",
    poll_interval=10.0,   # 轮询间隔秒数；默认 5.0
    timeout=600.0,        # **总**秒数预算；默认 1200（20 分钟）
    on_progress=lambda pos: print(f"Queue: {pos}"),
)
done["translations"]["de"]

异步：

done = await client.jobs.translate(
    content=long_md,
    targets=["de"],
    poll_interval=2.0,
    timeout=300.0,
)

API 状态：pending，processing，completed，failed。

异常

类何时
polylingo.PolyLingoError基类 — status，error，args[0] 消息。
polylingo.AuthErrorHTTP 401。
polylingo.RateLimitErrorHTTP 429 — 可能设置了 retry_after（秒）。
polylingo.JobFailedError失败的任务，错误的完成负载，或轮询超时 — job_id。
import polylingo

try:
    client.translate(content="x", targets=["es"])
except polylingo.AuthError as e:
    print(e.status, e.error)
except polylingo.RateLimitError as e:
    print(e.retry_after)
except polylingo.JobFailedError as e:
    print(e.job_id)
except polylingo.PolyLingoError as e:
    print(e.status, e.error)

异步任务模式（摘要）

  1. 手动： jobs.create → 循环 jobs.get 直到终态。
  2. 辅助： 使用 jobs.translate，带 poll_interval、timeout 和可选的 on_progress。

对于非常大的内容，建议使用任务，因为同步 translate 可能会遇到客户端或服务器超时。

类型

该包附带 py.typed。响应对象是与 API 对齐的纯 dict 值；如果需要，可在代码中使用 TypedDict 风格的注解。

更新日志

0.1.0

  • 初始版本：同步 PolyLingo，异步 AsyncPolyLingo，完整端点覆盖，包括 jobs.translate 轮询辅助。
Python SDK | PolyLingo 文档 | PolyLingo