Document Translator API

The InKhmer Document Translator API translates PDF documents between Khmer and English (and other supported pairs) with the same engine that powers the inkhmer.com web tool. It is prepaid: every job debits credits from your InKhmer wallet when the job is created, and unused credits are refunded automatically if the job fails or is cancelled before it finishes.

• PDF in, PDF out — layout and fonts are preserved; scanned pages pass through OCR.
• Khmer-aware — trained and evaluated on Khmer-first academic and official documents.
• Asynchronous — create a job, poll its state, download the result. A typical job completes in seconds per page.
• Prepaid — no subscription; you pay only for pages actually translated.

Base URL: https://api.inkhmer.com/v1/public/document-translator

Create a job with one multipart POST, poll until the state reaches done, then download the PDF. Replace sk_test_… with your key and contract.pdf with your file.

# Create a job
curl -X POST https://api.inkhmer.com/v1/public/document-translator/jobs \
  -H "Authorization: Bearer $INKHMER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@contract.pdf" \
  -F "source=auto" \
  -F "target=km"
# → 202 { "jobId": "019a…", "pagesTotal": 72, "tier": "t4",
#         "priceCredits": 999, "walletAfter": 1301,
#         "pollUrl": "/v1/public/document-translator/jobs/019a…" }

# Poll until done / error / cancelled (~every 2 s)
JOB_ID=019a…   # from the 202 response
while :; do
  STATE=$(curl -s https://api.inkhmer.com/v1/public/document-translator/jobs/$JOB_ID \
    -H "Authorization: Bearer $INKHMER_KEY" | jq -r .state)
  echo "$STATE"
  [ "$STATE" = done ] && break
  [ "$STATE" = error ] && exit 1
  [ "$STATE" = cancelled ] && exit 1
  sleep 2
done

# Download the watermark-free PDF
curl -o translation.pdf https://api.inkhmer.com/v1/public/document-translator/jobs/$JOB_ID/pdf \
  -H "Authorization: Bearer $INKHMER_KEY"

// Requires Node 18+ (global fetch / FormData / Blob).
import { randomUUID } from 'node:crypto';
import fs from 'node:fs';

const BASE = 'https://api.inkhmer.com/v1/public/document-translator';
const ORIGIN = 'https://api.inkhmer.com';
const KEY = process.env.INKHMER_KEY; // sk_test_… / sk_live_…
const headers = { Authorization: `Bearer ${KEY}` };

// 1. Create the job (multipart upload)
const form = new FormData();
form.append('file', new Blob([fs.readFileSync('contract.pdf')]), 'contract.pdf');
form.append('source', 'auto');
form.append('target', 'km');

const created = await fetch(`${BASE}/jobs`, {
  method: 'POST',
  headers: { ...headers, 'Idempotency-Key': randomUUID() },
  body: form,
}).then((r) => r.json());

// 2. Poll the job (~every 2 s) until a terminal state.
//    created.pollUrl is the relative /v1/… path from the 202 response.
while (true) {
  const job = await fetch(`${ORIGIN}${created.pollUrl}`, { headers })
    .then((r) => r.json());
  if (job.state === 'done') break;
  if (job.state === 'error' || job.state === 'cancelled')
    throw new Error(`job ${job.state}: ${job.error}`);
  await new Promise((r) => setTimeout(r, 2000));
}

// 3. Download the watermark-free PDF
const pdf = await fetch(`${BASE}/jobs/${created.jobId}/pdf`, { headers });
fs.writeFileSync('translation.pdf', Buffer.from(await pdf.arrayBuffer()));

import os, time, uuid
import requests

BASE = 'https://api.inkhmer.com/v1/public/document-translator'
KEY = os.environ['INKHMER_KEY']  # sk_test_… / sk_live_…
HEADERS = {'Authorization': f'Bearer {KEY}'}

# 1. Create the job (multipart upload)
with open('contract.pdf', 'rb') as f:
    created = requests.post(
        f'{BASE}/jobs',
        headers={**HEADERS, 'Idempotency-Key': str(uuid.uuid4())},
        files={'file': ('contract.pdf', f, 'application/pdf')},
        data={'source': 'auto', 'target': 'km'},
    ).json()

# 2. Poll the job (~every 2 s) until a terminal state
while True:
    job = requests.get(
        f"{BASE}/jobs/{created['jobId']}", headers=HEADERS
    ).json()
    if job['state'] == 'done':
        break
    if job['state'] in ('error', 'cancelled'):
        raise RuntimeError(f"job {job['state']}: {job['error']}")
    time.sleep(2)

# 3. Download the watermark-free PDF
pdf = requests.get(
    f"{BASE}/jobs/{created['jobId']}/pdf", headers=HEADERS
)
with open('translation.pdf', 'wb') as f:
    f.write(pdf.content)

Jobs with more than ~20 MiB of payload should use the direct-to-storage flow instead: POST /jobs/intent for a presigned upload URL, PUT the bytes, then POST /jobs/{jobId}/finalize. See the reference section for both flows.

Jobs are billed in wallet credits by page band — the same tiers as the inkhmer.com tool. 1 credit = $0.01 USD. The price is quoted at job creation and debited before translation starts; unused credits from failed or cancelled jobs are refunded automatically.

Top up credits with Bakong KHQR (or card) on your billing page — credits are shared between the web tool and the API.

More than 1,000 pages per document? Contact us for a custom quote.

Every request carries a TosKey API key in the Authorization: Bearer header. Issue keys in the TosKey Console, InKhmer section (S5) — a new key selects all three translator scopes by default.

Authorization: Bearer sk_live_…
# scopes: translator:translate | translator:read | translator:cancel

• translator:translate — create jobs, upload intents, finalize uploads.
• translator:read — poll job status and download PDFs.
• translator:cancel — cancel a running job and refund unused pages.
• translator:* — wildcard covering all three; selected by default on new keys.

Open the TosKey Console

The TosKey gateway enforces per-key limits before a request reaches the API. Responses carry X-RateLimit-Limit / -Remaining / -Reset and, on 429, a Retry-After seconds hint.

50 req/min — All keys belonging to one identity share an account-level burst limit of 50 requests/minute — request 51 within a minute is rejected at the gateway.

pro-translator-rate pro-translator-rate lifts the write limits to 100/min · 1,000/hour · 10,000/day per key. It is assigned by the operator in the TosKey Console — contact us to request it; it is not self-serve.

Read X-RateLimit-Remaining to back off before a hard stop, and honour Retry-After on 429 responses. X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetRetry-After

Every operation below is rendered from the live OpenAPI document — request and response bodies, parameters, and the exact error examples the API returns.

Download openapi.jsonPostman collectionExample code (zip)

idempotency-key — Mutating endpoints accept the header. Replaying the same key within 24 hours returns the original response without charging twice.

• Keys are scoped to your API key — two different keys using the same value start independent jobs.
• Replaying the same key with a different payload returns 409 idempotency_conflict.
• Safe retries: if a create call times out, retry with the same Idempotency-Key — the second call replays the first job instead of double-charging.
• Idempotency-Key must be 8–255 characters; a uuidv4/uuidv7 is recommended.

v1 has no webhooks — poll GET /jobs/{jobId} every ~2 seconds until the state is done, error, or cancelled. A job.done webhook is on the roadmap.

Using the API means you accept the InKhmer API Terms — acceptable use, retention, and rate-limit enforcement. Read the API terms