FreedomSpeech API

https://freedomspeech.kz/docs
Admin
FreedomSpeech API offers Kazakh speech synthesis, recognition, voice cloning, and translation...
Tokens:9,709
Snippets:71
Trust Score:2.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Complete WebSocket ASR Example

Source: https://freedomspeech.kz/docs

A full example demonstrating WebSocket connection, message handling for ready, partial, and final states, and starting/stopping audio recording.

```javascript
const ws = new WebSocket(
  "wss://freedomspeech.kz/ws/asr?apiKey=YOUR_API_KEY"
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "ready") {
    // Start sending audio
    startRecording();
  }
  if (msg.type === "partial") {
    console.log("Partial:", msg.text);
  }
  if (msg.type === "final") {
    console.log("Final:", msg.text);
    ws.close();
  }
};

function stopRecording() {
  ws.send(JSON.stringify({ type: "stop" }));
}

// Connection auto-closes after 15s of inactivity

```

--------------------------------

### Complete WebSocket TTS Streaming Example

Source: https://freedomspeech.kz/docs

A full example demonstrating how to connect, send a synthesis request, and process incoming audio chunks and the end-of-audio signal.

```javascript
const ws = new WebSocket(
  "wss://freedomspeech.kz/ws/tts?apiKey=YOUR_API_KEY"
);

const chunks = [];

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "synthesize",
    text: "Сәлеметсіз бе",
    voice: "tomiris",
    emotion: "neutral",
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "audio_chunk") {
    chunks.push(msg.audio); // base64 PCM int16
  }
  if (msg.type === "audio_end") {
    console.log("Done:", msg.totalChunks, "chunks");
    ws.close();
  }
};
```

--------------------------------

### Complete Example Implementation

Source: https://freedomspeech.kz/docs

A comprehensive example demonstrating how to establish a WebSocket connection, handle incoming messages for 'ready', 'partial', and 'final' transcription statuses, and initiate the stop signal.

```APIDOC
### Complete Example
```javascript
const ws = new WebSocket(
  "wss://freedomspeech.kz/ws/asr?apiKey=YOUR_API_KEY"
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "ready") {
    // Start sending audio
    startRecording();
  }
  if (msg.type === "partial") {
    console.log("Partial:", msg.text);
  }
  if (msg.type === "final") {
    console.log("Final:", msg.text);
    ws.close();
  }
};

function stopRecording() {
  ws.send(JSON.stringify({ type: "stop" }));
}

// Connection auto-closes after 15s of inactivity
```
```

--------------------------------

### Generate Voice with cURL

Source: https://freedomspeech.kz/docs

Example of how to generate a voice using the Voice Design API with cURL. Ensure to replace 'YOUR_API_KEY' with your actual API key.

```bash
curl -X POST https://freedomspeech.kz/api/voice-design \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Сәлеметсіз бе, менің атым Қазақ",
    "instruct": "young woman, soft voice, medium pace",
    "language": "kz"
  }'
```

--------------------------------

### Generate Voice with Python

Source: https://freedomspeech.kz/docs

Example of how to generate a voice using the Voice Design API with Python's requests library. This snippet also shows how to decode the base64 WAV output and save it to a file. Ensure to replace 'YOUR_API_KEY' with your actual API key.

```python
import requests, base64

resp = requests.post(
    "https://freedomspeech.kz/api/voice-design",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "text": "Сәлеметсіз бе",
        "instruct": "young woman, soft voice, medium pace",
        "language": "kz",
    },
)
data = resp.json()
with open("designed.wav", "wb") as f:
    f.write(base64.b64decode(data["voice_clone_wav_base64"]))

```

--------------------------------

### Text with Non-Verbal Tags (Example)

Source: https://freedomspeech.kz/docs

This example shows how to insert non-verbal sounds like sighs into the text for the Tomiris voice. Ensure the voice selected supports these tags.

```text
Сәлеметсіз бе <sigh> мен шаршадым
```

--------------------------------

### Example API Response for Voices

Source: https://freedomspeech.kz/docs

This is an example of the JSON response you will receive when calling the /api/voices endpoint. It shows the structure of voice objects, including their IDs, names, and types.

```json
[
  { "id": "tomiris", "name": "Tomiris", "type": "builtin" },
  { "id": "shrek", "name": "Shrek", "type": "custom" },
  ...
]
```

--------------------------------

### List Supported Languages

Source: https://freedomspeech.kz/docs

Retrieve a list of supported source and target languages from the /v2/languages endpoint. No authentication is required.

```bash
curl https://freedomspeech.kz/v2/languages
```

--------------------------------

### Connect to WebSocket API

Source: https://freedomspeech.kz/docs

Establishes a WebSocket connection to the ASR service. Include your API key and optionally enable prettified output.

```javascript
const ws = new WebSocket(
  "wss://freedomspeech.kz/ws/asr?apiKey=YOUR_API_KEY&prettify=true"
);
```

--------------------------------

### Synthesize Text to Speech (Bash)

Source: https://freedomspeech.kz/docs

Use this command to send a POST request to the Text-to-Speech API to synthesize text into a WAV audio file. Ensure you replace YOUR_API_KEY with your actual API key.

```bash
curl -X POST https://freedomspeech.kz/v1/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Қазақстан — менің Отаным","voice":"tomiris"}' \
  --output speech.wav
```

--------------------------------

### List All Available Voices

Source: https://freedomspeech.kz/docs

Use this command to fetch a list of all available voices from the API. The response includes voice IDs, names, and types (builtin or custom).

```bash
curl https://freedomspeech.kz/api/voices
```

--------------------------------

### Synthesize Text to Speech (Python)

Source: https://freedomspeech.kz/docs

This Python script demonstrates how to use the requests library to interact with the Text-to-Speech API. It sends a JSON payload with the text and voice, then saves the received audio content to a WAV file.

```python
import requests

resp = requests.post(
    "https://freedomspeech.kz/v1/audio/speech",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"input": "Қазақстан — менің Отаным", "voice": "tomiris"},
)
with open("speech.wav", "wb") as f:
    f.write(resp.content)
```

--------------------------------

### Clone Voice with Preset Voice and Slower Pace

Source: https://freedomspeech.kz/docs

This snippet demonstrates cloning a voice with a preset ID and adjusting the speaking pace. Use the 'time' parameter to control speed (lower values mean faster speech).

```bash
curl -X POST https://freedomspeech.kz/api/voice-clone \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "voice_id=tomiris" \
  -F "text=Бүгін ауа райы өте жақсы болды." \
  -F "time=1.5" \
  --output tomiris_slow.wav
```

--------------------------------

### Translate Single String with Python

Source: https://freedomspeech.kz/docs

Demonstrates how to use the Python requests library to translate a single string.

```python
import requests

resp = requests.post(
    "https://freedomspeech.kz/v2/translate",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"text": "Привет мир", "target_lang": "kk"},
)
print(resp.json()["translations"][0]["text"])
```

--------------------------------

### Clone Voice with Custom Audio

Source: https://freedomspeech.kz/docs

Use this snippet to clone a voice by providing your own reference audio file. Ensure the audio is in WAV, MP3, or WebM format.

```bash
curl -X POST https://freedomspeech.kz/api/voice-clone \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "audio=@reference.wav" \
  -F "text=Сәлеметсіз бе" \
  -F "language=kk" \
  --output cloned.wav
```

--------------------------------

### Send Synthesis Request (Client to Server)

Source: https://freedomspeech.kz/docs

Send a JSON message to initiate speech synthesis. The 'text' field is required; 'voice', 'emotion', and 'language' are optional.

```json
{
  "type": "synthesize",
  "text": "Қазақстан — менің Отаным",
  "voice": "tomiris",
  "emotion": "neutral",
  "language": "kk"
}
```

--------------------------------

### Synthesize Text with Preset Voice and Pace Control (Python)

Source: https://freedomspeech.kz/docs

This Python snippet synthesizes text using a preset voice and controls the speaking pace. The 'time' parameter adjusts the speed.

```python
import requests

# With preset voice + pace control
resp = requests.post(
    "https://freedomspeech.kz/api/voice-clone",
    headers={"X-API-Key": "YOUR_API_KEY"},
    data={
        "voice_id": "tomiris",
        "text": "Сәлеметсіз бе, қалыңыз қалай?",
        "language": "kk",
        "time": "1.2",   # slightly slower
    },
)
with open("out.wav", "wb") as f:
    f.write(resp.content)
```

--------------------------------

### Synthesize Text with Custom Audio (Python)

Source: https://freedomspeech.kz/docs

This Python snippet synthesizes text using your own uploaded audio as a reference. The audio file is sent as part of the request.

```python
# With your own audio
with open("reference.wav", "rb") as f:
    resp = requests.post(
        "https://freedomspeech.kz/api/voice-clone",
        headers={"X-API-Key": "YOUR_API_KEY"},
        files={"audio": f},
        data={"text": "Сәлеметсіз бе", "language": "kk"},
    )
with open("cloned.wav", "wb") as f:
    f.write(resp.content)
```

--------------------------------

### POST /v1/audio/speech

Source: https://freedomspeech.kz/docs

Synthesizes text into speech audio and returns a WAV file. This endpoint is compatible with OpenAI standards.

```APIDOC
## POST /v1/audio/speech

### Description
Synthesize text into speech audio. Returns a WAV file. OpenAI-compatible.

### Method
POST

### Endpoint
/v1/audio/speech

### Parameters
#### Request Body (JSON)
- **input** (string) - Required - Text to synthesize (max 1000 chars)
- **voice** (string) - Required - Voice ID: tomiris, taymas, or a custom voice ID
- **emotion** (string) - Optional - Emotion: neutral, happy, sad, surprised, angry, fearful
- **language** (string) - Optional - Language hint. Supported hints: `kk` Kazakh, `ru` Russian, `en`/`other` for English, Uyghur, Turkish, Uzbek, Kyrgyz, Tajik, Chinese/Mandarin, European languages and other non-Kazakh/non-Russian text. Aliases are accepted: `ug`/`uyghur`, `tr`, `uz`, `ky`/`kyrgyz`, `tg`, `zh`/`mandarin`.

### Response
`audio/wav` - 16-bit PCM mono WAV (24 kHz for Tomiris, 44.1 kHz for Taymas).

### Request Example
```bash
curl -X POST https://freedomspeech.kz/v1/audio/speech \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Қазақстан — менің Отаным","voice":"tomiris"}' \
  --output speech.wav
```
```python
import requests

resp = requests.post(
    "https://freedomspeech.kz/v1/audio/speech",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"input": "Қазақстан — менің Отаным", "voice": "tomiris"},
)
with open("speech.wav", "wb") as f:
    f.write(resp.content)
```

### Non-Verbal Tags
Insert non-verbal sounds into the text (Tomiris voice only): `<cough>`, `<groan>`, `<laugh>`, `<realization>`, `<sigh>`, `<smirk>`, `<startle>`, `<thinking>`, `<yawn>`
Example: "Сәлеметсіз бе <sigh> мен шаршадым"

### Errors
Code| Description  
---|---
400| Missing or invalid parameters (input, voice)
401| Invalid or missing API key
503| TTS backend unavailable
500| Internal server error
```

--------------------------------

### Supported Languages

Source: https://freedomspeech.kz/docs

List supported source and target languages. No authentication required.

```APIDOC
## GET `/v2/languages`

### Description
List supported source and target languages. No authentication required.

### Method
GET

### Endpoint
`/v2/languages`

### Response
#### Success Response (200)
- **source_languages** (array) - A list of supported source languages.
  - **language** (string) - The language code.
  - **name** (string) - The name of the language.
- **target_languages** (array) - A list of supported target languages.
  - **language** (string) - The language code.
  - **name** (string) - The name of the language.

### Request Example
```bash
curl https://freedomspeech.kz/v2/languages
```
```

--------------------------------

### Receive Audio Chunk (Server to Client)

Source: https://freedomspeech.kz/docs

Handle incoming audio data chunks. The 'audio' field contains base64 encoded PCM int16 data.

```json
// Audio chunk
{
  "type": "audio_chunk",
  "audio": "<base64 PCM int16>",
  "chunkIndex": 0,
  "sampleRate": 24000,
  "format": "int16"
}
```

--------------------------------

### ASR Streaming WebSocket Connection

Source: https://freedomspeech.kz/docs

Connect to the ASR streaming service using the provided WebSocket URL. Ensure you replace 'YOUR_API_KEY' with your actual API key. The 'prettify' parameter can be optionally set to 'true' for enhanced output formatting.

```APIDOC
## WebSocket: ASR Streaming
WS`wss://freedomspeech.kz/ws/asr?apiKey=YOUR_API_KEY`
Stream audio in real-time and receive incremental transcription results.
### Query Parameters
  * `apiKey`string* — Your API key
  * `prettify`string — Set to "true" or "1" to enable prettified output (named entities are corrected, better number/date formatting, filler words are removed)

### Connect
```javascript
const ws = new WebSocket(
  "wss://freedomspeech.kz/ws/asr?apiKey=YOUR_API_KEY&prettify=true"
);
```
```

--------------------------------

### POST /api/voice-design

Source: https://freedomspeech.kz/docs

Generates a voice from a text description and synthesizes text with it.

```APIDOC
## POST /api/voice-design

### Description
Generate a voice from a text description (e.g. "old man with a deep voice, speaking slowly") and synthesize text with it.

### Method
POST

### Endpoint
/api/voice-design

### Parameters
#### Request Body (JSON)
- **text** (string) - Required - Text to synthesize
- **instruct** (string) - Required - Voice description / instruction
- **language** (string) - Optional - Voice description / instruction. If set, skips auto-detection. Supported route hints: `kk` Kazakh, `ru` Russian, `en`/`other` for English, Uyghur, Turkish, Uzbek, Kyrgyz, Tajik, Chinese/Mandarin, European languages and other non-Kazakh/non-Russian text. Aliases are accepted: `ug`/`uyghur`, `tr`, `uz`, `ky`/`kyrgyz`, `tg`, `zh`/`mandarin`.

### Response
#### Success Response
- **voice_clone_wav_base64** (string) - Base64 encoded WAV audio of the synthesized voice.
- **reference_wav_base64** (string) - Base64 encoded WAV audio of the reference voice.

### Request Example
```bash
curl -X POST https://freedomspeech.kz/api/voice-design \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "text": "Сәлеметсіз бе, менің атым Қазақ", \
    "instruct": "young woman, soft voice, medium pace", \
    "language": "kz" \
  }'
```

### Response Example
```json
{
  "voice_clone_wav_base64": "<base64 WAV>",
  "reference_wav_base64": "<base64 reference>"
}
```
```

--------------------------------

### Connect to WebSocket TTS Stream

Source: https://freedomspeech.kz/docs

Establish a WebSocket connection to the TTS streaming endpoint. Replace YOUR_API_KEY with your actual API key.

```javascript
const ws = new WebSocket(
  "wss://freedomspeech.kz/ws/tts?apiKey=YOUR_API_KEY"
);
```

--------------------------------

### POST /api/voice-clone

Source: https://freedomspeech.kz/docs

Clones a voice from a reference audio sample or a preset voice ID and synthesizes the provided text in that voice. Supports Kazakh, Russian, and English.

```APIDOC
## POST /api/voice-clone

### Description
Clone a voice from a reference audio sample and synthesize text in that voice. Supports Kazakh, Russian, and English.

### Method
POST

### Endpoint
/api/voice-clone

### Parameters
#### Request Body
- **text** (string) - Required - Text to synthesize in the cloned voice
- **audio** (binary) - Required if voice_id is not set - Reference speaker audio file (WAV/MP3/WebM)
- **voice_id** (string) - Required if audio is not uploaded - Preset voice ID
- **language** (string) - Optional - Language hint. Supported route hints: `kk` Kazakh, `ru` Russian, `en`/`other` for English, Uyghur, Turkish, Uzbek, Kyrgyz, Tajik, Chinese/Mandarin, European languages and other non-Kazakh/non-Russian text. Aliases are accepted: `ug`/`uyghur`, `tr`, `uz`, `ky`/`kyrgyz`, `tg`, `zh`/`mandarin`.
- **time** (number) - Optional - Speaking pace multiplier (0.5–2.0). Lower = faster, higher = slower.
- **speed** (number) - Optional - Alternative speed control.
- **duration** (number) - Optional - Target audio duration in seconds.

### Response
#### Success Response (200)
- **audio/wav** - WAV file synthesized in the cloned voice.

### Examples
```bash
# With your own audio
curl -X POST https://freedomspeech.kz/api/voice-clone \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "audio=@reference.wav" \
  -F "text=Сәлеметсіз бе" \
  -F "language=kk" \
  --output cloned.wav

# With a preset voice
curl -X POST https://freedomspeech.kz/api/voice-clone \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "voice_id=tomiris" \
  -F "text=Сәлеметсіз бе, қалыңыз қалай?" \
  -F "language=kk" \
  --output tomiris.wav

# Tomiris with slower pace (time=1.5)
curl -X POST https://freedomspeech.kz/api/voice-clone \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "voice_id=tomiris" \
  -F "text=Бүгін ауа райы өте жақсы болды." \
  -F "time=1.5" \
  --output tomiris_slow.wav
```
```python
import requests

# With preset voice + pace control
resp = requests.post(
    "https://freedomspeech.kz/api/voice-clone",
    headers={"X-API-Key": "YOUR_API_KEY"},
    data={
        "voice_id": "tomiris",
        "text": "Сәлеметсіз бе, қалыңыз қалай?",
        "language": "kk",
        "time": "1.2",   # slightly slower
    },
)
with open("out.wav", "wb") as f:
    f.write(resp.content)

# With your own audio
with open("reference.wav", "rb") as f:
    resp = requests.post(
        "https://freedomspeech.kz/api/voice-clone",
        headers={"X-API-Key": "YOUR_API_KEY"},
        files={"audio": f},
        data={"text": "Сәлеметсіз бе", "language": "kk"},
    )
with open("cloned.wav", "wb") as f:
    f.write(resp.content)
```
```

--------------------------------

### Translate Batch with Explicit Source Language

Source: https://freedomspeech.kz/docs

Translates multiple strings to the target language with an explicitly defined source language.

```bash
curl -s -X POST https://freedomspeech.kz/v2/translate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":["Привет","Пока"],"target_lang":"kk","source_lang":"ru"}' | jq .
# → {"translations":[{"text":"Сәлем"},{"text":"Сау бол"}]}
```

--------------------------------

### Clone Voice with Preset Voice ID

Source: https://freedomspeech.kz/docs

Use this snippet to clone a voice using a predefined voice ID. This is useful for quick synthesis without uploading audio.

```bash
curl -X POST https://freedomspeech.kz/api/voice-clone \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "voice_id=tomiris" \
  -F "text=Сәлеметсіз бе, қалыңыз қалай?" \
  -F "language=kk" \
  --output tomiris.wav
```

--------------------------------

### Sending Audio Data

Source: https://freedomspeech.kz/docs

Send raw audio data as binary frames to the WebSocket server. This can be done by capturing audio from a MediaRecorder or microphone stream and sending the data chunks.

```APIDOC
### Send Audio (Client → Server)
Send raw audio as **binary frames** (PCM or WebM chunks).
```javascript
// From a MediaRecorder or microphone stream
mediaRecorder.ondataavailable = (e) => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(e.data); // binary audio chunk
  }
};
```
```

--------------------------------

### Detect Language with Python

Source: https://freedomspeech.kz/docs

Detect the language of multiple texts using the /v2/detect endpoint with Python's requests library. Requires an API key.

```python
import requests

resp = requests.post(
    "https://freedomspeech.kz/v2/detect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"text": ["Сәлем", "Hello", "Привет"]},
)
for d in resp.json()["detections"]:
    print(d["detected_source_language"], d["text"])
```

--------------------------------

### Send Audio Data

Source: https://freedomspeech.kz/docs

Sends binary audio chunks (PCM or WebM) to the WebSocket server for transcription. Ensure the WebSocket connection is open before sending.

```javascript
// From a MediaRecorder or microphone stream
mediaRecorder.ondataavailable = (e) => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(e.data); // binary audio chunk
  }
};
```

--------------------------------

### Receive Error Message (Server to Client)

Source: https://freedomspeech.kz/docs

Handles any errors that occur during the synthesis process. The 'message' field contains a description of the error.

```json
// Error
{
  "type": "error",
  "message": "error description"
}
```

--------------------------------

### Receive WebSocket Messages

Source: https://freedomspeech.kz/docs

Handles incoming messages from the WebSocket server, including ready signals, partial transcripts, and final transcription results.

```json
// Ready signal
{ "type": "ready" }
```

```json
// Partial transcript (incremental)
{
  "type": "partial",
  "text": "accumulated transcript so far",
  "is_final": false
}
```

```json
// Final transcript
{
  "type": "final",
  "text": "complete transcript",
  "language": "kk"
}
```

--------------------------------

### Translate Single String

Source: https://freedomspeech.kz/docs

Translates a single string to the target language. Auto-detects source language if not specified.

```bash
curl -s -X POST https://freedomspeech.kz/v2/translate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Привет мир","target_lang":"kk"}' | jq .
# → {"translations":[{"detected_source_language":"ru","text":"Сәлем дүние"}]}
```

--------------------------------

### Detect Language with cURL

Source: https://freedomspeech.kz/docs

Detect the language of multiple texts using the /v2/detect endpoint. Requires an API key and JSON content type.

```bash
curl -X POST https://freedomspeech.kz/v2/detect \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":["Сәлем","Hello","Привет"]}'
```

--------------------------------

### Detect Language

Source: https://freedomspeech.kz/docs

Detect the language of one or more texts. Requires an API key.

```APIDOC
## POST `/v2/detect`

### Description
Detect the language of one or more texts. Requires an API key.

### Method
POST

### Endpoint
`/v2/detect`

### Parameters
#### Request Body (JSON)
- **text** (string | string[]) - Required - Text(s) to detect. Max 50 items.

### Response
#### Success Response (200)
- **detections** (array) - An array of detection results.
  - **detected_source_language** (string) - The detected language code.
  - **text** (string) - The original text.

### Request Example
```bash
curl -X POST https://freedomspeech.kz/v2/detect \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":["Сәлем","Hello","Привет"]}'
```

```python
import requests

resp = requests.post(
    "https://freedomspeech.kz/v2/detect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"text": ["Сәлем", "Hello", "Привет"]},
)
for d in resp.json()["detections"]:
    print(d["detected_source_language"], d["text"])
```
```

--------------------------------

### List All Voices

Source: https://freedomspeech.kz/docs

Retrieves a list of all available voices, which can be either built-in or custom. The 'id' field from the response is crucial for subsequent TTS or Voice Clone operations.

```APIDOC
## GET /api/voices

### Description
Lists all available voices (builtin + custom). No authentication required. Use the `id` field as the `voice` parameter in TTS or `voice_id` in Voice Clone requests.

### Method
GET

### Endpoint
/api/voices

### Response
#### Success Response
JSON array of voice objects.

### Available Voices
| id | Name | Type |
|---|---|---|
| tomiris | Tomiris | builtin |
| taymas | Taymas | builtin |
| shrek | Shrek | custom |
| spongebob | SpongeBob | custom |
| kid | Kid 👶 | custom |
| confident | Confident Male Voice | custom |
| mom | Mom👩‍🍼 | custom |
| monster | Monster 👹 | custom |
| harry-potter | Harry Potter | custom |
| puss-in-boots | Puss in Boots 🐈 | custom |
| retro | Retro Voice 📼 | custom |
| ayaz-ata | Ayaz Ata 🎅 | custom |
| dio | Dio Brando | custom |
| asmr | ASMR Voice | custom |
| aisha | Aisha Kid 👶 | custom |
| aiaru | Aiaru Kid 👶 | custom |
| murager | Murager Teenager | custom |
| aruzhan-teen | Aruzhan Teenager | custom |
| abulkhair | Abulkhair Teenager | custom |
| nurasyl | Nurasyl Male Voice | custom |
| berik | Berik Male Voice | custom |
| alikhan | Alikhan Male Voice | custom |
| yerassyl | Yerassyl Male Voice | custom |
| arlan | Arlan Male Voice | custom |
| beksultan | Beksultan Male Voice | custom |
| nurdaulet | Nurdaulet Male Voice | custom |
| temir | Temir Male Voice | custom |
| aidana | Aidana Female Voice | custom |
| aruzhan | Aruzhan Female Voice | custom |
| journalist | Journalist Male Voice | custom |
| aigerim | Aigerim Female Voice | custom |
| moldir | Moldir Female Voice | custom |
| akbota | Akbota Female Voice | custom |
| cartoon | Cartoon Voice | custom |
| saule | Saule Female Voice | custom |
| call_center_woman | Колл центр Алтынай | custom |

### Request Example
```bash
curl https://freedomspeech.kz/api/voices
```

### Response Example
```json
[
  { "id": "tomiris", "name": "Tomiris", "type": "builtin" },
  { "id": "shrek", "name": "Shrek", "type": "custom" },
  ...
]
```
```

--------------------------------

### Translate Text

Source: https://freedomspeech.kz/docs

Translate one or more strings between Kazakh, Russian, and English. The source language can be auto-detected or explicitly provided. Requires an API key.

```APIDOC
## POST /v2/translate

### Description
Translate one or more strings between Kazakh, Russian, and English. Modeled after DeepL. Requires an API key.

### Method
POST

### Endpoint
/v2/translate

### Parameters
#### Request Body
- **text** (string | string[]) - Required - Text(s) to translate. Single string treated as array of one. Max 50 items.
- **target_lang** (string) - Required - Target language: `kk`, `ru`, `en`
- **source_lang** (string) - Optional - Source language. Omit for auto-detect.

### Response
#### Success Response (200)
- **translations** (array) - An array of translation objects.
  - **detected_source_language** (string) - Present only when `source_lang` was omitted. Indicates the detected source language.
  - **text** (string) - The translated text.

### Response Example
```json
{
  "translations": [
    {
      "detected_source_language": "ru",
      "text": "Сәлем дүние"
    }
  ]
}
```

### Examples
#### cURL (Single string)
```bash
curl -s -X POST https://freedomspeech.kz/v2/translate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Привет мир","target_lang":"kk"}' | jq .
```

#### cURL (Batch with explicit source lang)
```bash
curl -s -X POST https://freedomspeech.kz/v2/translate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":["Привет","Пока"],"target_lang":"kk","source_lang":"ru"}' | jq .
```

#### Python
```python
import requests

resp = requests.post(
    "https://freedomspeech.kz/v2/translate",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"text": "Привет мир", "target_lang": "kk"},
)
print(resp.json()["translations"][0]["text"])
```
```

--------------------------------

### Receive End of Audio Signal (Server to Client)

Source: https://freedomspeech.kz/docs

Indicates the end of the synthesized audio stream. 'totalChunks' provides the count of audio chunks received.

```json
// End of audio
{
  "type": "audio_end",
  "totalChunks": 42,
  "sampleRate": 24000
}
```

--------------------------------

### Receiving Transcription Results

Source: https://freedomspeech.kz/docs

The server sends back JSON messages indicating the status of the transcription. These include a 'ready' signal, 'partial' results for incremental updates, and 'final' results when the transcription is complete.

```APIDOC
### Receive (Server → Client)
```json
// Ready signal
{ "type": "ready" }

// Partial transcript (incremental)
{
  "type": "partial",
  "text": "accumulated transcript so far",
  "is_final": false
}

// Final transcript
{
  "type": "final",
  "text": "complete transcript",
  "language": "kk"
}
```
```

--------------------------------

### Health Check

Source: https://freedomspeech.kz/docs

Check if the ASR service is available. No authentication required.

```APIDOC
## GET `/api/asr/health`

### Description
Check if the ASR service is available. No authentication required.

### Method
GET

### Endpoint
`/api/asr/health`

### Response
#### Success Response (200)
- **status** (string) - The status of the ASR service (e.g., "available").
- **model_loaded** (boolean) - Indicates if the ASR model is loaded.

### Request Example
```bash
curl https://freedomspeech.kz/api/asr/health
```
```

--------------------------------

### Check ASR Service Health

Source: https://freedomspeech.kz/docs

Check the availability of the ASR service using the /api/asr/health endpoint. No authentication is required.

```bash
curl https://freedomspeech.kz/api/asr/health
```

--------------------------------

### Ending the Connection and Inactivity Timeout

Source: https://freedomspeech.kz/docs

The WebSocket connection can be explicitly closed by sending a stop signal. Additionally, the connection will automatically close after 15 seconds of inactivity.

```APIDOC
### Ending the Connection
Send `{"type":"stop"}` to finalize transcription and receive the `final` message. The connection also auto-closes after 15 seconds of inactivity.
```

--------------------------------

### Send Stop Signal

Source: https://freedomspeech.kz/docs

Sends a JSON object with type 'stop' to signal the end of audio streaming and finalize transcription.

```json
{ "type": "stop" }
```

--------------------------------

### TTS Streaming WebSocket

Source: https://freedomspeech.kz/docs

Connect to the WebSocket endpoint to stream synthesized speech. Send JSON messages to initiate synthesis and receive audio chunks or status updates.

```APIDOC
## WebSocket: TTS Streaming

WS `wss://freedomspeech.kz/ws/tts?apiKey=YOUR_API_KEY`

Stream synthesized speech in real-time. Send a JSON message and receive PCM audio chunks as they are generated.

### Connect
```javascript
const ws = new WebSocket(
  "wss://freedomspeech.kz/ws/tts?apiKey=YOUR_API_KEY"
);
```

### Send (Client → Server)
```json
{
  "type": "synthesize",
  "text": "Қазақстан — менің Отаным",
  "voice": "tomiris",
  "emotion": "neutral",
  "language": "kk"
}
```

`voice`, `emotion` and `language` are all optional — only `text` is required. `voice` defaults to `tomiris`; `emotion` defaults to neutral.
`emotion` accepts the same values as the HTTP TTS endpoint (neutral, happy, sad, surprised, angry, fearful). When `language` is set, it is used as a routing hint and auto-detection is skipped; supported values match the HTTP TTS `language` field.

### Receive (Server → Client)
```json
// Audio chunk
{
  "type": "audio_chunk",
  "audio": "<base64 PCM int16>",
  "chunkIndex": 0,
  "sampleRate": 24000,
  "format": "int16"
}

// End of audio
{
  "type": "audio_end",
  "totalChunks": 42,
  "sampleRate": 24000
}

// Error
{
  "type": "error",
  "message": "error description"
}
```

### Complete Example
```javascript
const ws = new WebSocket(
  "wss://freedomspeech.kz/ws/tts?apiKey=YOUR_API_KEY"
);

const chunks = [];

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "synthesize",
    text: "Сәлеметсіз бе",
    voice: "tomiris",
    emotion: "neutral",
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === "audio_chunk") {
    chunks.push(msg.audio); // base64 PCM int16
  }
  if (msg.type === "audio_end") {
    console.log("Done:", msg.totalChunks, "chunks");
    ws.close();
  }
};
```

### Ending the Connection
Close the WebSocket after receiving `audio_end`, or call `ws.close()` at any time to cancel.
```

--------------------------------

### Stopping the Streaming Session

Source: https://freedomspeech.kz/docs

To finalize the transcription process and receive the final results, send a JSON object with the type 'stop' to the server.

```APIDOC
### Stop Streaming
Send a JSON stop signal when done recording:
```json
{ "type": "stop" }
```
```
Tokens:
Raw