Documentation
Full reference for all Mulat AI V3 API endpoints
Mulat AI V3 — API Reference
V3 LIVEMulat AI V3 provides 8 production endpoints across four capability groups — Translate, Chat, OCR, and Voice. Each group has two variants: int (international: EN, FR, ZH, TR, AR) and native (African: AM, OM, SO, TI, SW).
V1 endpoints are no longer actively developed. They remain accessible but will be removed in a future release. Migrate to V3 — see the .
Authentication
Every V3 request requires a Bearer token in the Authorization header. Get your key from the Dashboard.
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
MULAT_E001No header401MULAT_E002Invalid key401MULAT_E004Key disabled403Translate
Translate · Fast
POSTV3https://mulat.dev/api/external/v3/mulat_ai/translate/fastSingle-text, context-aware translation between any language pair. Specializes in EN, FR, ZH, TR, AR (int) and AM, OM, SO, TI, SW (native). Powered by Mulat AI.
Request Body Parameters
textstringREQUIREDThe text to translatesourceLangstringREQUIREDSource language name or code (e.g. "English", "en", "Amharic")targetLangstringREQUIREDTarget language name or codepreserveFormattingbooleanoptionalPreserve line breaks and structure. Default: falseconst res = await fetch('https://mulat.dev/api/external/v3/mulat_ai/translate/fast', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
text: 'Hello, how are you today?',
sourceLang: 'English',
targetLang: 'Amharic',
}),
});
const { success, translation, usage } = await res.json();
// translation → "ሰላም፣ ዛሬ እንዴት ናችሁ?"Success Response (200)
{
"success": true,
"translation": "ሰላም፣ ዛሬ እንዴት ናችሁ?",
"sourceLang": "English",
"targetLang": "Amharic",
"usage": {
"input_tokens": 42,
"output_tokens": 18
},
"model": "gemini-2.5-flash-lite",
"latency_ms": 430,
"version": "v3"
}Translate · Batch
POSTV3https://mulat.dev/api/external/v3/mulat_ai/translate/batchTranslate up to 100 items in a single request. Returns a JSON array of translated strings in order. Ideal for data pipelines and content platforms. Powered by Mulat AI.
Request Body Parameters
itemsstring[]REQUIREDArray of strings to translate (max 100 items, ~400k total chars)sourceLangstringREQUIREDSource language name or codetargetLangstringREQUIREDTarget language name or codepreserveFormattingbooleanoptionalPreserve formatting per item. Default: falseconst res = await fetch('https://mulat.dev/api/external/v3/mulat_ai/translate/batch', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
items: ['Hello', 'Good morning', 'Thank you'],
sourceLang: 'English',
targetLang: 'Amharic',
}),
});
const { translations } = await res.json();
// translations → ["ሰላም", "እንደምን አደሩ", "አመሰግናለሁ"]Success Response (200)
{
"success": true,
"translations": ["ሰላም", "እንደምን አደሩ", "አመሰግናለሁ"],
"count": 3,
"sourceLang": "English",
"targetLang": "Amharic",
"usage": { "input_tokens": 85, "output_tokens": 40 },
"model": "gemini-2.5-flash-lite",
"latency_ms": 820,
"version": "v3"
}Chat
Chat · International
POSTV3https://mulat.dev/api/external/v3/mulat_ai/chat/intMulti-turn conversational AI optimized for English, French, Simplified Chinese, Turkish, and Arabic. Supports conversation history and context injection. Powered by Mulat AI.
Request Body Parameters
messagestringREQUIREDThe user's messagelanguagestringoptionalForce response language (e.g. "French"). Default: auto-detecthistoryarrayoptional[{role:"user"|"assistant", content:string}] — previous turnscontextstringoptionalOptional context string prepended to the system promptconst res = await fetch('https://mulat.dev/api/external/v3/mulat_ai/chat/int', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
message: 'Tell me about Ethiopia',
language: 'English',
history: [
{ role: 'user', content: 'Hi!' },
{ role: 'assistant', content: 'Hello! How can I help you?' },
],
}),
});
const { reply, usage } = await res.json();Success Response (200)
{
"success": true,
"reply": "Ethiopia is a landlocked country in the Horn of Africa...",
"language": "English",
"usage": {
"input_tokens": 58,
"output_tokens": 112,
"thinking_tokens": 340
},
"model": "gemini-2.5-flash",
"latency_ms": 1240,
"version": "v3"
}Chat · Native African Languages
POSTV3https://mulat.dev/api/external/v3/mulat_ai/chat/nativeDeeply specialized for Amharic, Afan Oromo, Af Somali, Tigrinya, and Kiswahili. Understands grammar, proverbs, cultural context, and African worldviews. Supports four modes.
Request Body Parameters
messagestringREQUIREDThe user's message in any supported languagelanguagestringoptional"Amharic" | "Afan Oromo" | "Af Somali" | "Tigrinya" | "Kiswahili" — or automodestringoptional"general" | "explain" | "translate" | "proverbs". Default: generalhistoryarrayoptionalMulti-turn conversation historycontextstringoptionalOptional context stringconst res = await fetch('https://mulat.dev/api/external/v3/mulat_ai/chat/native', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
message: 'ሰላም! ስለ ኢትዮጵያ ንገረኝ።',
language: 'Amharic',
mode: 'explain', // 'general' | 'explain' | 'translate' | 'proverbs'
}),
});
const { reply } = await res.json();Success Response (200)
{
"success": true,
"reply": "ሰላም! ኢትዮጵያ በአፍሪካ ቀንድ ውስጥ ትገኛለች...",
"language": "Amharic",
"mode": "general",
"usage": { "input_tokens": 64, "output_tokens": 98, "thinking_tokens": 280 },
"model": "gemini-2.5-flash",
"latency_ms": 1100,
"version": "v3"
}OCR
OCR · International
POSTV3https://mulat.dev/api/external/v3/mulat_ai/ocr/intExtract text from images — Latin, Arabic, CJK (Chinese/Japanese/Korean) scripts. Accepts base64-encoded image or a public image URL. Powered by Gemini 1.5 Flash vision.
Request Body Parameters
imageBase64stringoptionalBase64-encoded image data (must also pass mimeType)imageUrlstringoptionalPublic URL of the image. Used if imageBase64 is omitted.mimeTypestringoptionalMIME type when using base64: image/jpeg | image/png | image/webp | image/gif. Default: image/jpeglanguagestringoptionalDocument language hint (e.g. "French"). Default: autooutputFormatstringoptional"plain" | "markdown". Default: plain// Using a URL
const res = await fetch('https://mulat.dev/api/external/v3/mulat_ai/ocr/int', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
imageUrl: 'https://example.com/document.jpg',
outputFormat: 'markdown',
}),
});
const { text } = await res.json();
// Or using base64
body: JSON.stringify({
imageBase64: btoa(binaryImageData),
mimeType: 'image/png',
})Success Response (200)
{
"success": true,
"text": "Invoice
Date: September 15, 2026
Amount: $450.00",
"language": "auto",
"output_format": "plain",
"usage": { "input_tokens": 890, "output_tokens": 64 },
"model": "gemini-1.5-flash",
"latency_ms": 1600,
"version": "v3"
}OCR · Native African Scripts
POSTV3https://mulat.dev/api/external/v3/mulat_ai/ocr/nativeExtract text from images in Ethiopic (Ge'ez script), Somali, Kiswahili, and other African writing systems. Deep character recognition fine-tuned for native scripts.
Request Body Parameters
imageBase64stringoptionalBase64-encoded image dataimageUrlstringoptionalPublic URL of the imagemimeTypestringoptionalMIME type for base64. Default: image/jpeglanguagestringoptionalScript hint: "Amharic" | "Tigrinya" | "Af Somali" | "Kiswahili". Default: autooutputFormatstringoptional"plain" | "markdown". Default: plainconst res = await fetch('https://mulat.dev/api/external/v3/mulat_ai/ocr/native', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
imageUrl: 'https://example.com/amharic-doc.jpg',
language: 'Amharic', // 'Tigrinya' | 'Af Somali' | 'Kiswahili'
}),
});
const { text } = await res.json();Success Response (200)
{
"success": true,
"text": "ፕሬዚዳንት ሳህለ-ወርቅ ዘውዴ
ሪፐብሊክ ኢትዮጵያ",
"language": "Amharic",
"output_format": "plain",
"usage": { "input_tokens": 920, "output_tokens": 28 },
"model": "gemini-1.5-flash",
"latency_ms": 1450,
"version": "v3"
}Voice
Voice · International
POSTV3https://mulat.dev/api/external/v3/mulat_ai/voice/intAudio transcription for international languages. Accepts base64 audio or an audio URL. Supports MP3, WAV, OGG, WebM, AAC, FLAC. Outputs plain text, SRT subtitles, or WebVTT.
Request Body Parameters
audioBase64stringoptionalBase64-encoded audio data (pass mimeType too)audioUrlstringoptionalPublic URL of the audio filemimeTypestringoptionalaudio/mp3 | audio/wav | audio/ogg | audio/webm | audio/aac | audio/flac. Default: audio/mp3languagestringoptionalLanguage hint (e.g. "French"). Default: autooutputFormatstringoptional"text" | "srt" | "vtt". Default: textincludePunctuationbooleanoptionalAdd punctuation. Default: trueconst res = await fetch('https://mulat.dev/api/external/v3/mulat_ai/voice/int', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
audioUrl: 'https://example.com/recording.mp3',
outputFormat: 'srt', // 'text' | 'srt' | 'vtt'
language: 'auto',
}),
});
const { transcript } = await res.json();Success Response (200)
{
"success": true,
"transcript": "Hello, this is a test recording in English.",
"language": "auto",
"output_format": "text",
"usage": { "input_tokens": 1200, "output_tokens": 42 },
"model": "gemini-1.5-flash",
"latency_ms": 2100,
"version": "v3"
}Voice · Native African Languages
POSTV3https://mulat.dev/api/external/v3/mulat_ai/voice/nativeSpeech-to-text fine-tuned for Amharic, Afan Oromo, Af Somali, Tigrinya, and Kiswahili. Handles tonal patterns, code-switching, and native phonology accurately.
Request Body Parameters
audioBase64stringoptionalBase64-encoded audio dataaudioUrlstringoptionalPublic URL of the audio filemimeTypestringoptionalAudio MIME type. Default: audio/mp3languagestringoptional"Amharic" | "Afan Oromo" | "Af Somali" | "Tigrinya" | "Kiswahili". Default: autooutputFormatstringoptional"text" | "srt" | "vtt". Default: textincludePunctuationbooleanoptionalAdd punctuation. Default: trueconst res = await fetch('https://mulat.dev/api/external/v3/mulat_ai/voice/native', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
audioUrl: 'https://example.com/speech.mp3',
language: 'Amharic', // 'Afan Oromo' | 'Af Somali' | 'Tigrinya' | 'Kiswahili'
outputFormat: 'text',
}),
});
const { transcript } = await res.json();Success Response (200)
{
"success": true,
"transcript": "ሰላም፣ ይህ ሙከራ ቅጂ ነው።",
"language": "Amharic",
"output_format": "text",
"usage": { "input_tokens": 1400, "output_tokens": 38 },
"model": "gemini-1.5-flash",
"latency_ms": 2300,
"version": "v3"
}Error Codes
All V3 errors return a consistent shape with error_code, error message, and version: "v3".
{
"success": false,
"error_code": "MULAT_E005",
"error": "Rate limit exceeded. Upgrade your plan for higher limits.",
"version": "v3"
}MULAT_E001Missing Authorization header. Use: Authorization: Bearer YOUR_API_KEY
HTTP 401
MULAT_E002Invalid API key
HTTP 401
MULAT_E003API key is pending admin approval
HTTP 403
MULAT_E004API key is disabled
HTTP 403
MULAT_E005Rate limit exceeded. Upgrade your plan for higher limits.
HTTP 429
MULAT_E006Invalid JSON request body
HTTP 400
MULAT_E007Missing required field
HTTP 400
MULAT_E008Language not supported for this endpoint
HTTP 400
MULAT_E009Input too long. Reduce size or use a batch endpoint.
HTTP 400
MULAT_E010Batch size exceeded. Max 100 items per request.
HTTP 400
MULAT_E011Invalid or missing image. Provide valid base64 or imageUrl.
HTTP 400
MULAT_E012Invalid or missing audio. Provide valid base64 or audioUrl.
HTTP 400
MULAT_E013AI model error. Please retry.
HTTP 500
MULAT_E014This endpoint is currently disabled.
HTTP 503
MULAT_E015Internal server error.
HTTP 500
Supported Languages
International (int)
enfrzhtrarAll other languages also accepted — int endpoints are optimized for these 5.
Native African (native)
amomsotiswNative endpoints have deep cultural knowledge — not just translation.
V1 API — Deprecated
V1 endpoints remain accessible for existing integrations but are no longer actively developed. They will be removed in a future release. Migrate to the V3 equivalents below.
/api/external/v1/mulat_ai/chat/api/external/v1/mulat_ai/native/api/external/v1/mulat_ai/translate/api/external/v1/mulat_ai/core_translation/api/external/v1/mulat_ai/languagesQuick Migration — Translate
// BEFORE — V1
- POST /api/external/v1/mulat_ai/translate
- { "text": "Hello", "sourceLang": "en", "targetLang": "am" }
// AFTER — V3 (same body shape, new path)
+ POST /api/external/v3/mulat_ai/translate/fast
+ { "text": "Hello", "sourceLang": "en", "targetLang": "am" }
// Response adds: usage.input_tokens, usage.output_tokens, latency_ms, version: "v3"