Developer workflow

Recommended patterns for a reliable VoiceLab integration.

Minimal path (sync)

Client / Backend
  -> X-Api-Key
  -> POST /api/v1/tts/post/  or  POST /api/v1/stt/post/
  -> result (audio_path / transcript)

Use when: short text, short audio, and you need an immediate response.

Async path (webhook or polling)

TTS

1. POST /api/v1/tts/post/ with webhook_notification_url → 202 + task_id / id
2. Wait for the webhook or poll GET /api/v1/tts/status/{id}/
3. History: GET /api/v1/tts/get/

STT (long audio)

1. POST /api/v2/stt/post/ → task_id + record id
2. Poll GET /api/v2/stt/get/{id}/ until SUCCESS or FAILED
3. List: GET /api/v2/stt/get/

Backend
  -> create job (v2 STT or async TTS)
  -> store id / task_id
  -> poll detail/status  or  webhook handler
  -> persist transcript / audio URL

Realtime path

For long sessions or low latency:

Service	Transport	Endpoint
TTS	WebSocket	wss://api.voicelab.uz/api/v1/tts/realtime?token=...
STT	WebSocket	wss://api.voicelab.uz/api/v1/stt/realtime?format=webm&token=...
TTS / STT	gRPC	api.voicelab.uz:443

Practices:

• Reuse one TTS WebSocket for multiple text turns; do not reconnect per turn.
• Stream STT audio chunks; finish with {"event":"end"}.
• Balance is usually checked when the stream starts — verify credit before opening a session.

Recommended architecture

Browser / Mobile
      |
      v
Your Backend (holds AISHA_API_KEY)
      |
      +--> REST TTS/STT
      +--> WebSocket / gRPC realtime
      +--> Webhook receiver (async)
      |
      v
Storage / DB / downstream systems

• Keep the API key only on your backend.
• Separate preview and production (different keys and webhook URLs).
• Persist async job ids in your database for retries and audit.

Integration checklist

1. [ ] AISHA_API_KEY is read from the environment
2. [ ] Sync TTS/STT smoke test passes
3. [ ] Async status/detail flow is closed
4. [ ] 402 / 403 are handled in UI or logs
5. [ ] If using realtime — multiple turns on one session work
6. [ ] Agents can load llms-api.txt

Endpoint details: TTS · STT