Integrate Traxlate into your pipeline in under 30 minutes

Prerequisites

You need a Traxlate account with a Business or Pro plan (API access is included in both). From your dashboard, navigate to API keys and create a new key. Copy the raw token — it is shown once.

All API requests use Authorization: Bearer tr_live_ as the authentication header.

Step 1: Get a quote

Before creating a job, call the quote endpoint to see how many credits a translation will consume:

POST /api/v1/quote
{
  "text": "The contract supersedes all prior agreements.",
  "src": "en",
  "tgt": "fr",
  "quality": "accurate"
}

Response:

{
  "credits": 3,
  "charCount": 45,
  "breakdown": {
    "base": 1,
    "langTierMultiplier": 1.0,
    "qualityMultiplier": 1.8
  }
}

Step 2: Submit a translation job

For text under 500 characters, the API will wait up to 28 seconds and return the result inline:

POST /api/v1/translate
{
  "text": "The contract supersedes all prior agreements.",
  "src": "en",
  "tgt": "fr",
  "quality": "accurate"
}

Response (synchronous):

{
  "job_id": "a1b2c3d4-...",
  "status": "done",
  "result": "Le contrat remplace tous les accords antérieurs.",
  "credits_charged": 3
}

For longer text or file uploads, the API returns immediately with a poll_url:

{
  "job_id": "e5f6g7h8-...",
  "status": "queued",
  "poll_url": "https://traxlate.com/api/v1/jobs/e5f6g7h8-..."
}

Step 3: Poll for job completion

GET /api/v1/jobs/e5f6g7h8-...

Response:

{
  "id": "e5f6g7h8-...",
  "status": "done",
  "progress": 100,
  "result": "...",
  "credits_charged": 145
}

Poll every 5–10 seconds. status transitions: queued → translating → done (or failed).

Step 4: Configure a webhook (recommended)

Instead of polling, configure a webhook URL on your API key. When a job completes, Traxlate will POST to your endpoint with the job payload:

{
  "event": "job.done",
  "job_id": "e5f6g7h8-...",
  "status": "done",
  "result": "...",
  "credits_charged": 145
}

The request includes a X-Traxlate-Signature header — a HMAC-SHA256 of the raw body using your webhook secret. Verify this before processing:

import hmac, hashlib

def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Setting spend caps

To prevent runaway costs from a bug in your code, set a monthlySpendCapCredits on your API key. Once the cap is hit, the API returns 402 until the following month.

Configure this from the API keys dashboard or pass it as a field when creating the key via the API.

File uploads

For PDF, DOCX, PNG, and other document formats, use multipart form data:

POST /api/v1/translate
Content-Type: multipart/form-data

file=@contract.pdf
src=en
tgt=de
quality=verified

File translations are always asynchronous. The response includes a poll_url. For large files (100+ pages), typical processing time is 2–8 minutes depending on queue depth.

Listing your jobs

GET /api/v1/jobs?limit=20&status=done

Supports status, src, tgt, limit, and before (cursor pagination) query parameters.

Cancelling a job

DELETE /api/v1/jobs/<job_id>

Cancels a queued or active job and refunds all charged credits.

More articles