POST Translation API
/api/v1/ai/translation
Translate text into one or multiple languages simultaneously, with automatic source language detection.
Architecture Role & AI Definition
Translation API provides low-latency, deterministic REST execution for production engineering workflows. It processes structured payloads with strict schema validation, returns uniform JSON envelopes, and is secured via SHA-256 API key authentication with atomic credit pre-authorization locks.
Production Reliability Guidelines
Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.
Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).
RSFlowHub acquires an atomic lock verifying base credits before model invocation. If validation fails, zero credits are deducted.
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
text |
string | Required | The user text to analyze or translate (Max: 15,000 characters). |
translate |
boolean | Optional | Whether to apply translation. Set to false to just detect language. Default is true. |
target_language |
string | Optional | A single language to translate into. Required if target_languages is not provided. |
target_languages |
array of strings | Optional | Translate text into multiple languages at once (Max 10 items). |
preserve_formatting |
boolean | Optional | Optional. If true, preserves HTML/XML tags and Markdown symbols verbatim without translating them. Default is true. |
protected_keys |
array of strings | Optional | Optional. List of dynamic placeholders/variables (e.g. ["user_name", "count"]) that must NOT be translated. Max 30 items. |
glossary |
object | Optional | Optional. Custom key-value terminology dictionary (e.g. {"Invoice": "Factura"}) to enforce exact translations. Max 30 items. |
tone |
string | Optional | Optional. Custom tone style. Options: "formal", "casual", "friendly", "professional". |
Important Note on Credit Usage
Your Content Size (Input Characters) is multiplied based on the number of target languages you request. For example, translating a 1,000-character text into 3 languages (target_languages array) consumes more processing credits than translating it into 1 language. Please be mindful of the content length and requested languages.
Example Request (Multiple Languages)
{
"text": "Hello, how can I help you today?",
"translate": true,
"target_languages": ["Spanish", "French"]
}curl -X POST https://rsflowhub.com/api/v1/ai/translation \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello, how can I help you today?",
"target_languages": ["Spanish", "French"]
}'Example Response
{
"success": true,
"request_id": "req_7f3a9c2d1e4b8a6f",
"data": {
"result": {
"detected_language": "English",
"translation_applied": true,
"translated_text": "Hola, ¿cómo puedo ayudarte hoy?",
"target_language": "Spanish",
"translations": [
{
"target_language": "Spanish",
"translated_text": "Hola, ¿cómo puedo ayudarte hoy?"
},
{
"target_language": "French",
"translated_text": "Bonjour, comment puis-je vous aider aujourd'hui ?"
}
]
}
},
"meta": {
"version": "v1",
"timestamp": "2026-09-27T12:34:56+00:00"
}
}Advanced Example (Formatting, Variables & Glossary)
This example demonstrates translating HTML-marked text while protecting placeholders, using a custom trademark glossary, and setting a casual tone.
{
"text": "Hello <b>{user_name}</b>, welcome to RSFlowHub! Please check your latest Invoice.",
"target_languages": ["Spanish"],
"preserve_formatting": true,
"protected_keys": ["user_name"],
"glossary": {
"RSFlowHub": "RSFlowHub",
"Invoice": "Factura"
},
"tone": "casual"
}{
"success": true,
"request_id": "req_7f3a9c2d1e4b8a6f",
"data": {
"result": {
"detected_language": "English",
"translation_applied": true,
"translated_text": "¡Hola <b>{user_name}</b>, bienvenido a RSFlowHub! Por favor, revisa tu última Factura.",
"target_language": "Spanish",
"translations": [
{
"target_language": "Spanish",
"translated_text": "¡Hola <b>{user_name}</b>, bienvenido a RSFlowHub! Por favor, revisa tu última Factura."
}
]
}
},
"meta": {
"version": "v1",
"timestamp": "2026-09-27T12:34:56+00:00"
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/translation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"text": "Hello, how can I help you today?",
"target_languages": [
"Spanish",
"French"
]
}'Want to try it without code? Test this request in the live Playground.
The API uses advanced models and generally supports all major global languages automatically. Source language is auto-detected.
Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 401 | API_KEY_MISSING / INVALID_API_KEY |
No key sent, or the key was mistyped or regenerated. | Copy the current key from Dashboard → API Keys and send it as Authorization: Bearer (or X-API-Key). |
| 402 | INSUFFICIENT_CREDITS |
Your balance cannot cover the estimate for this call (base 1 credits plus input/output size). | Buy a plan in Dashboard → Billing. Nothing was charged. |
| 422 | VALIDATION_ERROR |
A field is missing, too long or the wrong type, or the body is not valid JSON. | Read error.details for the field messages and fix the request. Do not retry the same body. |
| 429 | RATE_LIMIT_EXCEEDED |
Your plan-wide or per-endpoint per-minute limit was reached. | Wait the seconds in the Retry-After header, then retry with jitter. Rate limits |
| 502 | AI_PROVIDER_ERROR |
The AI model and its backup both failed. | Retry with backoff and check the status page. Nothing was charged. |