LinguaFlow API

AI-powered translation, OCR, document extraction, and audio/video transcription with streaming support, glossary memory, and 40+ languages.

Overview

The LinguaFlow API provides a unified interface for:

• Text translation between 40+ languages with formality control
• Language detection from a text sample
• Image OCR + translation — extract text from images and translate it
• Document extraction + translation — extract text from PDFs, HTML, TXT, CSV, XML, etc and translate it
• Video transcription + translation — transcribe speech from video files with speaker identification
• Audio transcription + translation — transcribe speech from audio files with speaker identification

All endpoints accept optional memory (glossary terms and instructions) passed by the client to customise translations.

Base URL

All endpoints route through a single URL using the action query parameter:

For example, to translate text:

POST /api.do?action=translate HTTP/1.1
Host: your-domain.com
Authorization: Bearer demo
Content-Type: application/json

Authentication

All endpoints (except languages and openapi) require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

A dev key is available to test, the same is used in the frontend: demo.

Error Handling

Errors return a JSON object with an error string and an appropriate HTTP status code:

{
  "error": "Parameter \"text\" is required."
}

Status	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — missing or invalid API key
404	Endpoint not found — invalid action parameter
405	Method not allowed — wrong HTTP method
413	Request body too large
422	Unprocessable — e.g. no text found in image, no speech in audio
502	Upstream error — the AI model returned an error

For streaming requests, errors are delivered as SSE events:

event: error
data: {"error":"No speech detected in the audio."}

Streaming (SSE)

Set stream to true (JSON) or "1" (form-data) to receive results as Server-Sent Events. The response uses Content-Type: text/event-stream.

Event types

Event	Description
(default)	Translation chunk: data: {"content":"partial text..."}
extracted	OCR/transcription/extraction result (image, document, video, audio): data: {"extracted_text":"..."}
done	Stream complete: data: [DONE]
error	Error: data: {"error":"..."}

For image/document/video/audio endpoints, the extracted event fires first with the OCR, extracted text, or transcription, then translation chunks stream in.

Memory Bank

Glossary terms and custom instructions are client-side — no user data is stored on the server. Include an optional memory object with translation requests:

{
  "memory": {
    "glossary": [
      {
        "source_term": "cloud computing",
        "target_term": "computación en la nube",
        "source_lang": "en",
        "target_lang": "es"
      }
    ],
    "instructions": [
      { "text": "Always use British English spelling", "active": true },
      { "text": "Keep brand names in original language", "active": true }
    ]
  }
}

For multipart/form-data requests (image, document, video, audio), send memory as a JSON-encoded string field.

Translate Text

Request body — application/json

Field	Type	Required	Description
text	string	Yes	Source text to translate (max 5,000 characters)
target_lang	string	Yes	Target language ISO 639-1 code (e.g. es)
source_lang	string	No	Source language code, or auto to detect (default: auto)
formality	string	No	default, formal, or informal
stream	boolean	No	Enable SSE streaming (default: false)
memory	object	No	Client-side glossary and instructions

Example request

curl -X POST "https://translate.demo.efficientstack.com/api.do?action=translate" \
  -H "Authorization: Bearer demo" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The quick brown fox jumps over the lazy dog.",
    "target_lang": "es",
    "formality": "formal"
  }'

Response

{
  "translation": "El rápido zorro marrón salta sobre el perro perezoso."
}

Detect Language

Request body — application/json

Field	Type	Required	Description
text	string	Yes	Text sample to detect language from

Example

curl -X POST "https://translate.demo.efficientstack.com/api.do?action=detect" \
  -H "Authorization: Bearer demo" \
  -H "Content-Type: application/json" \
  -d '{"text": "Bonjour le monde"}'

Response

{
  "language": "fr"
}

Translate Image (OCR)

Extracts text from an image via OCR, then translates it. Supported formats: JPEG, PNG, GIF, WebP (max 7 MB).

Request — multipart/form-data

Field	Type	Required	Description
file	file	Yes	Image file to process
target_lang	string	Yes	Target language ISO 639-1 code
source_lang	string	No	Source language (default: auto)
formality	string	No	default, formal, or informal
stream	string	No	0 or 1 (default: 0)
memory	string	No	JSON-encoded memory object

Example

curl -X POST "https://translate.demo.efficientstack.com/api.do?action=image" \
  -H "Authorization: Bearer demo" \
  -F "file=@sign.jpg" \
  -F "target_lang=de"

Response

{
  "extracted_text": "Welcome to our store\nOpen daily 9am - 6pm",
  "translation": "Willkommen in unserem Geschäft\nTäglich geöffnet 9:00 - 18:00 Uhr"
}

Translate Document

Extracts text from a document and translates it. For text-based files (TXT, CSV, Markdown, JSON, JavaScript, CSS), text is read directly for instant extraction. For binary or markup formats (PDF, HTML, XML, RTF), Gemini is used for intelligent text extraction.

Supported formats: PDF, TXT, HTML, CSV, XML, Markdown, RTF, JSON, JavaScript, CSS (max 7 MB). Extracted text is capped at 20,000 characters.

Request — multipart/form-data

Field	Type	Required	Description
file	file	Yes	Document file to process
target_lang	string	Yes	Target language ISO 639-1 code
source_lang	string	No	Source language (default: auto)
formality	string	No	default, formal, or informal
stream	string	No	0 or 1 (default: 0)
memory	string	No	JSON-encoded memory object

Example

curl -X POST "https://translate.demo.efficientstack.com/api.do?action=document" \
  -H "Authorization: Bearer demo" \
  -F "file=@report.pdf" \
  -F "target_lang=es"

Response

{
  "extracted_text": "Quarterly Report\n\nRevenue increased by 15% compared to the previous quarter...",
  "translation": "Informe Trimestral\n\nLos ingresos aumentaron un 15% en comparación con el trimestre anterior..."
}

Transcribe & Translate Video

Transcribes spoken content from a video file with speaker identification, then translates the transcription. Supported formats: MP4, WebM, MOV (max 7 MB).

Request — multipart/form-data

Field	Type	Required	Description
file	file	Yes	Video file to process
target_lang	string	Yes	Target language ISO 639-1 code
source_lang	string	No	Source language (default: auto)
formality	string	No	default, formal, or informal
stream	string	No	0 or 1 (default: 0)
memory	string	No	JSON-encoded memory object

Example

curl -X POST "https://translate.demo.efficientstack.com/api.do?action=video" \
  -H "Authorization: Bearer demo" \
  -F "file=@interview.mp4" \
  -F "target_lang=fr" \
  -F "stream=0"

Response

The transcription uses a speaker-labelled format with Markdown-bold speaker names:

{
  "transcription": "**Host:** Welcome to the show. Today we have a special guest.\n**Guest:** Thank you for having me. It's great to be here.\n**Host:** Let's dive right in.",
  "translation": "**Présentateur :** Bienvenue dans l'émission. Aujourd'hui, nous avons un invité spécial.\n**Invité :** Merci de m'avoir invité. C'est formidable d'être ici.\n**Présentateur :** Allons-y directement."
}

Transcribe & Translate Audio

Identical behaviour to the video endpoint but for audio files. Supported formats: MP3, WAV, OGG, M4A, AAC, FLAC, WebM (max 7 MB).

Request — multipart/form-data

Same fields as the video endpoint.

Example

curl -X POST "https://translate.demo.efficientstack.com/api.do?action=audio" \
  -H "Authorization: Bearer demo" \
  -F "file=@podcast.mp3" \
  -F "target_lang=ja"

Response

{
  "transcription": "**Speaker 1:** Hello everyone and welcome back.\n**Speaker 2:** Thanks for having me on the show.",
  "translation": "**スピーカー1:** 皆さん、こんにちは。お帰りなさい。\n**スピーカー2:** 番組に呼んでいただきありがとうございます。"
}

Supported Languages

Response

{
  "languages": [
    { "code": "en", "name": "English" },
    { "code": "es", "name": "Spanish" },
    ...
  ]
}

All 40 supported languages

OpenAPI Specification

Returns the full OpenAPI 3.0.3 JSON specification. Use it with tools like:

• Swagger Editor
• Postman (import as OpenAPI)
• Any OpenAPI-compatible code generator

curl "https://translate.demo.efficientstack.com/api.do?action=openapi" | python -m json.tool