TTS API

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

Get API key Contact team Base URL https://back.aisha.group

API v1 TTS Sync / Async

Overview #

1 Send transcript to POST /api/v1/tts/post/ to generate audio.
2 Pass webhook_notification_url to run the request asynchronously and receive 202 Accepted.
3 Check the result through GET /api/v1/tts/status/{id}/ or history.

Prefer a CLI? The aisha-ai npm package wraps these endpoints: npx aisha-ai tts / npx aisha-ai stt. aisha-ai on npm

API Key #

API Key
X-Api-Key: <api_key>

Recommended for server-to-server integrations.

Generate audio #

POST https://back.aisha.group/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

string

Text to synthesize.

Example: Assalomu alaykum

language

string

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

Example: uz

model

string

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

Example: Gulnoza

mood

string

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

Example: Neutral

speed

float

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

Example: 1.0

voice_id

integer

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

Example: 12

webhook_notification_url

string

Runs TTS asynchronously when provided.

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

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'

CLI (aisha-ai)

export AISHA_API_KEY=your_api_key
npx aisha-ai tts "Salom dunyo" --model Gulnoza --out salom.wav

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.

Check status #

GET https://back.aisha.group/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.

History list #

GET https://back.aisha.group/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.