Translate

POST /ai_agent/translate. Translate text, HTML or JSON in real-time or batch mode. Request fields, response shapes, formats, and every validation error.

View as Markdown

http

POST https://api.fluentc.ai/ai_agent/translate

Translates input into target_language. In real-time mode the translation is in the response. In batch mode the response is a job_id and you fetch the result with Batch results.

Request

Headers:

Header	Value
`Authorization`	Your API key, with no `Bearer` prefix. See Authentication.
`Content-Type`	`application/json`

Body:

Field	Type	Required	Description
`input`	string or object	Yes	The content to translate. A JSON object is accepted when `input_format` is `json`.
`input_format`	string	Yes	`text`, `html` or `json`.
`target_language`	string	Yes	Language to translate into. Two or three lowercase letters such as `es`. Must be enabled for your key.
`source_language`	string	No	Language of `input`. Same format as `target_language`. If omitted, it is worked out from the text.
`mode`	string	Yes	`real-time` or `batch`. Case-insensitive.

Language codes and formats are explained in Concepts.

Response: real-time

200 OK

json

{
  "status": "complete",
  "translation": "¡Hola, mundo!",
  "token_count": 15,
  "source_language_detected": "en"
}

Field	Type	Description
`status`	string	Always `complete` in real-time mode.
`translation`	string	The translated content. For `json` input this is a JSON-encoded string; parse it.
`token_count`	integer	The size of the translation in tokens.
`source_language_detected`	string	The source language code: detected, or the `source_language` you sent.

Response: batch

200 OK

json

{
  "job_id": "abc123def456"
}

The request is accepted and translated in the background. Pass job_id to Batch results until status is complete.

The job_id is deterministic: the same input and target_language always produce the same ID, so it is safe to resubmit.

Examples

Text, real-time

bash

curl -X POST https://api.fluentc.ai/ai_agent/translate \
  -H "Authorization: $FLUENTC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello, world!",
    "input_format": "text",
    "target_language": "es",
    "source_language": "en",
    "mode": "real-time"
  }'

python

import os
import requests

res = requests.post(
    "https://api.fluentc.ai/ai_agent/translate",
    headers={"Authorization": os.environ["FLUENTC_KEY"]},
    json={
        "input": "Hello, world!",
        "input_format": "text",
        "target_language": "es",
        "source_language": "en",
        "mode": "real-time",
    },
)
res.raise_for_status()
print(res.json()["translation"])  # ¡Hola, mundo!

const res = await fetch("https://api.fluentc.ai/ai_agent/translate", {
  method: "POST",
  headers: {
    Authorization: process.env.FLUENTC_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "Hello, world!",
    input_format: "text",
    target_language: "es",
    source_language: "en",
    mode: "real-time",
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.error}`);
console.log(body.translation); // ¡Hola, mundo!

HTML, batch

Markup is preserved and the text inside it is translated.

bash

curl -X POST https://api.fluentc.ai/ai_agent/translate \
  -H "Authorization: $FLUENTC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "<h1>Welcome</h1><p>This is a sample page.</p>",
    "input_format": "html",
    "target_language": "fr",
    "mode": "batch"
  }'

json

{ "job_id": "abc123def456" }

JSON, batch

Send the structure as an object. String values are translated and the keys and shape are kept.

bash

curl -X POST https://api.fluentc.ai/ai_agent/translate \
  -H "Authorization: $FLUENTC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "title": "Welcome", "cta": "Start now" },
    "input_format": "json",
    "target_language": "ja",
    "mode": "batch"
  }'

When the job completes, translation is a JSON-encoded string:

json

{
  "status": "complete",
  "translation": "{\"title\":\"ようこそ\",\"cta\":\"今すぐ開始\"}",
  "token_count": 24,
  "source_language_detected": "en"
}

python

import json

translated = json.loads(result["translation"])
print(translated["cta"])  # 今すぐ開始

Errors

Errors are JSON with an error string. The full list is on Errors. The ones specific to this endpoint:

Status	Message	Fix
`422`	`Input is missing`	Send a non-empty `input`.
`422`	`Invalid or missing input format. Allowed formats: text, html, json`	Set `input_format` to one of the three.
`422`	`Invalid or missing target language code.`	Use a lowercase two- or three-letter code. Region codes like `pt-BR` are not accepted.
`422`	`Target language 'xx' is not enabled for this site.`	Pick a language from Languages.
`422`	`Invalid source language code: 'xx'.`	Fix `source_language`, or omit it.
`422`	`Source language 'xx' is not enabled for this site.`	Pick a language from Languages.
`422`	`Invalid or missing mode. Allowed modes: batch, real-time`	Set `mode` to `batch` or `real-time`.
`422`	`Realtime translation is not supported for this agent.`	Your key is on the Batch plan. Use `batch`, or move to the Real-time plan.
`422`	`Agent translation is not supported for this site.`	The key isn't set up for the translation API. Contact us.
`422`	`Invalid JSON format`	`input_format` is `json` but `input` isn't valid JSON.

Notes

Choose batch for large JSON. It runs in parallel and reassembles the result for you.
Pass source_language when you know it. It avoids guesses on very short strings.
Repeat requests are cheap. Identical input and target language are answered from translation memory.
Request size. Batch requests carry up to 50,000 rows. The n8n node limits a single input to 100,000 bytes; see n8n.

Something unclear, or missing? Tell us.