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. {"Wallet": "Billetera"}) 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,
"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": {
"credits_used": 3,
"credits_remaining": 997
}
}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 Wallet balance.",
"target_languages": ["Spanish"],
"preserve_formatting": true,
"protected_keys": ["user_name"],
"glossary": {
"RSFlowHub": "RSFlowHub",
"Wallet": "Billetera"
},
"tone": "casual"
}{
"success": true,
"data": {
"result": {
"detected_language": "English",
"translation_applied": true,
"translated_text": "¡Hola <b>{user_name}</b>, bienvenido a RSFlowHub! Por favor, revisa el saldo de tu Billetera.",
"target_language": "Spanish",
"translations": [
{
"target_language": "Spanish",
"translated_text": "¡Hola <b>{user_name}</b>, bienvenido a RSFlowHub! Por favor, revisa el saldo de tu Billetera."
}
]
}
},
"meta": {
"credits_used": 2,
"credits_remaining": 995
}
}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"
]
}'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 |
|---|---|---|---|
| 400 | bad_request |
Malformed JSON syntax or missing required top-level parameters. | Validate JSON payload with Content-Type: application/json and ensure all required fields are present. |
| 401 | unauthorized |
Missing, revoked, or incorrectly formatted x-api-key header. |
Verify API key exists in Dashboard → API Keys and pass in x-api-key or Authorization: Bearer. |
| 402 | insufficient_credits |
Account credit balance is lower than the base required credits (1 credits). | Top up credits in billing settings or enable auto-recharge to prevent pipeline interruption. |
| 422 | validation_error |
Input failed parameter constraints (e.g., character length exceeded or invalid array types). | Review parameters table above and adjust payload length, types, or structure accordingly. |
| 429 | rate_limit_exceeded |
Concurrency limit (60 requests/minute default) reached for this endpoint key. | Back off and retry using the timestamp in Retry-After response header, or batch requests. |