Aisha AI
by voicelab

TTS API

Text-to-Speech endpointlari. Server integratsiya uchun har bir so'rovda X-Api-Key header yuboring.

API key olish Jamoa bilan bog‘lanish Base URL https://back.aisha.group
API v1 TTS Sync / Async Realtime

Overview #

  1. 1 Audio yaratish uchun POST /api/v1/tts/post/ endpointiga transcript yuboring.
  2. 2 webhook_notification_url yuborilsa, so'rov async ishlaydi va 202 Accepted qaytadi.
  3. 3 Natijani GET /api/v1/tts/status/{id}/ yoki history orqali tekshiring.
  4. 4 Realtime TTS uchun wss://back.aisha.group/api/v1/tts/realtime WebSocket yoki back.aisha.group:443 gRPC ishlating.
  5. 5 Bitta connection ichida bir nechta text turn yuboring; har turn uchun qayta ulanishingiz shart emas.
  6. 6 TTS character tarifi stream boshlanishida balance tekshirilgandan keyin qo‘llanadi.

CLI qulayroqmi? aisha-ai npm paketi shu endpointlarni o‘rab beradi: npx aisha-ai tts / npx aisha-ai stt. npm’dagi aisha-ai

API Key #

  • API Key

    X-Api-Key: <api_key>

    Server-to-server integratsiya uchun tavsiya qilinadi.

  • Streaming auth

    WebSocket: ?token=<api_key> | gRPC: x-api-key: <api_key>

    WebSocket browser uchun query token, gRPC esa metadata orqali API key qabul qiladi.

Audio yaratish #

POST https://back.aisha.group/api/v1/tts/post/

Matnni audio faylga aylantiradi. language=uz uchun built-in Gulnoza modeli ishlaydi. en va ru oqimlarida model, mood, speed yuborilmaydi.

Autentifikatsiya: X-Api-Key yuboring. Public so‘rovlar reCAPTCHA talab qilishi mumkin.

  • Limit: API key bilan 1000 belgi, public so‘rovda 500 belgi.
  • speed qiymati 0 yoki 0.5-2.0 oralig‘ida bo‘ladi.
  • mood faqat built-in Gulnoza uchun. voice_id bilan yuborilganda mood ishlatilmaydi.

So‘rov maydonlari #

transcript majburiy

string

Audio ga aylantiriladigan matn.

Misol: Assalomu alaykum

language

string

Qo'llab-quvvatlanadi: uz, en, ru. Default: uz.

Misol: uz

model

string

Faqat uz built-in oqimi uchun. Hozir bitta model bor: Gulnoza.

Misol: Gulnoza

mood

string

Faqat built-in Gulnoza uchun 4 ta mood bor: Neutral, Cheerful, Happy, Sad. voice_id, en, ru oqimlarida yuborilmaydi.

Misol: Neutral

speed

float

Faqat uz oqimi uchun. 0 default tezlik. Custom qiymat: 0.5-2.0.

Misol: 1.0

voice_id

integer

Userga tegishli READY custom voice ID. voice_id ishlatilsa mood yuborilmaydi.

Misol: 12

webhook_notification_url

string

Berilsa TTS async queue ga tushadi.

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

Misollar #

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

Javoblar #

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 kodlari #

201

Audio tayyor va `audio_path` qaytdi.

202

Async task queue ga qo'yildi.

400

Transcript, language, model yoki speed xato.

401

Custom voice uchun auth kerak.

402

Balans yetarli emas.

503

TTS servisi vaqtincha unavailable.

Status tekshirish #

GET https://back.aisha.group/api/v1/tts/status/{id}/

Async TTS task holatini qaytaradi.

Autentifikatsiya: X-Api-Key yuboring.

  • Status qiymatlari: PENDING, SUCCESS, FAILED.

Misollar #

Status request

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

Javoblar #

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 kodlari #

200

Status qaytdi.

403

Boshqa user recordiga access yo'q.

404

TTS record topilmadi.

History ro'yxati #

GET https://back.aisha.group/api/v1/tts/get/?page=1&limit=10

Userga tegishli TTS audio tarixini paginatsiya bilan qaytaradi.

Autentifikatsiya: X-Api-Key talab qilinadi.

  • Response count, next, previous, results formatida qaytadi.

Misollar #

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'

Javoblar #

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 kodlari #

200

History qaytdi.

403

API key noto'g'ri yoki yuborilmagan.

Realtime WebSocket TTS #

WS wss://back.aisha.group/api/v1/tts/realtime?token=YOUR_API_KEY

Send multiple text turns over one persistent WebSocket connection. Each turn returns metadata followed by binary WAV bytes.

Autentifikatsiya: Send the API key as the token query parameter. Balance and character pricing are checked when the session starts.

  • Requests are JSON text messages with request_id, speaker_id, language, text, and speed.
  • Built-in speakers: happy, cheerful, neutral, sad.
  • Defaults: language=uz and speed=1.0.
  • The response is a mono, 16-bit, 16 kHz WAV. The JSON metadata frame is followed by one binary audio frame.
  • Send {"type":"end"} once to close the session. Keep the connection open for subsequent turns.

So‘rov maydonlari #

token majburiy

string

API key in the query string.

Misol: YOUR_API_KEY

speaker_id

string

One of happy, cheerful, neutral, sad.

Misol: happy

language

string

Default: uz.

Misol: uz

text majburiy

string

Text to synthesize.

Misol: Assalomu alaykum

speed

float

Default: 1.0.

Misol: 1.0

Misollar #

Browser WebSocket

const token = 'your_api_key'
const ws = new WebSocket('wss://back.aisha.group/api/v1/tts/realtime?token=' + encodeURIComponent(token))

ws.onmessage = event => {
  if (typeof event.data === 'string') {
    const message = JSON.parse(event.data)
    if (message.type === 'audio') console.log(message.request_id, message.sample_rate, message.duration_sec)
    if (message.type === 'error') console.error(message.code, message.message)
    return
  }
  // Binary frame: complete 16 kHz mono WAV bytes.
  playWav(event.data)
}

ws.onopen = () => ws.send(JSON.stringify({
  request_id: 'turn-1',
  speaker_id: 'happy',
  language: 'uz',
  text: 'Assalomu alaykum, bu Aisha TTS sinovi.'
}))

// Reuse this connection for later turns, then close the session once.
function finishSession() {
  ws.send(JSON.stringify({ type: 'end' }))
}

Request JSON

{
  "request_id": "turn-1",
  "speaker_id": "happy",
  "language": "uz",
  "text": "Assalomu alaykum, bu Aisha TTS sinovi.",
  "speed": 1.0
}

Javoblar #

message

Session started

{
  "type": "session_started",
  "session_id": "7ab6d67a-9a29-4ad9-90b7-d2f5b2fc08fb",
  "billing": "characters"
}
message + binary

Audio metadata + WAV bytes

{
  "type": "audio",
  "request_id": "turn-1",
  "speaker_id": "happy",
  "sample_rate": 16000,
  "duration_sec": 1.84,
  "characters": 42
}

// The next WebSocket frame is binary audio_wav bytes.
message

Balance error

{
  "type": "error",
  "code": "insufficient_balance",
  "message": "TTS character balance limit reached"
}

Status kodlari #

1000

Session closed normally.

1008

API key or balance was rejected.

synthesis_failed

Text or speaker synthesis failed.

Persistent gRPC TTS stream #

gRPC back.aisha.group:443/aisha.tts.RealtimeTTS/Synthesize

Send sequential text turns in one client-streaming request and receive one server-streaming audio response per turn.

Autentifikatsiya: Send x-api-key: <api_key> as gRPC metadata.

  • TLS endpoint: back.aisha.group:443.
  • Each SynthesizeRequest is one text turn. Send end=true to finish the stream.
  • Reuse one gRPC channel for the complete voice-agent session; do not create a channel for every turn.
  • Each response contains 16 kHz WAV audio_wav, sample_rate, duration_sec, characters, and request_id.
  • TTS billing is based on characters after balance verification at stream start.

So‘rov maydonlari #

text majburiy

string

Text to synthesize.

Misol: Assalomu alaykum

speaker_id

string

Built-in speaker ID.

Misol: neutral

language

string

Default: uz.

Misol: uz

speed

float

Default: 1.0.

Misol: 1.0

end

boolean

Finishes the persistent stream.

Misol: true

Misollar #

Python persistent stream

import grpc
import tts_pb2
import tts_pb2_grpc

channel = grpc.secure_channel('back.aisha.group:443', grpc.ssl_channel_credentials())
client = tts_pb2_grpc.RealtimeTTSStub(channel)

def requests():
    yield tts_pb2.SynthesizeRequest(
        request_id='turn-1', speaker_id='happy', language='uz',
        text='Assalomu alaykum, bu Aisha TTS sinovi.'
    )
    yield tts_pb2.SynthesizeRequest(
        request_id='turn-2', speaker_id='neutral', language='uz',
        text='Keyingi turn shu channel ichida davom etadi.'
    )
    yield tts_pb2.SynthesizeRequest(end=True)

for response in client.Synthesize(requests(), metadata=(('x-api-key', 'your_api_key'),)):
    if response.error_code:
        raise RuntimeError(response.error_message)
    save_wav(response.audio_wav)

# Reuse channel and create another Synthesize stream for the next session.
channel.close()

Javoblar #

OK

Synthesis response

{
  "request_id": "turn-1",
  "speaker_id": "happy",
  "sample_rate": 16000,
  "duration_sec": 1.84,
  "characters": 42,
  "audio_wav": "bytes"
}
stream response

Error

{
  "type": "error",
  "code": "insufficient_balance",
  "message": "TTS character balance limit reached"
}

Status kodlari #

OK

Audio response returned.

UNAUTHENTICATED

API key metadata is missing or invalid.

RESOURCE_EXHAUSTED

TTS character balance is insufficient.