TranslateKaro API

Programmatic access to the same document-translation pipeline the web app uses: upload a scanned PDF, get back a translated document. OCR extracts the text from the scan; machine translation converts it into your target language.

Authentication

Send your key in the X-API-Key header on every request. Keys are per-user — generate or regenerate yours from the API Access card on your dashboard. A key is shown once, at generation time; only its prefix is shown afterwards.

An X-API-Key request is authenticated independently of your browser session and does not need a CSRF token. If you call these endpoints from a logged-in browser session instead (no X-API-Key header), the usual session CSRF protection applies.

An invalid X-API-Key always gets a JSON 401. If you send no key at all (and have no browser session), you must also send Accept: application/json to get a JSON 401 back — without it you get a browser-style 302 redirect to /login instead, so API clients should always send that header. See Errors below.

Rate limits

Limits are keyed per user when a valid X-API-Key is presented, otherwise per IP address. Exceeding a limit returns 429.

Uploading a document

POST /estimate takes a multipart/form-data body:

Target languages

Document (source) languages

Endpoints

Paying by card happens through Razorpay's own Checkout widget in a browser — this API does not accept card details directly. The free trial path (/billing/start-free/<job_id>) is the only fully headless way to start a job.

Response shapes

POST /estimate responds with:

{
  "job_id": "…",
  "filename": "…",
  "target_lang": "en",
  "target_lang_name": "English",
  "source_lang": "hi",
  "source_lang_name": "Hindi",
  "page_count": 12,
  "price_per_page": 15,
  "total_price": 180,
  "total_price_paise": 18000,
  "currency": "INR",
  "pricing_tiers": [{"up_to": 20, "rate": 15}, …],
  "trial_eligible": true,
  "free_uploads_remaining": 2,
  "trial_page_limit": 5,
  "trial_pages": 5,
  "gst_enabled": false
}

When GST is enabled for your account, gst_rate_percent, gst_amount, total_with_gst and total_with_gst_paise are added.

GET /status/<job_id> responds with:

{
  "status": "processing",
  "step": "uploading",
  "detail": "Starting...",
  "progress": 42,
  "pages_done": 5,
  "pages_total": 12
}

pages_done/pages_total/progress are only present once the job has started; stuck: true is added if the job appears wedged.

Status values

estimated is a job's actual status immediately after /estimate — the state /billing/start-free and /billing/create-order expect the job to be in. But /status returns 404 for it until then: no order or trial attempt has been created for the job yet, so there's no record to look up. Once /billing/create-order has been called, /status starts working and reports estimated until the payment is confirmed, when it moves to processing. The free trial path (/billing/start-free) skips this window entirely and moves the job straight to processing.

Errors

Errors are JSON: {"error": "…"}.

Walkthrough

Accept: application/json is included on every call below — without it, an unauthenticated or unauthorized request gets a browser redirect instead of a JSON error (see Errors above).

# 1. Estimate — upload the PDF, get a job id and price
curl -X POST https://translatekaro.com/estimate \
  -H "X-API-Key: $TK_API_KEY" -H "Accept: application/json" \
  -F "pdf=@document.pdf" \
  -F "target_lang=en" \
  -F "source_lang=hi"
# => {"job_id": "abc123...", "trial_eligible": true, "total_price": 180, ...}

# 2a. Start it on the free trial, if trial_eligible is true
curl -X POST https://translatekaro.com/billing/start-free/abc123... \
  -H "X-API-Key: $TK_API_KEY" -H "Accept: application/json"

# 2b. Otherwise, pay: create an order, complete Razorpay Checkout in a
#     browser with the returned order_id/key_id, then verify it
curl -X POST https://translatekaro.com/billing/create-order/abc123... \
  -H "X-API-Key: $TK_API_KEY" -H "Accept: application/json"
# ... complete payment via Razorpay Checkout ...
curl -X POST https://translatekaro.com/billing/verify-payment \
  -H "X-API-Key: $TK_API_KEY" -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"razorpay_order_id": "...", "razorpay_payment_id": "...", "razorpay_signature": "..."}'

# 3. Poll status until complete
curl -H "X-API-Key: $TK_API_KEY" -H "Accept: application/json" \
  https://translatekaro.com/status/abc123...

# 4. Download the result
curl -H "X-API-Key: $TK_API_KEY" -H "Accept: application/json" \
  -o translated.pdf \
  "https://translatekaro.com/download/abc123...?format=pdf"