Text Translation¶

POST /v1/jobs¶

Create a new translation job from text input.

Auth: X-API-Key required Status: 202 Accepted

Request Body¶

Field	Type	Required	Default	Description
`mode`	`"translation"` \| `"creation"`	yes	—	`translation` = translate source text; `creation` = generate target-language content
`source_lang`	`string`	yes	—	BCP-47 source language code, e.g. `"de"`
`target_lang`	`string` \| `list[string]`	yes	—	Single language → `JobCreateResponse`; list → `MultiJobCreateResponse`
`text`	`string`	yes*	—	Full text to translate (will be segmented). Exclusive with `texts`
`texts`	`list[string]`	yes*	—	List of short strings (batch mode — segmenter skipped). Exclusive with `text`
`domain`	`string`	no	`null`	Subject domain, e.g. `"medical"`, `"legal"`, `"e-commerce"`
`tone`	`string`	no	`null`	Tone, e.g. `"formal"`, `"casual"`
`instructions`	`string`	no	`null`	Free-form instructions for the agents
`glossary_id`	`string`	no	`null`	ID of a stored glossary to enforce terminology
`glossary`	`list[GlossaryEntry]`	no	`null`	Inline glossary entries (alternative to `glossary_id`)
`style_reference`	`string`	no	`null`	Reference text for style matching
`constraints`	`list[ConstraintItem]`	no	`null`	Formal constraints, e.g. `[{"type": "max_chars", "value": 100}]`
`text_type`	`string`	no	`null`	Text category, e.g. `"marketing"`, `"legal"`, `"technical"`
`tier`	`string`	no	`null`	`free` / `starter` / `professional` / `business` / `enterprise`
`source_review`	`boolean`	no	`null`	Force source review on (`true`) / off (`false`), or use tier default (`null`)

*Exactly one of text or texts must be provided.

`text` vs `texts`¶

	`text`	`texts`
Input	Single string	List of strings
Segmentation	Supervisor splits into segments	Each string becomes one segment directly
Use case	Articles, documents, paragraphs	UI labels, product names, short strings
Context flow	Sequential with prior-segment context	Sequential within the list

Response: single language¶

When target_lang is a string:

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

Response: multiple languages¶

When target_lang is a list:

{
  "batch_id": "b1c2d3e4-f5a6-7890-b1c2-d3e4f5a67890",
  "jobs": [
    { "job_id": "550e8400-...", "target_language": "en", "status": "queued" },
    { "job_id": "661f9511-...", "target_language": "fr", "status": "queued" }
  ],
  "total_jobs": 2
}

Error Codes¶

Code	Description
`400`	Invalid briefing data, prompt injection detected, or input too long
`401`	Missing or invalid `X-API-Key`
`409`	Duplicate content — same text already submitted; body contains `job_id` + `status`
`422`	Invalid language combination, too many languages, or duplicate languages in list

Examples¶

Simple translation:

cURLPythonJavaScript

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": "Willkommen bei Falara."
  }'

import requests

r = requests.post(
    "https://falara.io/v1/jobs",
    headers={"X-API-Key": "sk_live_..."},
    json={
        "mode": "translation",
        "source_lang": "de",
        "target_lang": "en",
        "text": "Willkommen bei Falara.",
    },
)
print(r.json())  # {"job_id": "...", "status": "queued"}

const r = 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: "Willkommen bei Falara.",
  }),
});
console.log(await r.json());

With glossary and domain:

{
  "mode": "translation",
  "source_lang": "en",
  "target_lang": "de",
  "text": "The patient shows signs of hypertension.",
  "domain": "medical",
  "glossary_id": "gloss_abc12345"
}

Multi-language:

{
  "mode": "translation",
  "source_lang": "de",
  "target_lang": ["en", "fr", "es"],
  "text": "Unsere neue Produktlinie ist jetzt verfügbar.",
  "domain": "e-commerce"
}

Batch mode (texts) with constraints:

{
  "mode": "translation",
  "source_lang": "de",
  "target_lang": "en",
  "texts": ["Startseite", "Über uns", "Kontakt", "Warenkorb"],
  "constraints": [{"type": "max_chars", "value": 20}]
}

POST /v1/jobs/batch-text¶

Same as POST /v1/jobs, but target_lang must be a list. Enforces multi-language mode explicitly.