Aisha AI
by voicelab

STT API

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

Get API key Contact team Base URL https://back.aisha.group
API v1 API v2 Realtime STT

Overview #

  1. 1 POST /api/v1/stt/post/ for short audio (sync).
  2. 2 POST /api/v2/stt/post/ for long audio (async, returns task_id).
  3. 3 Use WebSocket wss://back.aisha.group/api/v1/stt/realtime for realtime audio.
  4. 4 Use gRPC endpoint back.aisha.group:443 for server streaming integrations.

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.

  • Streaming token

    ?token=<token>

    Realtime WebSocket sends the token as a query parameter.

Short-audio transcription #

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

Upload a short audio file and get the result immediately (sync).

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

  • Supported formats: mp3, wav, ogg, m4a (validated on the server).
  • With diarization enabled, audio must be at least 15 seconds.

Request fields #

audio required

file

Audio file.

Example: voice-note.mp3

language

string

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

Example: uz

has_diarization

boolean string

Speaker diarization flag.

Example: false

has_offset

boolean string

Return segment offsets.

Example: false

is_summary

boolean string

Generate summary.

Example: false

title

string

Optional title.

Example: meeting-voice-note

Examples #

v1 POST

curl --request POST \
  --url https://back.aisha.group/api/v1/stt/post/ \
  --header 'X-Api-Key: your_api_key' \
  --header 'Accept-Language: uz' \
  --form 'audio=@/path/to/voice-note.mp3' \
  --form 'language=uz' \
  --form 'has_diarization=false'

CLI (aisha-ai)

export AISHA_API_KEY=your_api_key
npx aisha-ai stt ./audio.wav

Responses #

200 OK

Success

{
  "id": 531,
  "gender": "unknown",
  "title": null,
  "created_at": "2026-05-04T10:12:43.212Z",
  "duration": 18.7,
  "transcript": "Assalomu alaykum, bu qisqa audio transkripsiyasi."
}

Status codes #

200

Result returned.

400

Missing audio or invalid format.

402

Insufficient balance.

403

Duration limit or access issue.

503

STT service temporarily unavailable.

v1 history list #

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

Returns the user's transcripts with pagination.

Authentication: Requires X-Api-Key.

  • The alias /api/v1/stt/audios/ is also available.

Examples #

v1 GET history

curl --request GET \
  --url 'https://back.aisha.group/api/v1/stt/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": 531,
      "title": null,
      "gender": "unknown",
      "status": "SUCCESS",
      "language": "uz",
      "created_at": "2026-05-04T10:12:43.212Z",
      "duration": 18.7,
      "transcript": "Assalomu alaykum, bu qisqa audio transkripsiyasi.",
      "summary": "",
      "diarization": [],
      "audio_url": "/media/audio/f35f6c3a.wav",
      "speakers": []
    }
  ]
}

Status codes #

200

History returned.

403

API key is invalid or missing.

Long-audio transcription (async) #

POST https://back.aisha.group/api/v2/stt/post/

Upload a long audio file. The response includes task_id and PENDING status.

Authentication: Requires X-Api-Key.

  • Max file size: 500MB.

Request fields #

audio required

file

Audio file.

Example: meeting-record.mp3

language

string

Default: uz.

Example: uz

has_diarization

boolean string

Speaker diarization flag.

Example: true

has_offset

boolean string

Offsets flag.

Example: false

is_summary

boolean string

Summary flag.

Example: true

is_meeting

boolean string

Meeting mode flag.

Example: false

title

string

Optional title.

Example: sales-call

Examples #

v2 POST

curl --request POST \
  --url https://back.aisha.group/api/v2/stt/post/ \
  --header 'X-Api-Key: your_api_key' \
  --form 'audio=@/path/to/meeting-record.mp3' \
  --form 'language=uz' \
  --form 'has_diarization=true' \
  --form 'is_summary=true'

Responses #

200 OK

Queued

{
  "id": 901,
  "has_diarization": true,
  "is_meeting": false,
  "task_id": "66e92db4-95cf-4bb9-acbc-49462039d19f",
  "status": "PENDING",
  "title": "sales-call-13-aprel",
  "audio_url": "/media/audio/273bc5f8-1f91-4573-b3df-3c38c44294d0.mp3"
}

Status codes #

200

Task created.

400

Missing audio or file too large.

401

API key is missing or invalid.

403

Balance or access error.

500

Internal error.

Realtime WebSocket transcription #

WS wss://back.aisha.group/api/v1/stt/realtime?format=webm&token=YOUR_API_KEY

Send microphone or audio stream chunks through WebSocket. The server returns session_started, transcription, and error JSON messages.

Authentication: Send token as a query parameter. Balance is checked before the connection starts.

  • format=webm: for audio/webm;codecs=opus chunks sent by browser MediaRecorder.
  • format=pcm: for raw PCM streams. Exact format: 16 kHz, mono, signed 16-bit little-endian (s16le).
  • Do not send raw Opus frames; browser Opus must be sent inside the WebM container.
  • When the stream is finished, send text message {"event":"end"}.

Request fields #

token required

string

API key.

Example: YOUR_API_KEY

format

string

Supported: webm, pcm. Default: webm.

Example: webm

binary chunks required

bytes

Audio bytes sent through WebSocket.

Example: audio/webm chunk

Examples #

Browser WebM/Opus stream

const token = 'your_api_key'
const ws = new WebSocket(
  `wss://back.aisha.group/api/v1/stt/realtime?format=webm&token=${encodeURIComponent(token)}`
)

ws.onmessage = event => {
  const message = JSON.parse(event.data)
  if (message.type === 'transcription') {
    console.log(message.text, message.partial, message.consumed_audio_seconds)
  }
}

const stream = await navigator.mediaDevices.getUserMedia({ audio: true })
const recorder = new MediaRecorder(stream, { mimeType: 'audio/webm;codecs=opus' })

recorder.ondataavailable = async event => {
  if (event.data.size > 0 && ws.readyState === WebSocket.OPEN) {
    ws.send(await event.data.arrayBuffer())
  }
}

// Bitta connection ichida audio chunk'larni uzluksiz yuborish mumkin.
// Har session oxirida faqat bir marta end event yuboring.
recorder.start(250)

// Stop when the user finishes speaking.
// recorder.stop()
// ws.send(JSON.stringify({ event: 'end' }))

Raw PCM stream

import asyncio
import websockets

TOKEN = "your_api_key"
URL = f"wss://back.aisha.group/api/v1/stt/realtime?format=pcm&token={TOKEN}"

async def stream_pcm():
    async with websockets.connect(URL, max_size=None) as ws:
        async def reader():
            async for message in ws:
                print(message)

        reader_task = asyncio.create_task(reader())
        with open("audio.s16le", "rb") as audio:
            while chunk := audio.read(3200):
                await ws.send(chunk)
                await asyncio.sleep(0.1)

        await ws.send('{"event":"end"}')
        await reader_task

asyncio.run(stream_pcm())

Responses #

message

Session started

{
  "type": "session_started",
  "session_id": "7ab6d67a-9a29-4ad9-90b7-d2f5b2fc08fb",
  "user_id": "42",
  "allowed_audio_seconds": 1280,
  "format": "webm"
}
message

Transcript

{
  "type": "transcription",
  "session_id": "7ab6d67a-9a29-4ad9-90b7-d2f5b2fc08fb",
  "text": "Assalomu alaykum, buyurtmam holatini tekshirib bering.",
  "partial": false,
  "segment_event": "end",
  "consumed_audio_seconds": 4.32
}
message

Error

{
  "type": "error",
  "code": "insufficient_balance",
  "message": "Balance limit reached",
  "session_id": "7ab6d67a-9a29-4ad9-90b7-d2f5b2fc08fb"
}

Status codes #

1000

Stream closed normally.

1008

Token, balance, or format error.

1011

Server could not process the stream.

gRPC streaming transcription #

gRPC back.aisha.group:443/aisha.stt.RealtimeSTT/Transcribe

Backend services send an audio bytes stream over gRPC and receive transcript, segments, and timings in the final response.

Authentication: Use token/API access issued by the gateway.

  • Send audio bytes in a regular audio file format: wav, mp3, m4a, ogg, or webm.
  • Send first=true and language in the first chunk. Later chunks only need audio_chunk.
  • User-facing response fields: text, language, duration, audio_bytes, segments, timings.

Request fields #

audio_chunk required

bytes

Audio stream chunk.

Example: 32000 bytes

language

string

Supported: uz, ru, en. Sent in the first chunk.

Example: uz

first

boolean

Marks the first chunk.

Example: true

Examples #

Python gRPC stream

import grpc
import stt_pb2
import stt_pb2_grpc

channel = grpc.secure_channel("back.aisha.group:443", grpc.ssl_channel_credentials())
client = stt_pb2_grpc.RealtimeSTTStub(channel)

def chunks(path):
    with open(path, "rb") as audio:
        first = True
        while data := audio.read(32000):
            yield stt_pb2.TranscribeChunk(
                audio_chunk=data,
                language="uz" if first else "",
                first=first,
            )
            first = False

def transcribe(path):
    response = client.Transcribe(chunks(path))
    print(response.text)
    for segment in response.segments:
        print(segment.start, segment.end, segment.text)

# Channel reuse mumkin, lekin har audio/utterance uchun alohida Transcribe RPC ochiladi.
transcribe("audio.wav")
transcribe("another.wav")

Responses #

OK

Transcript

{
  "text": "Assalomu alaykum, buyurtmam holatini tekshirib bering.",
  "language": "uz",
  "duration": 4.32,
  "audio_bytes": 138240,
  "segments": [
    {
      "start": 0.0,
      "end": 4.32,
      "text": "Assalomu alaykum, buyurtmam holatini tekshirib bering."
    }
  ],
  "timings": {
    "transcribe_sec": 0.74,
    "total_sec": 0.82
  }
}

Status codes #

OK

Transcript returned.

INVALID_ARGUMENT

Audio stream is empty or invalid.

UNAUTHENTICATED

Token/API access was not accepted.

v2 history list #

GET https://back.aisha.group/api/v2/stt/get/

Returns the transcript history list (paginated).

Authentication: Requires X-Api-Key.

  • Detail: GET /api/v2/stt/get/{id}/.

Examples #

v2 history

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

Responses #

200 OK

History

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 901,
      "title": "sales-call-13-aprel",
      "status": "PENDING",
      "created_at": "2026-05-04T10:39:58.501Z",
      "duration": null,
      "audio_url": "/media/audio/273bc5f8-1f91-4573-b3df-3c38c44294d0.mp3"
    }
  ]
}

Status codes #

200

History/detail returned.

401

API key is missing or invalid.

404

Transcript not found.

v2 transcript detail #

GET https://back.aisha.group/api/v2/stt/get/{id}/

Returns status and result for a single transcript.

Authentication: Requires X-Api-Key.

  • When status=SUCCESS, the transcript result is included.

Examples #

v2 detail

curl --request GET \
  --url https://back.aisha.group/api/v2/stt/get/901/ \
  --header 'X-Api-Key: your_api_key'

Responses #

200 OK

Completed

{
  "id": 901,
  "title": "sales-call-13-aprel",
  "status": "SUCCESS",
  "created_at": "2026-05-04T10:39:58.501Z",
  "duration": 612.4,
  "transcript": "Uzoq meeting transcript matni...",
  "summary": "Qisqa summary...",
  "diarization": [],
  "audio_url": "/media/audio/273bc5f8-1f91-4573-b3df-3c38c44294d0.mp3"
}

Status codes #

200

Detail returned.

401

API key is missing or invalid.

404

Transcript not found.

Task status polling #

GET https://back.aisha.group/task-status/{task_id}/?instance_id={id}

Checks async task state. instance_id is required for ownership verification.

Authentication: Requires X-Api-Key or user access token.

  • The task must be linked to instance_id to check its status.

Examples #

task-status

curl --request GET \
  --url 'https://back.aisha.group/task-status/task-123/?instance_id=944' \
  --header 'X-Api-Key: your_api_key'

Responses #

200 OK

Pending

{
  "task_id": "task-123",
  "status": "PENDING",
  "transcript_status": "PENDING",
  "message": "Task is still processing"
}
200 OK

Success

{
  "task_id": "task-123",
  "status": "SUCCESS",
  "transcript_status": "SUCCESS",
  "result": {
    "transcript": "Hello world"
  }
}

Status codes #

200

Task status returned.

400

instance_id missing.

403

Access denied.

500

Task failed/unknown state.