Skip to content

File Translation

Upload files for translation through the Falara pipeline. Formatting is preserved automatically.

POST /v1/jobs/file

Upload a single file for translation.

Authentication

Header: X-API-Key: your_api_key

Content-Type: multipart/form-data Status: 202 Accepted

Supported Formats

Extension Format Notes
.html, .htm HTML Tag structure preserved; only text nodes translated.
.md, .markdown Markdown Structure preserved; only prose translated.
.docx Microsoft Word Paragraphs, tables, character formatting preserved.
.xlsx Microsoft Excel Cell values translated; formulas untouched.
.pptx Microsoft PowerPoint Slide text and speaker notes translated.
.xlf, .xliff XLIFF 1.2 / 2.0 / Eurotext-XLIFF Translation units processed; metadata preserved.
.json JSON Values translated; keys and structure preserved.
.pdf PDF Text extracted and translated.

File Size Limit

Maximum file size is 50 MB. Files exceeding this limit return 413 Payload Too Large.

Form Fields

Field Type Required Description
file file yes The file to translate.
briefing_json string (JSON) yes JSON-encoded string containing mode, source_lang, target_lang, and optional translation options (see below).

briefing_json

The briefing_json form field is a JSON-encoded string that contains the required translation parameters (mode, source_lang, target_lang) along with any optional settings.

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

{
  "mode": "translate",
  "source_lang": "de",
  "target_lang": "en",
  "domain": "legal",
  "tone": "formal",
  "glossary_ids": ["gloss_abc12345"],
  "quality": "premium",
  "project_name": "Contract Translations Q2",
  "instructions": "Preserve all legal references in their original form."
}

Response (202)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "File job created successfully.",
  "original_filename": "contract_de.docx"
}

Examples

curl -X POST https://app.falara.io/v1/jobs/file \
  -H "X-API-Key: $FALARA_API_KEY" \
  -F "file=@contract_de.docx" \
  -F 'briefing_json={"mode":"translate","source_lang":"de","target_lang":"en","domain":"legal","tone":"formal","quality":"premium"}'

import json
import requests

briefing = {
    "mode": "translate",
    "source_lang": "de",
    "target_lang": "en",
    "domain": "legal",
    "tone": "formal",
    "quality": "premium",
}

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

const formData = new FormData();
formData.append("file", fileBlob, "contract_de.docx");
formData.append(
  "briefing_json",
  JSON.stringify({
    mode: "translate",
    source_lang: "de",
    target_lang: "en",
    domain: "legal",
    tone: "formal",
    quality: "premium",
  })
);

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

GET /v1/jobs/{job_id}/download

Download the translated file. Only available when the job status is completed or completed_with_blocks.

Authentication

Header: X-API-Key: your_api_key

Status: 200 OK Content-Type: Original file MIME type (e.g., application/vnd.openxmlformats-officedocument.wordprocessingml.document)

The response body is the binary file content. The filename is provided via the Content-Disposition header.

Examples

curl -X GET "https://app.falara.io/v1/jobs/550e8400-.../download" \
  -H "X-API-Key: $FALARA_API_KEY" \
  -o translated_contract_en.docx

import requests

response = requests.get(
    f"https://app.falara.io/v1/jobs/{job_id}/download",
    headers={"X-API-Key": FALARA_API_KEY},
)

filename = response.headers.get("content-disposition", "").split("filename=")[-1]
with open(filename or "translated.docx", "wb") as f:
    f.write(response.content)

const response = await fetch(
  `https://app.falara.io/v1/jobs/${jobId}/download`,
  { headers: { "X-API-Key": FALARA_API_KEY } }
);

const blob = await response.blob();
// Save blob using your preferred method

Errors

Status Description
401 Invalid or missing API key.
404 Job not found.
409 Job not yet complete or is not a file job.