Skip to content

Quickstart

Get your first translation in under five minutes.

1. Get an API Key

Sign up at falara.io and create an API key from the Dashboard. Keys start with fal_.

fal_xxxxxxxxxxxxxxxxxxxxxxxx

Keep your key secret

Never expose API keys in client-side code or public repositories. Use environment variables.

2. Translate Text

Submit a translation job via POST /v1/jobs:

curl -X POST https://app.falara.io/v1/jobs \
  -H "X-API-Key: $FALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "translation",
    "source_lang": "de",
    "target_lang": "en",
    "text": "Falara kombiniert KI-Übersetzung mit automatischer Qualitätssicherung."
  }'

import requests

response = requests.post(
    "https://app.falara.io/v1/jobs",
    headers={"X-API-Key": FALARA_API_KEY},
    json={
        "mode": "translation",
        "source_lang": "de",
        "target_lang": "en",
        "text": "Falara kombiniert KI-Übersetzung mit automatischer Qualitätssicherung.",
    },
)
job = response.json()
print(job["job_id"])

const response = await fetch("https://app.falara.io/v1/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": FALARA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "translation",
    source_lang: "de",
    target_lang: "en",
    text: "Falara kombiniert KI-Übersetzung mit automatischer Qualitätssicherung.",
  }),
});
const job = await response.json();
console.log(job.job_id);

The API returns 202 Accepted with a job_id:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Job created successfully."
}

3. Poll for Results

Translation is asynchronous. Poll GET /v1/jobs/{job_id} until status is completed:

Polling interval

Poll every 2-3 seconds. Most text translations complete in under 30 seconds.

curl -X GET https://app.falara.io/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: $FALARA_API_KEY"

import time
import requests

job_id = job["job_id"]

while True:
    status_response = requests.get(
        f"https://app.falara.io/v1/jobs/{job_id}",
        headers={"X-API-Key": FALARA_API_KEY},
    )
    status = status_response.json()

    if status["status"] in ("completed", "failed"):
        break

    time.sleep(3)  # poll every 3 seconds

print(status)

const jobId = job.job_id;

let status;
while (true) {
  const res = await fetch(`https://app.falara.io/v1/jobs/${jobId}`, {
    headers: { "X-API-Key": FALARA_API_KEY },
  });
  status = await res.json();

  if (status.status === "completed" || status.status === "failed") break;

  await new Promise((r) => setTimeout(r, 3000)); // poll every 3 seconds
}

console.log(status);

When the job is complete, the response includes the translated text and a QA score:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "source_lang": "de",
  "target_lang": "en",
  "result": {
    "translated_text": "Falara combines AI translation with automated quality assurance.",
    "qa_score": 97.2
  }
}

Use webhooks instead of polling

For production integrations, set up webhooks to receive notifications when jobs complete.

Next steps