REST API
Build with Traxlate.
Integrate frontier-quality document translation directly into your pipelines. Authenticate with a Bearer key, post text or files, poll for results — or receive them via webhook.
- 1.Upgrade your account to Pro, Business, or Enterprise.
- 2.Go to Dashboard → API Keys and create a key.
- 3.Call POST /api/v1/translate with your Bearer token.
- 4.For short text (≤ 500 chars) the result is returned synchronously. For longer text or files, poll the job URL or configure a webhook.
All authenticated endpoints require a Bearer token in the Authorization header. Keys start with tr_live_ and are shown exactly once on creation. Store them securely — we cannot recover them.
Authorization: Bearer tr_live_<prefix><secret>Rate limit: 60 requests / minute per key (fixed window). Exceeding the limit returns 429 Too Many Requests with a Retry-After header.
Use ISO 639-1 two-letter codes (en, de, fr, zh, …) for both src and tgt. Over 200 languages are supported. The engine will reject unsupported pairs with a 400 error.
/api/v1/languagesNo auth requiredReturns the full list of supported languages with their codes, native names, script variants, and credit tier multipliers.
/api/v1/quoteNo auth requiredEstimate the credit cost before submitting a job. No credits are charged.
Request body (JSON)
charsintegerCharacter count of the source text. Provide either chars or fileBytes.
fileBytesintegerFile size in bytes. Used with mime to estimate character count.
mimestringMIME type of the source file (application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, etc.).
srcstringrequiredSource language code.
tgtstringrequiredTarget language code.
Example request
curl -X POST https://traxlate.io/api/v1/quote \
-H "Content-Type: application/json" \
-d '{"chars": 3500, "src": "de", "tgt": "en"}'Response
{
"credits": 42,
"breakdown": {
"chars": 3500,
"src": "de",
"tgt": "en",
"langTier": 1
}
}/api/v1/translateBearer authSubmit a translation job. Short text (≤ 500 chars) is translated synchronously and the result is returned immediately. Longer text or file uploads return 202 Accepted with a poll_url.
JSON body (text)
textstringrequiredSource text to translate (max 1 MB).
srcstringrequiredSource language code.
tgtstringrequiredTarget language code.
webhookstringOverride the key-level webhook URL for this specific request.
Multipart body (file upload)
filefilerequiredPDF, DOCX, PNG, JPG, TIFF — max 200 MB.
srcstringrequiredSource language code.
tgtstringrequiredTarget language code.
Example — text (cURL)
curl -X POST https://traxlate.io/api/v1/translate \
-H "Authorization: Bearer tr_live_..." \
-H "Content-Type: application/json" \
-d '{
"text": "Guten Morgen, Welt.",
"src": "de",
"tgt": "en"
}'Example — file upload (cURL)
curl -X POST https://traxlate.io/api/v1/translate \
-H "Authorization: Bearer tr_live_..." \
-F "file=@contract.pdf;type=application/pdf" \
-F "src=de" \
-F "tgt=en"Synchronous response (short text)
{
"job_id": "01900000-0000-0000-0000-000000000001",
"status": "done",
"sync": true,
"credits": 5,
"elapsed_seconds": 1.8,
"result": "The quick brown fox jumps over the lazy dog."
}Asynchronous response (long text / file)
HTTP/1.1 202 Accepted
{
"job_id": "01900000-0000-0000-0000-000000000001",
"status": "queued",
"sync": false,
"poll_url": "https://traxlate.io/api/v1/jobs/01900000-0000-0000-0000-000000000001"
}/api/v1/jobs/:idBearer authPoll the status of an asynchronous job. Poll every 2–5 seconds until status is done or failed.
Response fields
statusstringqueued | active | done | failed
progress_percentinteger0–100.
creditsintegerCredits charged. null while pending.
elapsed_secondsnumberWall time since job creation.
resultstringTranslated text. Present when status === "done".
errorstringError message. Present when status === "failed".
export_docxstringURL to download a formatted DOCX export. Present when done + source was a document.
export_pdfstringURL to download a PDF export. Present when done + source was a document.
{
"job_id": "01900000-0000-0000-0000-000000000001",
"status": "done",
"progress_percent": 100,
"credits": 42,
"elapsed_seconds": 9.4,
"result": "...",
"export_docx": "/api/v1/jobs/01900000.../export/docx",
"export_pdf": "/api/v1/jobs/01900000.../export/pdf"
}/api/v1/jobs/:idBearer authCancel a queued or in-progress job. Any credits that were reserved for the job are refunded immediately. Jobs that have already completed, failed, or been canceled return 409 Conflict.
Response
{
"ok": true,
"job_id": "01900000-0000-0000-0000-000000000001",
"status": "canceled",
"credits_refunded": 42
}/api/v1/jobsBearer authList the 50 most recent jobs for the authenticated key. Supports optional limit and offset query parameters.
{
"jobs": [
{
"job_id": "018f…",
"status": "done",
"title": "Q1 Report EN→DE",
"credits": 42,
"created_at": "2026-05-12T09:00:00.000Z"
}
],
"total": 87
}/api/v1/usageBearer authReturns the last 30 days of request and credit usage for the authenticated key. Days with no activity are included with zero values.
{
"key_id": "key_abc123",
"days": [
{ "day": "2026-05-12", "requests": 14, "credits_spent": 87 },
{ "day": "2026-05-11", "requests": 9, "credits_spent": 51 }
]
}/api/v1/jobs/:id/export/docx/api/v1/jobs/:id/export/pdfBearer authStream a formatted export of a completed document job. Returns binary file data with the appropriate Content-Type and Content-Disposition: attachment header.
Premium TTS with optional voice cloning, cross-lingual transfer, emotion presets, and word-level prosody editing. Same auth model as the translation API — pass your Bearer tr_live_… key. Pricing in the pricing page: 5 cr/1k chars standard, 15 cr/1k chars studio or cloned voice, 30 cr/1k chars studio + clone, with a 50-credit minimum per render.
POST /api/v1/tts/synth
Render a single TTS clip. Returns the WAV bytes inline for text ≤ 1500 characters; longer text returns a jobId to poll.
Body
voiceIdstringrequiredNamed voice — one of aria, nova, lyra, iris, maya, marcus, atlas, felix, orion, kai.
targetLangstringrequiredTwo-letter target language code. 31 supported — see GET /api/v1/tts/voices.
textstringrequiredScript. Max 50,000 characters per render.
mode"standard" | "studio"Defaults to standard. Studio enables best-of-N candidate selection (3× the per-character cost).
speednumber0.5–1.8 multiplier on TTS native speed.
cloneIdstring (uuid)Optional user-cloned voice id. When present, voiceId is still required for the brand label but the cloned reference overrides the preset character voice.
emotionobjectOptional delivery profile: {speed_ratio, pitch_delta_st, energy_ratio, pause_scale}. Or use emotionPreset for a built-in (whisper, shout, sad, urgent, excited, warm, calm).
cURL — preset voice
curl https://traxlate.com/api/v1/tts/synth \
-H "Authorization: Bearer tr_live_..." \
-H "Content-Type: application/json" \
-d '{"voiceId":"aria","targetLang":"en","text":"Hello, world."}' \
--output hello.wavcURL — cloned voice with an emotion preset
curl https://traxlate.com/api/v1/tts/synth \
-H "Authorization: Bearer tr_live_..." \
-H "Content-Type: application/json" \
-d '{
"voiceId":"aria",
"cloneId":"7f5b...",
"targetLang":"ko",
"text":"こんにちは。",
"emotionPreset":"warm"
}' \
--output ko_clone_warm.wavPOST /api/v1/tts/synth/stream
Same body as /synth, but the response is a chunked audio/wavstream whose RIFF size fields are 0xFFFFFFFF — players start playback at first-chunk arrival (~150–250 ms TTFT). Built for conversational agents.
POST /api/v1/tts/voices/clones
Upload a 3–20s reference audio clip. The engine validates, denoises, trims silence, detects gender. Returns a clone id usable on subsequent /synth calls. Storage is free; you only pay credits when you render with the clone. Per-user cap: 25 clones.
cURL
curl https://traxlate.com/api/v1/tts/voices/clones \
-H "Authorization: Bearer tr_live_..." \
-F "file=@reference.wav" \
-F "name=My announcer" \
-F "description=Warm neutral podcast host"GET /api/v1/tts/voices
Returns the curated cast + the 31 supported languages. Public — no auth required.
Word-level editor
After a render, alignment + per-word DSP edits are available via /api/v1/tts/jobs/:id/words (alignment, lazy) and /api/v1/tts/jobs/:id/edit(apply pitch / speed / gain / pauses per word). Edits are free within the 12-hour retention window — refining your own render doesn't cost more credits.
Upload a video or audio file, get .srt / .vtt / .txt in the source language and (optionally) in one or more target languages. Files only — no video re-encoding, no burn-in. See full pricing on the pricing page: 30 cr/min caption-only, +60 cr/min/target for translations. Bilingual SRT free.
POST /api/v1/subtitles/upload
Stream-upload the media file. Returns { video_id, duration_seconds, size_bytes }. The same video_id can be reused across dub + subtitle jobs — the engine caches the extracted audio per video id.
cURL
curl https://traxlate.com/api/v1/subtitles/upload \
-H "Authorization: Bearer tr_live_..." \
-H "x-filename: lecture.mp4" \
-H "x-video-mime: video/mp4" \
--data-binary @lecture.mp4POST /api/v1/subtitles/create
Create a subtitle job. Omit targetLangs for caption-only (cheapest tier — source-language transcript only). Include one or more targets to also receive translated subtitle files.
Body
videoIdstringrequiredFrom /subtitles/upload.
durationSecondsnumberrequiredSource media duration in seconds.
sourceLang"auto" | stringBCP-47 source language hint, or "auto" (default — engine detects from speech).
targetLangsstring[]Optional list of BCP-47 target codes. Empty / omitted = caption-only mode.
originalFileNamestringUsed in the downloaded filenames.
cURL — caption-only (cheapest)
curl https://traxlate.com/api/v1/subtitles/create \
-H "Authorization: Bearer tr_live_..." \
-H "Content-Type: application/json" \
-d '{
"videoId":"vid_abc...",
"durationSeconds":900,
"sourceLang":"auto"
}'cURL — caption + translate into FR & DE
curl https://traxlate.com/api/v1/subtitles/create \
-H "Authorization: Bearer tr_live_..." \
-H "Content-Type: application/json" \
-d '{
"videoId":"vid_abc...",
"durationSeconds":900,
"sourceLang":"en",
"targetLangs":["fr","de"]
}'Returns { batchId, jobIds, mode, perChild, totalCredits }. All children share an engine job — polling any one child reflects the whole batch.
GET /api/v1/subtitles/:id/status
Poll job status. Subscribe to subtitle.done / subtitle.failedwebhooks instead if you don't want to poll. Subtitles are fast — a 30-minute video typically finishes in under a minute.
GET /api/v1/subtitles/:id/download/:fmt
Download a subtitle file. :fmt is one of srt, vtt, txt, bilingual_srt. Pass ?lang=xxto pick which language; omit for the job's default (source for caption-only, target for translate).
cURL
curl https://traxlate.com/api/v1/subtitles/abc.../download/srt?lang=fr \
-H "Authorization: Bearer tr_live_..." \
--output lecture_fr.srtFree re-export from dubs
Every completed dub job exposes the same subtitle artifacts for free under /api/v1/dub/:id/srt, /vtt, /txt and /bilingual-srt. No extra credits — the dub pipeline already produced this data.
Instead of polling, configure a webhook URL on your API key (Dashboard → API Keys → Webhook). Traxlate will POST a signed JSON payload to your endpoint when the job completes or fails.
Payload
POST https://your-server.com/hooks/traxlate HTTP/1.1
X-Traxlate-Signature: sha256=<hmac-hex>
Content-Type: application/json
{
"event": "job.done",
"job_id": "01900000-0000-0000-0000-000000000001",
"status": "done",
"result": "...",
"credits": 42,
"elapsed_seconds": 9.4
}Events
job.doneeventTranslation job completed. Includes result, credits, elapsed_seconds, and batch_id (when part of a multi-target batch).
job.failedeventTranslation job failed. Includes error and batch_id when applicable.
batch.completedeventAll children of a translation or dub batch reached a terminal state. Payload includes batch_id, target_count, done_count, failed_count, totals, and an array of per-child summaries.
tts.doneeventTTS render finished. Includes job_id, voice_id, target_lang, char_count, duration_seconds, and an audio_url that retrieves the WAV.
tts.failedeventTTS render failed. Includes job_id and error. Credits auto-refunded.
subtitle.doneeventSubtitle child job finished. Includes job_id, batch_id, mode (caption / translate), source_lang, target_lang, duration_seconds, credits_charged.
subtitle.failedeventSubtitle child job failed. Includes job_id, batch_id and error_message. Credits auto-refunded for the failed child only — sibling children continue.
subtitle.batch.completedeventAll children of a subtitle batch reached a terminal state. Same shape as the dub batch.completed payload — batch_id, target_count, done_count, failed_count, and a children[] array with one entry per language.
Signature verification (Python)
import hmac, hashlib
def verify(payload_bytes: bytes, header: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(
secret.encode(), payload_bytes, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, header)Always verify the signature before processing the payload. Your endpoint should return a 200 within 10 seconds. Traxlate retries failed deliveries with exponential back-off up to 5 times. View delivery logs in the API keys dashboard.
400Bad RequestMissing or invalid parameters.401UnauthorizedMissing or invalid API key.402Payment RequiredInsufficient credits. Top up at Dashboard → Billing.403ForbiddenYour plan does not include API access.404Not FoundJob does not exist or belongs to another key.413Payload Too LargeFile exceeds the 200 MB limit.415Unsupported Media TypeFile type not accepted.429Too Many RequestsRate limit exceeded. Check Retry-After header.500Internal Server ErrorEngine error. The job may be retried automatically.Get a free API key on the Pro plan. Cancel anytime.