File Translation¶

POST /v1/jobs/file¶

Upload a file for translation. The file is parsed, text segments are extracted, translated through the multi-agent pipeline, and reassembled into the original format.

Auth: X-API-Key required Content-Type: multipart/form-data Status: 202 Accepted

Supported Formats¶

Extension	Format
`.html`, `.htm`	HTML
`.md`, `.markdown`	Markdown
`.docx`	Microsoft Word
`.xlsx`	Microsoft Excel
`.pptx`	Microsoft PowerPoint
`.xlf`, `.xliff`	XLIFF 1.2, XLIFF 2.0, Eurotext-XLIFF

Maximum file size: 10 MB

Form Fields¶

Field	Type	Required	Description
`file`	file	yes	The file to translate
`briefing_json`	string (JSON)	yes	Translation settings as a JSON string. Must include `mode`, `source_lang`, `target_lang`. Do not include `text` or `texts` — content is extracted from the file.

briefing_json minimum required fields:

{
  "mode": "translation",
  "source_lang": "de",
  "target_lang": "en"
}

All optional POST /v1/jobs fields (domain, tone, glossary_id, constraints, etc.) are supported in briefing_json.

Response¶

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "format": "docx",
  "segments_extracted": 42,
  "translatable_segments": 38,
  "file_size_bytes": 204800
}

Field	Type	Description
`format`	`string`	Detected file format
`segments_extracted`	`int`	Total segments found in file
`translatable_segments`	`int`	Segments with translatable content
`file_size_bytes`	`int`	Uploaded file size

Error Codes¶

Code	Description
`400`	Invalid `briefing_json`, no processor for this format, or no translatable content found
`401`	Missing or invalid `X-API-Key`
`409`	Duplicate file — same content already submitted
`413`	File exceeds 10 MB limit
`415`	MIME type does not match file extension
`422`	Text extraction failed

Examples¶

cURLPythonJavaScript

curl -X POST https://falara.io/v1/jobs/file \
  -H "X-API-Key: sk_live_..." \
  -F "file=@document.docx" \
  -F 'briefing_json={"mode":"translation","source_lang":"de","target_lang":"en"}'

import json, requests

briefing = {
    "mode": "translation",
    "source_lang": "de",
    "target_lang": "en",
    "domain": "legal",
}

with open("document.docx", "rb") as f:
    r = requests.post(
        "https://falara.io/v1/jobs/file",
        headers={"X-API-Key": "sk_live_..."},
        files={"file": ("document.docx", f)},
        data={"briefing_json": json.dumps(briefing)},
    )
print(r.json())

const formData = new FormData();
formData.append("file", fileBlob, "document.docx");
formData.append(
  "briefing_json",
  JSON.stringify({ mode: "translation", source_lang: "de", target_lang: "en" })
);

const r = await fetch("https://falara.io/v1/jobs/file", {
  method: "POST",
  headers: { "X-API-Key": "sk_live_..." },
  body: formData,
});
console.log(await r.json());

GET /v1/jobs/{job_id}/download¶

Download the translated file once the job is complete.

Auth: X-API-Key required Available when: status is completed, completed_with_blocks, or needs_review

Response¶

Binary file stream with appropriate headers:

Content-Disposition: attachment; filename=translated_document.docx
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document

Content-Type by format:

Format	Content-Type
`.html`, `.htm`	`text/html`
`.md`, `.markdown`	`text/markdown`
`.docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
`.xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
`.pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
`.xlf`, `.xliff`	`application/xliff+xml`

Error Codes¶

Code	Description
`400`	Job is not a file job
`401`	Missing or invalid `X-API-Key`
`404`	Job not found
`409`	Job not yet complete
`410`	Original file no longer available (deleted)
`500`	Injection failed or no processor available

Example¶

curl https://falara.io/v1/jobs/550e8400-e29b-41d4-a716-446655440000/download \
  -H "X-API-Key: sk_live_..." \
  -o translated_document.docx