polytranslator-api

# Polytranslator API

**Document translation API that keeps the layout.** Translate PDFs (including scans), Word, PowerPoint, Excel, EPUB and photos across 475 languages and styles, including ancient and low-resource languages such as Ancient Greek, Coptic and Old English. Native documents keep their format; photos return as PNG and other supported inputs are converted to an editable document format. Text translation, webhooks and a remote MCP server for AI agents use the same prepaid credits. Use an API key for REST integrations or connect an assistant with OAuth. No subscription required.

- Website and pricing: https://www.polytranslator.com/developers/
- Full reference: https://www.polytranslator.com/developers/docs/ (Markdown for agents: https://www.polytranslator.com/api.md)
- OpenAPI: [`openapi.json`](openapi.json) (live at https://www.polytranslator.com/api/openapi.json)
- MCP server: `https://www.polytranslator.com/api/mcp`
- Public MCP tool card: [`/.well-known/mcp/server-card.json`](https://www.polytranslator.com/.well-known/mcp/server-card.json)
- Get an API key: https://www.polytranslator.com/api-keys/

## Quickstart

```sh
export POLYTRANSLATOR_API_KEY=pk_live_...
export IDEMPOTENCY_KEY=$(uuidgen) # Keep this value when retrying this submission.

# 1. Submit (returns 202 with a document id)
curl https://www.polytranslator.com/api/v1/documents \
  -H "Authorization: Bearer $POLYTRANSLATOR_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F file=@contract.pdf -F tgt=spa_Latn -F max_credits=500

# 2. Set DOCUMENT_ID to the returned id, then wait (up to 60 s per request).
export DOCUMENT_ID=REPLACE_WITH_RETURNED_ID
curl "https://www.polytranslator.com/api/v1/documents/$DOCUMENT_ID?wait=60" \
  -H "Authorization: Bearer $POLYTRANSLATOR_API_KEY"

# Repeat step 2 while status is queued or processing.
# 3. Once status is completed, download the translated file.
curl -OJ https://www.polytranslator.com/api/v1/documents/$DOCUMENT_ID/file \
  -H "Authorization: Bearer $POLYTRANSLATOR_API_KEY"
```

Runnable examples:

| Task | Python | Node | curl |
| --- | --- | --- | --- |
| Translate a document | [`translate_document.py`](examples/python/translate_document.py) | [`translate-document.mjs`](examples/node/translate-document.mjs) | [`translate-document.sh`](examples/curl/translate-document.sh) |
| Free quote | [`quote_document.py`](examples/python/quote_document.py) | | |
| Translate text | [`translate_text.py`](examples/python/translate_text.py) | | |
| Verify a webhook | [`verify_webhook.py`](examples/python/verify_webhook.py) | [`verify-webhook.mjs`](examples/node/verify-webhook.mjs) | |

## What it does

| | |
| --- | --- |
| Formats in | PDF (text-based or scanned), DOCX, PPTX, XLSX, EPUB, PNG, JPG, WEBP, HEIC; DOC, ODT, RTF, TXT, Markdown, HTML, XML, SRT, VTT, TeX, Pages → DOCX; XLS, ODS, CSV, TSV, Numbers → XLSX; PPT, ODP, Keynote → PPTX; MOBI, AZW3, FB2 → DOCX |
| Output | Native PDF, DOCX, PPTX, XLSX and EPUB keep their format; photos return as PNG, and converted inputs use the format shown above. Layout, tables and images are preserved, with scan/photo text translated in place (`output=formatted`). Or choose translated text only (`output=text`). |
| Limits | 50 MB, 1,000 PDF pages, 1,000,000 characters per document; 5 documents in progress per account |
| Languages and styles | 475 catalog entries; source auto-detected; `GET /v1/languages` |
| Tiers | `fast` and `advanced` (the most accurate) |
| Price | Prepaid credit packs from $9.99 (300 credits) to $99.99 (5,000). Every document is quoted for free before you pay and charged exactly its quote; failed documents are refunded. Text: 1 credit per 1,000 characters (fast), 3 (advanced). |
| Async | `?wait=` long-poll, or a signed webhook (`callback_url`) when the document finishes |
| Safety | `Idempotency-Key` on submissions (a retry never charges twice), `max_credits` spending cap per request |
| Agents | Headless signup and purchase with a Stripe Shared Payment Token, OpenAPI, [`llms.txt`](https://www.polytranslator.com/llms.txt), remote MCP server |

Measured examples on the fast tier: a short Word contract costs 1 credit; a one-page scanned court filing costs 19 credits.

## Use it from AI agents (MCP)

Remote Streamable HTTP server, nothing to install. Tools: `translate_document`, `get_document`, `quote_document`, `translate_text`, `list_languages`, `get_credit_balance`. Completed documents come back as download links that work without a key for 24 hours.

**ChatGPT / Claude web connectors (OAuth)**

Add `https://www.polytranslator.com/api/mcp` as a custom connector or MCP server in a client that supports remote MCP and OAuth. Sign in to Polytranslator and approve the connection. You do not need to copy an API key into the assistant. Connector availability depends on your client and account settings.

Each connection can translate documents and text, read your purchased credit balance, and retrieve your account's API document results. It cannot buy credits, change billing settings or manage API keys. Documents and text still spend purchased credits; approving a connection does not buy a credit pack. Any automatic refill you already enabled continues under its existing settings. Revoke a connection from the [API dashboard](https://www.polytranslator.com/api-keys/) by revoking its `MCP: <client name>` key.

For implementers: OAuth uses the `translation` scope and authorization code flow with S256 PKCE. Public clients can use an HTTPS Client ID Metadata Document (CIMD) with `token_endpoint_auth_method: none`. Dynamic client registration (DCR) also remains available for public clients (`none`) and confidential clients (`client_secret_basic` or `client_secret_post`). Access tokens last one hour; refresh tokens rotate and expire 30 days after connection creation.

The resource is exactly `https://www.polytranslator.com/api/mcp`; include it in authorization and token requests. The issuer is `https://www.polytranslator.com/api/oauth`. Discovery endpoints are [`/.well-known/oauth-protected-resource/api/mcp`](https://www.polytranslator.com/.well-known/oauth-protected-resource/api/mcp) and [`/.well-known/oauth-authorization-server/api/oauth`](https://www.polytranslator.com/.well-known/oauth-authorization-server/api/oauth).

All MCP transport requests, including initialization and tool listing, require authentication. Missing or invalid credentials receive HTTP 401 with a `WWW-Authenticate` discovery challenge so clients start OAuth immediately. Directories can inspect the six tools without signing in through the [public server card](https://www.polytranslator.com/.well-known/mcp/server-card.json). OAuth access tokens work only through MCP; direct REST requests use API keys.

**API-key clients**

API-key authentication remains supported. The configurations below use an API key; keep it out of source control. The REST examples and Postman collection also use API keys.

**Claude Code**

```sh
claude mcp add --transport http polytranslator https://www.polytranslator.com/api/mcp \
  --header "Authorization: Bearer $POLYTRANSLATOR_API_KEY"
```

**Cursor** (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "polytranslator": {
      "url": "https://www.polytranslator.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`)

```json
{
  "servers": {
    "polytranslator": {
      "type": "http",
      "url": "https://www.polytranslator.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

**Codex** (`~/.codex/config.toml`)

```toml
[mcp_servers.polytranslator]
url = "https://www.polytranslator.com/api/mcp"
bearer_token_env_var = "POLYTRANSLATOR_API_KEY"
```

Registry entry: [`mcp/server.json`](mcp/server.json) (`com.polytranslator/translator`). Also listed on [Smithery](https://smithery.ai/servers/polytranslator/polytranslator).

## How it compares

A sourced comparison with DeepL, Google Cloud Translation, Azure AI Translator and Amazon Translate (formats, scans, limits, languages, pricing, minimum charges, setup) is at https://www.polytranslator.com/guides/document-translation-api/.

## Postman

Open the [public Postman collection](https://www.postman.com/maxim-b5527c14-3409929/polytranslator-api/collection/7dxwy82/polytranslator-api), or import [`postman/polytranslator.postman_collection.json`](postman/polytranslator.postman_collection.json), and set the `apiKey` collection variable to your API key. Keep the populated value private; do not include credentials in a published workspace or exported collection. The `baseUrl` variable defaults to `https://www.polytranslator.com/api`.

## About

Polytranslator is built by the authors of *From LLM to NMT: Advancing Low-Resource Machine Translation with Claude* (Enis & Hopkins, 2024, [arXiv:2404.13813](https://arxiv.org/abs/2404.13813)). Questions: support@polytranslator.com.

The examples in this repository are MIT licensed.