Skip to content

Quickstart

Get up and running with the Falara API in minutes.

1. Get your API key

API keys are generated in the Falara Dashboard under Settings → API Keys.

All API requests require the key in the X-API-Key header:

X-API-Key: sk_live_...

2. Translate your first text

Send a POST /v1/jobs request with the source text and language pair.

curl -X POST https://falara.io/v1/jobs \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "translation",
    "source_lang": "de",
    "target_lang": "en",
    "text": "Die Qualität unserer Produkte spricht für sich."
  }'

import requests

response = requests.post(
    "https://falara.io/v1/jobs",
    headers={"X-API-Key": "sk_live_..."},
    json={
        "mode": "translation",
        "source_lang": "de",
        "target_lang": "en",
        "text": "Die Qualität unserer Produkte spricht für sich.",
    },
)
data = response.json()
job_id = data["job_id"]
print(f"Job created: {job_id}, status: {data['status']}")

const response = await fetch("https://falara.io/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": "sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "translation",
    source_lang: "de",
    target_lang: "en",
    text: "Die Qualität unserer Produkte spricht für sich.",
  }),
});
const { job_id, status } = await response.json();
console.log(`Job created: ${job_id}, status: ${status}`);

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

3. Get the result

Poll GET /v1/jobs/{job_id}/result until the job is complete. In production, use webhooks instead.

Tip

Poll every 2–3 seconds. Most translations complete in under 10 seconds.

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

import time

job_id = "550e8400-e29b-41d4-a716-446655440000"

while True:
    r = requests.get(
        f"https://falara.io/v1/jobs/{job_id}/result",
        headers={"X-API-Key": "sk_live_..."},
    )
    if r.status_code == 200:
        result = r.json()
        print(result["translation"])
        break
    elif r.status_code == 409:
        time.sleep(15)  # still processing
    else:
        raise Exception(f"Error: {r.status_code}")

async function pollResult(jobId) {
  while (true) {
    const r = await fetch(`https://falara.io/v1/jobs/${jobId}/result`, {
      headers: { "X-API-Key": "sk_live_..." },
    });
    if (r.status === 200) {
      const result = await r.json();
      console.log(result.translation);
      return result;
    } else if (r.status === 409) {
      await new Promise((resolve) => setTimeout(resolve, 15000));
    } else {
      throw new Error(`Unexpected status: ${r.status}`);
    }
  }
}

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "translation": "The quality of our products speaks for itself.",
  "qa_score": 96.5,
  "word_count": { "source": 8, "target": 9 },
  "delivery_notes": [],
  "warning": null
}

4. Translate a file

Upload a file using multipart/form-data. The briefing_json field contains the translation settings as a JSON string.

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

with open("document.docx", "rb") as f:
    response = requests.post(
        "https://falara.io/v1/jobs/file",
        headers={"X-API-Key": "sk_live_..."},
        files={"file": ("document.docx", f, "application/octet-stream")},
        data={
            "briefing_json": json.dumps({
                "mode": "translation",
                "source_lang": "de",
                "target_lang": "en",
            })
        },
    )
data = response.json()
job_id = data["job_id"]
print(f"Extracted {data['segments_extracted']} segments")

Download the translated file once the job is complete:

curl https://falara.io/v1/jobs/{job_id}/download \
  -H "X-API-Key: sk_live_..." \
  -o translated_document.docx

Next steps