Developer docs

TTS API

Text-to-Speech endpoints. For server-to-server integrations, send X-Api-Key with every request.

API v1 TTS Sync / Async https://back.aisha.group

API keys Contact team

Quick start

TTS API

Send transcript to POST /api/v1/tts/post/ to generate audio.

Pass webhook_notification_url to run the request asynchronously and receive 202 Accepted.

Check the result through GET /api/v1/tts/status/{id}/ or history.

Authentication

API Key

X-Api-Key: <api_key>

Recommended for server-to-server integrations.

POST

Generate audio

Endpoint /api/v1/tts/post/

Converts text to an audio file. The built-in Gulnoza model is used for language=uz. For en and ru, model, mood, and speed are not sent.

Authentication

Send X-Api-Key. Public requests may require reCAPTCHA.

Limit: 1000 characters with API key, 500 characters for public requests.

speed must be 0 or between 0.5-2.0.

mood is only for the built-in Gulnoza flow. When voice_id is used, mood is not sent.

Request fields

transcript required

Example: Assalomu alaykum

string

Text to synthesize.

language optional

Example: uz

string

Supported values: uz, en, ru. Default: uz.

model optional

Example: Gulnoza

string

Only for the built-in uz flow. There is currently one model: Gulnoza.

mood optional

Example: Neutral

string

Only for built-in Gulnoza. There are 4 moods: Neutral, Cheerful, Happy, Sad. Not sent for voice_id, en, or ru flows.

speed optional

Example: 1.0

float

Only for the uz flow. 0 uses the default speed. Custom range: 0.5-2.0.

voice_id optional

Example: 12

integer

READY custom voice ID owned by the user. If voice_id is used, mood is not sent.

webhook_notification_url optional

Example: https://example.com/webhooks/tts

string

Runs TTS asynchronously when provided.

Examples

Sync request

curl --request POST \
  --url https://back.aisha.group/api/v1/tts/post/ \
  --header 'X-Api-Key: your_api_key' \
  --header 'Accept-Language: uz' \
  --form 'transcript=Assalomu alaykum, bu AIsha TTS sinovi.' \
  --form 'language=uz' \
  --form 'model=Gulnoza' \
  --form 'mood=Neutral' \
  --form 'speed=1.0'

Async request

curl --request POST \
  --url https://back.aisha.group/api/v1/tts/post/ \
  --header 'X-Api-Key: your_api_key' \
  --form 'transcript=Webhook orqali qaytadigan sinov matni.' \
  --form 'language=uz' \
  --form 'webhook_notification_url=https://example.com/webhooks/tts'

Responses

201 Created

Sync success

{
  "audio_path": "/media/tts_audios/request-id.wav"
}

202 Accepted

Async queued

{
  "id": 184,
  "task_id": "7d5f8779-9cb0-4230-9318-2f8c3c3f0e31",
  "status": "PENDING"
}

Status codes

201

Audio is ready and `audio_path` is returned.

202

Async task was queued.

400

Invalid transcript, language, model, or speed.

401

Custom voice requires authentication.

402

Insufficient balance.

503

TTS service is temporarily unavailable.

GET

Check status

Endpoint /api/v1/tts/status/{id}/

Returns the state of an async TTS task.

Authentication

Send X-Api-Key.

Possible statuses: PENDING, SUCCESS, FAILED.

Examples

Status request

curl --request GET \
  --url https://back.aisha.group/api/v1/tts/status/184/ \
  --header 'X-Api-Key: your_api_key'

Responses

200 OK

Pending

{
  "id": 184,
  "status": "PENDING",
  "task_id": "7d5f8779-9cb0-4230-9318-2f8c3c3f0e31"
}

200 OK

Completed

{
  "id": 184,
  "status": "SUCCESS",
  "task_id": "7d5f8779-9cb0-4230-9318-2f8c3c3f0e31",
  "audio_path": "/media/tts_audios/request-id.wav",
  "characters": 42
}

Status codes

200

Status returned.

403

No access to another user's record.

404

TTS record not found.

GET

History list

Endpoint /api/v1/tts/get/?page=1&limit=10

Returns the current user's TTS audio history with pagination.

Authentication

Requires X-Api-Key.

Response format: count, next, previous, results.

Examples

History request

curl --request GET \
  --url 'https://back.aisha.group/api/v1/tts/get/?page=1&limit=10' \
  --header 'X-Api-Key: your_api_key'

Responses

200 OK

Paginated success

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 184,
      "transcript": "Assalomu alaykum, bu AIsha TTS sinovi.",
      "audio_url": "/media/tts_audios/request-id.wav",
      "model": "Gulnoza",
      "mood": "Neutral",
      "created_at": "2026-05-04T10:15:30Z"
    }
  ]
}

Status codes

200

History returned.

403

API key is invalid or missing.