Theme

Developer workflow ​

Use discovery endpoints and idempotency from the start so integrations remain safe as the catalog grows.

LLM ​

text
GET /v1/models
  -> POST /v1/chat/completions with JSON + Idempotency-Key
  -> JSON completion or SSE ending in [DONE]
  -> GET /v1/llm/requests/{id} for status and usage

Use a key with llm Access and choose a returned model ID. Save X-LLM-Request-ID. On a transport failure, reuse the same body and idempotency key; a duplicate returns 409 and the original request ID without replaying the response. Read request status before trying again. Stop and contact support on llm_usage_pending. See LLM for streaming and function calls.

Text-to-Speech ​

text
GET /v1/tts/languages
  -> GET /v1/voices?language={code}
  -> POST /v1/tts with JSON + Idempotency-Key
  -> WAV response

Always choose a language and opaque voice_... ID from the live catalogs. Save the binary 200 OK response as a WAV file. On a timeout, retry the identical body with the same idempotency key.

For history, use cursor pagination:

  • GET /v1/tts/generations?limit=30&cursor={opaque}
  • GET /v1/tts/generations/{generation_id}
  • DELETE /v1/tts/generations/{generation_id}

Speech-to-Text ​

text
POST /v1/stt with multipart audio + UUID Idempotency-Key
  -> 200 and transcript for short audio
  -> 202 and queued ID for long audio
  -> GET /v1/stt/transcriptions/{id} until completed

Use a new UUID for new audio or fields. Retry the same upload with the same UUID after a timeout.

Saved transcriptions support cursor-paginated history, title updates, revision-safe editor updates, deletion, and TXT/JSON/SRT/VTT export. See Speech-to-Text for the full contracts.

Realtime WebSocket ​

text
Backend holds VOICELAB_API_KEY
  -> POST /v1/ticket
  -> short-lived ticket
  -> wss://api.voicelab.uz/v1/{tts|stt}/stream?ticket=...

Realtime TTS sends PCM16 mono audio at 24 kHz. Realtime STT accepts PCM16 mono audio at 16 kHz and returns a final result after commit. Do not put the long-lived API key in the WebSocket URL.

Reliability checklist ​

  1. [ ] The API key is server-side and permission-limited.
  2. [ ] TTS capabilities and voices come from discovery endpoints.
  3. [ ] Every TTS and STT create request has an idempotency key.
  4. [ ] 429 honors Retry-After with jittered exponential backoff.
  5. [ ] Cursor values are treated as opaque.
  6. [ ] Signed audio URLs are not cached or exposed publicly.
  7. [ ] Logs include request_id, but never credentials or ticket query strings.

Endpoint details: LLM · TTS · STT · Realtime TTS · Realtime STT