AI services

Integrate AI translation

Send text and get back a translation between any two of 100 supported languages, priced by how much text you send.

Request

Send a JSON body:

Field	Meaning
`text`	text is required. Up to 10,000 characters (the console tester caps its own input tighter, at 1,000).
`sourceLanguage`	sourceLanguage is optional, one of the 100 supported codes below. When omitted, it defaults to "en" rather than being detected.
`targetLanguage`	targetLanguage is required, one of the 100 supported codes below.

Examples

curl -X POST https://core.roammoon.com/v1/ai/translation/translate \
  -H "X-API-Key: rm_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, world!", "sourceLanguage": "en", "targetLanguage": "vi"}'

Response

Returns the translated text along with what was actually charged:

JSON

{
  "translatedText": "Xin chào, thế giới!",
  "sourceLanguage": "en",
  "targetLanguage": "vi",
  "characterCount": 13,
  "creditsCharged": 1
}

Fields that matter

Field	Meaning
`translatedText`	The translated text.
`characterCount`	Length of the input text you sent.
`creditsCharged`	What this call actually cost: ceil(characterCount / 100), minimum 1.

Billing

Unlike the platform's other AI services, this one is priced by size rather than a flat rate per call: 1 credit per 100 characters of input text, rounded up, minimum 1 credit. A 10,000-character request costs at most 100 credits. Credits are charged only when the translation succeeds; every failure is refunded.

The charge policy is charge-on-success: credit is reserved when the request is accepted and only committed once processing succeeds. A failure refunds the reservation.

Supported languages

Both sourceLanguage and targetLanguage accept any of these 100 codes.

Language	Code	Language	Code
Afrikaans	`af`	Ganda	`lg`
Amharic	`am`	Lingala	`ln`
Arabic	`ar`	Lao	`lo`
Asturian	`ast`	Lithuanian	`lt`
Azerbaijani	`az`	Latvian	`lv`
Bashkir	`ba`	Malagasy	`mg`
Belarusian	`be`	Macedonian	`mk`
Bulgarian	`bg`	Malayalam	`ml`
Bengali	`bn`	Mongolian	`mn`
Breton	`br`	Marathi	`mr`
Bosnian	`bs`	Malay	`ms`
Catalan	`ca`	Burmese	`my`
Cebuano	`ceb`	Nepali	`ne`
Czech	`cs`	Dutch	`nl`
Welsh	`cy`	Norwegian	`no`
Danish	`da`	Northern Sotho	`ns`
German	`de`	Occitan	`oc`
Greek	`el`	Oriya	`or`
English	`en`	Punjabi	`pa`
Spanish	`es`	Polish	`pl`
Estonian	`et`	Pashto	`ps`
Persian	`fa`	Portuguese	`pt`
Fulah	`ff`	Romanian	`ro`
Finnish	`fi`	Russian	`ru`
French	`fr`	Sindhi	`sd`
Western Frisian	`fy`	Sinhala	`si`
Irish	`ga`	Slovak	`sk`
Scottish Gaelic	`gd`	Slovenian	`sl`
Galician	`gl`	Somali	`so`
Gujarati	`gu`	Albanian	`sq`
Hausa	`ha`	Serbian	`sr`
Hebrew	`he`	Swati	`ss`
Hindi	`hi`	Sundanese	`su`
Croatian	`hr`	Swedish	`sv`
Haitian Creole	`ht`	Swahili	`sw`
Hungarian	`hu`	Tamil	`ta`
Armenian	`hy`	Thai	`th`
Indonesian	`id`	Tagalog	`tl`
Igbo	`ig`	Tswana	`tn`
Iloko	`ilo`	Turkish	`tr`
Icelandic	`is`	Ukrainian	`uk`
Italian	`it`	Urdu	`ur`
Japanese	`ja`	Uzbek	`uz`
Javanese	`jv`	Vietnamese	`vi`
Georgian	`ka`	Wolof	`wo`
Kazakh	`kk`	Xhosa	`xh`
Khmer	`km`	Yiddish	`yi`
Kannada	`kn`	Yoruba	`yo`
Korean	`ko`	Chinese	`zh`
Luxembourgish	`lb`	Zulu	`zu`

Getting good results

Set sourceLanguage explicitly whenever your text isn't English. Leaving it out does not detect the language, it assumes English.
Shorter, well-formed sentences translate more reliably than long runs of text with mixed languages, slang, or heavy formatting.
This is machine translation, not a human review. For anything published, legal, or safety-critical, have a fluent speaker check the result before it goes out.

Errors

Every error uses the same shape. Branch on code, not on message, because messages can change.

JSON

{
  "error": {
    "code": "TEXT_TOO_LONG",
    "message": "The \"text\" field must be 10000 characters or fewer."
  }
}

HTTP	Code	What to do
401	`API_KEY_REQUIRED`	The X-API-Key header is missing.
401	`API_KEY_INVALID`	The key is wrong, disabled or expired. Check it or create a new one.
403	`API_KEY_FORBIDDEN`	The key is not permitted to use this service.
400	`INVALID_TRANSLATION_REQUEST`	The "text" field is missing or empty. No credit is charged.
400	`TEXT_TOO_LONG`	The text exceeds 10,000 characters. Shorten it or split it into multiple calls.
400	`UNSUPPORTED_LANGUAGE`	sourceLanguage or targetLanguage is not one of the supported codes.
402	`CREDIT_LIMIT_EXCEEDED`	The period's credits are exhausted. Upgrade or wait for the next period.
415	`JSON_BODY_REQUIRED`	Content-Type must be application/json.
429	`RATE_LIMIT_EXCEEDED`	Per-minute request limit exceeded. Slow down.
502	`TRANSLATION_UPSTREAM_ERROR`	The translation model could not complete the request. Retryable.

Retrying safely

502 is retryable, so use exponential backoff. Other errors return the same result on retry. Only a successful translation is charged, so retrying after a failure costs nothing extra. The exception is a network timeout: if the first attempt actually succeeded, the retry is charged as a second call.

Next: API reference →