Quick Start
Three steps to your first translation:
- 1. Create an account at ravira.dev/register
- 2. Purchase a character pack and generate an API key in Settings → API
- 3. Make your first request:
curl -X POST https://ravira.dev/api/v1/translate \
-H "Authorization: Bearer rk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Hello, world!", "source_lang": "en", "target_lang": "ro"}'Response:
{
"translated_text": "Bună ziua, lume!",
"characters_charged": 13,
"source_lang": "en",
"target_lang": "ro"
}Authentication
All API requests require a Bearer token in the Authorization header. API keys start with rk_live_ and are generated in your account settings.
Authorization: Bearer rk_live_YOUR_API_KEYEndpoints
/api/v1/translateTranslate text. Requires authentication. Characters are charged on success.
| Parameter | Type | Required | Description |
|---|---|---|---|
| text | string | Yes | Text to translate (max 100,000 chars) |
| source_lang | string | No | Source language code. Default: auto |
| target_lang | string | No | Target language code. Default: en |
/api/v1/usageReturns current character balance and usage. Requires authentication.
curl https://ravira.dev/api/v1/usage \
-H "Authorization: Bearer rk_live_YOUR_API_KEY"{
"characters_balance": 500000,
"characters_used": 12500,
"characters_expires_at": "2027-01-01T00:00:00"
}/api/v1/languagesReturns list of supported languages. No authentication required.
curl https://ravira.dev/api/v1/languagesCode Examples
Python
import requests
API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"
def translate(text, target_lang="ro", source_lang="auto"):
response = requests.post(
f"{BASE_URL}/translate",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"text": text, "source_lang": source_lang, "target_lang": target_lang}
)
response.raise_for_status()
return response.json()["translated_text"]
result = translate("Hello, world!", target_lang="ro")
print(result) # Bună ziua, lume!JavaScript
const API_KEY = "rk_live_YOUR_API_KEY";
const BASE_URL = "https://ravira.dev/api/v1";
async function translate(text, targetLang = "ro", sourceLang = "auto") {
const response = await fetch(`${BASE_URL}/translate`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ text, source_lang: sourceLang, target_lang: targetLang }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
return data.translated_text;
}
const result = await translate("Hello, world!", "ro");
console.log(result); // Bună ziua, lume!AI Apps (MCP)
RAVIRA runs a Model Context Protocol (MCP) server. AI apps that support remote MCP servers, such as Claude, ChatGPT, Cursor, VS Code and Claude Code, can translate with RAVIRA directly from a chat, an editor or a terminal, using your RAVIRA balance.
Server URL
https://ravira.dev/mcpHow connecting works
- Add
https://ravira.dev/mcpas a remote (HTTP) MCP server in your app. - Your browser opens the RAVIRA connection page. Sign in if needed.
- Check the domain shown on the page, review the requested access and approve.
- The app appears in your Profile, API tab, under Connected applications, where you can disconnect it at any time.
Setup examples
Menus can change between app versions; the server URL is always the same.
Claude (claude.ai and the Claude apps)
Settings, Connectors, Add custom connector, then paste the server URL.
Claude Code (terminal)
claude mcp add --transport http ravira https://ravira.dev/mcpThen run /mcp inside Claude Code to sign in.
Cursor
{
"mcpServers": {
"ravira": { "url": "https://ravira.dev/mcp" }
}
}VS Code (.vscode/mcp.json)
{
"servers": {
"ravira": { "type": "http", "url": "https://ravira.dev/mcp" }
}
}ChatGPT
In settings, open Connectors (developer mode may need to be enabled) and create a custom connector with the server URL.
Available tools
| Tool | What it does | Permission |
|---|---|---|
ravira_translate | Translates text with the right terminology and your glossary | mcp_translate |
ravira_usage | Shows your character balance | mcp_usage |
ravira_languages | Lists the supported languages | mcp_languages |
ravira_user_glossary | Reads and edits your personal glossary | mcp_glossary |
Permissions and safety
- Each app gets only the access you approve on the RAVIRA connection page.
- Verified apps, such as Claude, connect without a warning. Other apps are marked Unverified and need an explicit confirmation. Apps running on your own computer (localhost), such as editors and command-line tools, are labelled as such.
- Unverified apps do not get access to your personal glossary unless they ask for it and you approve it.
- A connected app can only translate and read what its permissions allow. It cannot manage your account, API keys or payments.
- Resetting your password with Forgot password disconnects all apps and revokes all API keys.
Using an API key instead
Apps that let you set custom headers can use an API key instead of signing in:
Authorization: Bearer rk_live_YOUR_API_KEYConnections made with an API key do not appear under Connected applications. To stop them, revoke the key in your API keys list.
Error Codes
| HTTP | Error code | Description |
|---|---|---|
| 401 | invalid_api_key | Missing, invalid, or revoked API key. |
| 402 | insufficient_balance | Account has no characters remaining. Purchase more at ravira.dev/topup. |
| 429 | rate_limit_exceeded | Too many requests. Slow down and retry after the retry_after value (seconds). |
| 400 | validation_error | Invalid request parameters. |
| 500 | server_error | Internal server error. Retry after a short delay. |
Rate Limits
Rate limits apply per account, not per API key.
- 60 requests/minute per account across all API keys
- When exceeded, the API returns
HTTP 429with aretry_afterfield (seconds) - Up to 5 API keys per account for project organization
Use Cases
Multilingual product listings
A seller on Amazon or eBay wants to list products in 5 languages automatically. One API call per language, with consistent terminology across all markets.
import requests
API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"
def translate_product(product):
languages = {"ro": "Romanian", "de": "German", "fr": "French", "es": "Spanish"}
translations = {}
for lang_code, lang_name in languages.items():
response = requests.post(
BASE_URL + "/translate",
headers={"Authorization": "Bearer " + API_KEY},
json={"text": product["title"] + "
" + product["description"],
"source_lang": "en", "target_lang": lang_code}
)
translations[lang_code] = response.json()["translated_text"]
return translations
product = {
"title": "Wireless Noise-Cancelling Headphones",
"description": "Premium over-ear headphones with 30-hour battery."
}
result = translate_product(product)Localized user notifications
A SaaS platform translates all notification templates when a new user sets their preferred language. No static translation files: dynamic and always up to date.
const API_KEY = "rk_live_YOUR_API_KEY";
const BASE_URL = "https://ravira.dev/api/v1";
async function localizeNotifications(userId, targetLang) {
const templates = {
welcome: "Welcome to our platform! Your account is ready.",
trial_ending: "Your free trial ends in 3 days.",
payment_success: "Payment confirmed. Thank you!",
usage_alert: "You have used 80% of your monthly quota."
};
const localized = {};
for (const [key, text] of Object.entries(templates)) {
const res = await fetch(BASE_URL + "/translate", {
method: "POST",
headers: {
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({ text, source_lang: "en", target_lang: targetLang })
});
localized[key] = (await res.json()).translated_text;
}
return localized;
}
// New user from Romania
localizeNotifications("user_123", "ro").then(t => {
console.log(t.welcome);
});Contract pre-translation
A law firm receives contracts in foreign languages and needs a fast pre-translation before sending to a certified translator. Consistent legal terminology saves review time.
import requests
API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"
def pretranslate_contract(contract_text, source_lang):
"""Pre-translate a contract for internal review."""
response = requests.post(
BASE_URL + "/translate",
headers={"Authorization": "Bearer " + API_KEY},
json={
"text": contract_text,
"source_lang": source_lang,
"target_lang": "en"
}
)
return response.json()["translated_text"]
# Translate a German contract for English-speaking lawyers
with open("vertrag_2026.txt", "r") as f:
german_contract = f.read()
english_draft = pretranslate_contract(german_contract, "de")
print("Pre-translation ready for legal review.")
print(english_draft[:200])International news monitoring
A newsroom monitors international sources and automatically translates relevant articles for editors. Runs as a scheduled job every hour.
import requests
import schedule
import time
API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"
def translate_article(article, source_lang):
response = requests.post(
BASE_URL + "/translate",
headers={"Authorization": "Bearer " + API_KEY},
json={"text": article, "source_lang": source_lang, "target_lang": "en"}
)
return response.json()["translated_text"]
def monitor_and_translate():
# Fetch articles from your news source here
articles = [
{"text": "Neue Wirtschaftsdaten zeigen starkes Wachstum...", "lang": "de"},
{"text": "Les negociations commerciales reprennent...", "lang": "fr"},
]
for article in articles:
translated = translate_article(article["text"], article["lang"])
print("Translated:", translated[:80] + "...")
# Run every hour
schedule.every().hour.do(monitor_and_translate)
monitor_and_translate() # Run immediately on startMultilingual job postings
A company posting jobs across Europe translates each listing automatically. One source in English, published in 6 languages within seconds.
const API_KEY = "rk_live_YOUR_API_KEY";
const BASE_URL = "https://ravira.dev/api/v1";
const TARGET_MARKETS = ["de", "fr", "es", "it", "pl", "ro"];
async function publishJobPosting(jobDescription) {
const postings = {};
for (const lang of TARGET_MARKETS) {
const res = await fetch(BASE_URL + "/translate", {
method: "POST",
headers: {
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
text: jobDescription,
source_lang: "en",
target_lang: lang
})
});
postings[lang] = (await res.json()).translated_text;
}
console.log("Published in " + Object.keys(postings).length + " languages");
return postings;
}
const job = "Senior Backend Engineer. Remote. Competitive salary.";
publishJobPosting(job);Software documentation
A developer tool translates its documentation to reach international users. Markdown files are translated while code blocks remain untouched.
import requests
import re
API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"
def translate_markdown(md_text, target_lang):
"""Translate markdown, preserving code blocks."""
# Extract code blocks before translation
code_blocks = {}
def save_code(match):
key = f"CODE_BLOCK_{len(code_blocks)}"
code_blocks[key] = match.group(0)
return key
protected = re.sub(r"```[\s\S]*?```", save_code, md_text)
# Translate text only
response = requests.post(
BASE_URL + "/translate",
headers={"Authorization": "Bearer " + API_KEY},
json={"text": protected, "source_lang": "en", "target_lang": target_lang}
)
translated = response.json()["translated_text"]
# Restore code blocks
for key, block in code_blocks.items():
translated = translated.replace(key, block)
return translated
with open("README.md") as f:
readme = f.read()
translated_readme = translate_markdown(readme, "ro")
print(translated_readme[:300])Patient intake forms
A clinic translates patient intake forms for international patients. For internal use and patient comfort, always reviewed by qualified medical staff before clinical decisions.
import requests
API_KEY = "rk_live_YOUR_API_KEY"
BASE_URL = "https://ravira.dev/api/v1"
def translate_intake_form(form_data, patient_lang):
"""
Translate patient intake form for non-English speaking patients.
For internal use only. Always reviewed by qualified medical staff.
"""
fields_to_translate = [
"chief_complaint", "medical_history", "current_medications", "allergies"
]
translated = {}
for field in fields_to_translate:
if field in form_data:
response = requests.post(
BASE_URL + "/translate",
headers={"Authorization": "Bearer " + API_KEY},
json={
"text": form_data[field],
"source_lang": patient_lang,
"target_lang": "en"
}
)
translated[field] = response.json()["translated_text"]
return translated
patient_form = {
"chief_complaint": "Durere puternica in piept de 2 zile",
"allergies": "Penicilina, Ibuprofen"
}
english_form = translate_intake_form(patient_form, "ro")
print("For medical staff review:", english_form)