API_DOCUMENTATION

Zaban Backend — API Documentation

Server-hosted APIs for Speech-to-Text (STT), Text-to-Speech (TTS), Translation, Transliteration, and Language Detection. Base URL for all endpoints: http://localhost:8000 (or your deployed host). API version prefix: /api/v1.

1. Authentication

Endpoints that require an API key

Endpoint	Requires `X-API-Key`	Reason
`POST /api/v1/translate`	Yes	Protected endpoint requiring authentication
`POST /api/v1/tts`	Yes	Protected endpoint requiring authentication
`POST /api/v1/stt`	Yes	Protected endpoint requiring authentication
`POST /api/v1/transliterate`	Yes	Protected endpoint requiring authentication
`POST /api/v1/detect-language`	Yes	Protected endpoint requiring authentication
`POST/GET/DELETE /api/v1/api-keys*`	No	Uses JWT Bearer token instead (see API key management)

Note: All API endpoints (Translation, TTS, STT, Transliteration, and Language Detection) require API key authentication. Only the API key management endpoints use JWT Bearer tokens instead.

For all API endpoints, you must send your API key in the header:

X-API-Key: sk-your-secret-key

Important: If you omit the X-API-Key header for any API endpoint, you will receive a 401 Unauthorized error with the message "X-API-Key header missing".

API keys are created after logging in (e.g. Google OAuth). See API key management and Authentication flow below.

Authentication flow

Get Google OAuth code (browser):

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8000/auth/callback&response_type=code&scope=openid%20email%20profile&prompt=consent

Exchange code for JWT:

curl -X POST http://localhost:8000/api/v1/auth/google/login \
  -H "Content-Type: application/json" \
  -d '{"code":"YOUR_CODE","redirect_uri":"http://localhost:8000/auth/callback"}'

Create API key (use the JWT from step 2):

curl -X POST http://localhost:8000/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Key"}'

Response includes secret_key (e.g. sk-...) — use it as X-API-Key; it is only returned once.

2. Speech-to-Text (STT)

Transcribe or translate speech to text. Accepts multipart form (audio file) or JSON (audio URL).

Endpoint: POST /api/v1/stt
Authentication: Required. Header: X-API-Key: sk-...

Important: The STT endpoint requires API key authentication. You must include the X-API-Key header in your request, or you will receive a 401 Unauthorized error.

Option A: Multipart form (audio file)

Parameter	Location	Required	Description
`audio`	form (file)	Yes	Audio file (WAV, MP3, M4A, WebM, OGG, FLAC, etc.)
`lang`	form	No	Language code (2-letter or BCP-47). Omit for auto-detect.
`model`	form	No	`whisper` (default) or `ai4bharat`.
`format`	form	No	Output format (optional).
`translate_to_english`	form	No	`true`/`false`. If `true`, output is translated to English.

Models:

whisper (default): faster-whisper, 100+ languages, auto-detect.
ai4bharat: Vistaar IndicWhisper; best for Indian languages (hi, mr, ta, te, bn, gu, kn, ml, pa, or, sa, ur). Requires lang when using this model.

cURL — multipart (file)

# Basic: audio file, auto-detect language
curl -X POST http://localhost:8000/api/v1/stt \
  -H "X-API-Key: sk-your-secret-key" \
  -F "audio=@/path/to/recording.wav"

# With language hint
curl -X POST http://localhost:8000/api/v1/stt \
  -H "X-API-Key: sk-your-secret-key" \
  -F "audio=@recording.webm" \
  -F "lang=hi"

# With model and translate to English
curl -X POST http://localhost:8000/api/v1/stt \
  -H "X-API-Key: sk-your-secret-key" \
  -F "audio=@recording.wav" \
  -F "lang=hi" \
  -F "model=whisper" \
  -F "translate_to_english=true"

# Use IndicWhisper (Indian languages) — lang required
curl -X POST http://localhost:8000/api/v1/stt \
  -H "X-API-Key: sk-your-secret-key" \
  -F "audio=@hindi_speech.wav" \
  -F "lang=hi" \
  -F "model=ai4bharat"

Option B: JSON (audio URL)

Parameter	Type	Required	Description
`audio_url`	string	Yes	Public URL of the audio file.
`lang`	string	No*	Language code. *Required if `model` is `ai4bharat`.
`model`	string	No	`whisper` (default) or `ai4bharat`.
`format`	string	No	Output format.
`translate_to_english`	boolean	No	If `true`, output is translated to English.

cURL — JSON (URL)

curl -X POST http://localhost:8000/api/v1/stt \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-secret-key" \
  -d '{
    "audio_url": "https://example.com/audio.wav",
    "lang": "hi",
    "model": "whisper",
    "translate_to_english": false
  }'

Response (normal)

{
  "text": "Transcribed text here",
  "language": "hin_Deva",
  "language_probability": 0.98,
  "model": "faster-whisper",
  "auto_detected": true,
  "segments": []
}

Response (when `translate_to_english=true`)

{
  "text": "Transcribed and translated text in English",
  "language": "hin_Deva",
  "language_probability": 0.98,
  "model": "faster-whisper",
  "auto_detected": false,
  "translated_text": "Same as text when using Whisper translate",
  "target_lang": "eng_Latn",
  "translation_model": "whisper-translate",
  "segments": []
}

3. Text-to-Speech (TTS)

Synthesize speech from text (IndicParler TTS locally, or external AI4Bharat when configured).

Endpoint: POST /api/v1/tts
Authentication: Required. Header: X-API-Key: sk-...

Request body (JSON)

Parameter	Type	Required	Description
`text`	string	Yes	Text to convert to speech.
`language` / `lang`	string	No	2-letter ISO 639-1 (e.g. `hi`, `en`). Auto-detected if omitted.
`voice_description` / `description`	string	No	Description of desired voice.
`speaker`	string	No	Speaker name for consistent voice.
`sample_rate`	integer	No	Used only when external TTS API is configured.
`format`	string	No	Used only when external API; e.g. `wav`.

Supported languages (21): as, bn, brx, en, gu, hi, kn, ks, ml, mni, mr, ne, or, pa, sa, sd, ta, te, ur, doi, kok.

cURL examples

# Minimal
curl -X POST http://localhost:8000/api/v1/tts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-secret-key" \
  -d '{"text": "नमस्ते"}'

# With language and speaker
curl -X POST http://localhost:8000/api/v1/tts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-secret-key" \
  -d '{"text": "Hello world", "language": "en", "speaker": "female"}'

# Save response as WAV file
curl -X POST http://localhost:8000/api/v1/tts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-secret-key" \
  -d '{"text": "नमस्ते", "lang": "hi"}' \
  -o speech.wav

Response

Body: Binary audio (WAV).
Headers:
- Content-Type: audio/wav
- X-Sample-Rate: sample rate
- X-Language: language used
- X-Model: model name
- X-Speaker: speaker (or default)
- Content-Disposition: attachment; filename="speech.wav"

4. Translation

Translate text between languages (IndicTrans2 locally or external API when configured).

Endpoint: POST /api/v1/translate
Authentication: Required. Header: X-API-Key: sk-...

Request body (JSON)

Parameter	Type	Required	Description
`text`	string	Yes	Text to translate.
`target_lang`	string	Yes	Target language (BCP-47, e.g. `hin_Deva`, `eng_Latn`).
`source_lang`	string	No	Source language (BCP-47). Omit or use with `auto_detect` for auto-detection.
`auto_detect`	boolean	No	If `true`, source language is auto-detected (FastText + script).
`domain`	string	No	Used only when external translation API is configured.

cURL examples

# Explicit source and target
curl -X POST http://localhost:8000/api/v1/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-secret-key" \
  -d '{
    "text": "How are you?",
    "source_lang": "eng_Latn",
    "target_lang": "hin_Deva"
  }'

# Auto-detect source language
curl -X POST http://localhost:8000/api/v1/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-secret-key" \
  -d '{
    "text": "नमस्ते दुनिया",
    "target_lang": "eng_Latn",
    "auto_detect": true
  }'

Response

{
  "translated_text": "आप कैसे हैं?",
  "source_lang": "eng_Latn",
  "target_lang": "hin_Deva",
  "model": "indictrans2-local",
  "auto_detected": false
}

Supported languages: see Language codes reference (IndicTrans2: 22 languages including English and major Indian languages).

5. Transliteration

Convert text between scripts (e.g. Latin → Devanagari). Uses external AI4Bharat transliteration API when AI4B_TRANSLITERATE_URL is set.

Endpoint: POST /api/v1/transliterate
Authentication: Required. Header: X-API-Key: sk-...

Request body (JSON)

Parameter	Type	Required	Description
`text`	string	Yes	Text to transliterate.
`source_script`	string	Yes	Source script (e.g. `latn`, `deva`).
`target_script`	string	Yes	Target script.
`lang`	string	Yes	Language code (e.g. `hi`).
`topk`	integer	No	Default `1`.

cURL example

curl -X POST http://localhost:8000/api/v1/transliterate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-secret-key" \
  -d '{
    "text": "namaste",
    "source_script": "latn",
    "target_script": "deva",
    "lang": "hi",
    "topk": 1
  }'

Response

Structure depends on the external transliteration API; typically includes transliterated text and possibly alternatives when topk > 1.

6. Language detection

Detect language of text (FastText).

Endpoint: POST /api/v1/detect-language
Authentication: Required. Header: X-API-Key: sk-...

Request body (JSON)

Parameter	Type	Required	Description
`text`	string	Yes	Non-empty text to analyze.

cURL example

curl -X POST http://localhost:8000/api/v1/detect-language \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-your-secret-key" \
  -d '{"text": "नमस्ते दुनिया"}'

Response

{
  "detected_lang": "hin_Deva",
  "confidence": 0.95,
  "method": "fasttext",
  "is_auto_detected": true
}

7. API key management

All API key endpoints require a JWT in the header: Authorization: Bearer YOUR_JWT_TOKEN (from Google OAuth login). They do not use X-API-Key.

Method	Endpoint	Description
POST	`/api/v1/api-keys`	Create API key (returns `secret_key` once).
GET	`/api/v1/api-keys`	List current user’s API keys.
GET	`/api/v1/api-keys/{key_id}`	Get one API key (metadata only).
DELETE	`/api/v1/api-keys/{key_id}`	Deactivate/delete API key.

Create API key

Request body (optional):

Parameter	Type	Required	Description
`name`	string	No	Label for the key.

curl -X POST http://localhost:8000/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Key"}'

Response:

{
  "id": "uuid-here",
  "name": "My Key",
  "secret_key": "sk-ewVR1t_HMn57DRmVu..."
}

Use secret_key as X-API-Key for /translate and /tts. It is only returned at creation.

List API keys

curl -X GET http://localhost:8000/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "api_keys": [
    {
      "id": "uuid",
      "name": "My Key",
      "is_active": true,
      "created_at": "2025-10-23T06:59:12",
      "revoked_at": null,
      "secret_key_prefix": "sk-***"
    }
  ],
  "total": 1
}

Get one API key

curl -X GET http://localhost:8000/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Delete (deactivate) API key

curl -X DELETE http://localhost:8000/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Returns 204 No Content on success.

8. Health & UI endpoints

Method	Endpoint	Description
GET	`/up`	Health check. Returns `{"status": "ok"}`.
GET	`/translate-ui`	Serves translation test HTML page (if present).
GET	`/stt-ui`	Serves STT test HTML page (if present).

curl http://localhost:8000/up

9. Language codes reference

BCP-47 (translation, detection, STT response)

Language	Code
English	`eng_Latn`
Hindi	`hin_Deva`
Bengali	`ben_Beng`
Tamil	`tam_Taml`
Telugu	`tel_Telu`
Gujarati	`guj_Gujr`
Kannada	`kan_Knda`
Malayalam	`mal_Mlym`
Marathi	`mar_Deva`
Punjabi	`pan_Guru`
Odia	`ory_Orya`
Assamese	`asm_Beng`
Urdu	`urd_Arab`
Kashmiri (Arabic)	`kas_Arab`
Kashmiri (Devanagari)	`kas_Deva`
Konkani	`gom_Deva`
Manipuri (Bengali)	`mni_Beng`
Manipuri (Meitei)	`mni_Mtei`
Nepali	`npi_Deva`
Sanskrit	`san_Deva`
Santali	`sat_Olck`
Sindhi (Arabic)	`snd_Arab`
Sindhi (Devanagari)	`snd_Deva`

TTS accepts 2-letter codes (e.g. hi, en) or BCP-47; it normalizes internally.

10. Errors

HTTP	Cause	Action
400	Bad request (missing/invalid params, invalid body)	Check required fields and types.
401	`X-API-Key header missing`	Send `X-API-Key: sk-...` for all API endpoints (`/translate`, `/tts`, `/stt`, `/transliterate`, `/detect-language`).
401	`Invalid or inactive API key`	Create a new API key or use a valid one.
401	`Missing bearer token` / `Invalid token`	Use a valid JWT for API key management endpoints.
404	API key or resource not found	Check ID and that the key belongs to the current user.
500	Service/model error (e.g. IndicParler, external API)	Check server logs and env configuration.

Error responses are typically JSON, e.g.:

{"detail": "audio_url is required"}

Summary: which header for which endpoint

Endpoint	Header
`POST /api/v1/stt`	`X-API-Key: sk-...`
`POST /api/v1/tts`	`X-API-Key: sk-...`
`POST /api/v1/translate`	`X-API-Key: sk-...`
`POST /api/v1/transliterate`	`X-API-Key: sk-...`
`POST /api/v1/detect-language`	`X-API-Key: sk-...`
`POST/GET/DELETE /api/v1/api-keys*`	`Authorization: Bearer <JWT>`

Replace http://localhost:8000 with your server base URL when using a deployed host.

API_DOCUMENTATION

Zaban Backend — API Documentation

Table of contents

1. Authentication

Endpoints that require an API key

Authentication flow

2. Speech-to-Text (STT)

Option A: Multipart form (audio file)

cURL — multipart (file)

Option B: JSON (audio URL)

cURL — JSON (URL)

Response (normal)

Response (when translate_to_english=true)

3. Text-to-Speech (TTS)

Request body (JSON)

cURL examples

Response

4. Translation

Request body (JSON)

cURL examples

Response

5. Transliteration

Request body (JSON)

cURL example

Response

6. Language detection

Request body (JSON)

cURL example

Response

7. API key management

Create API key

List API keys

Get one API key

Delete (deactivate) API key

8. Health & UI endpoints

9. Language codes reference

BCP-47 (translation, detection, STT response)

10. Errors

Summary: which header for which endpoint

Uh oh!

Clone this wiki locally

Response (when `translate_to_english=true`)