Theme

Getting started ​

Send your first VoiceLab request with a server-side API key.

Use the VoiceLab API ​

  1. Create an API key

    Create a key in the VoiceLab app with TTS Access, Voices Read, and STT Access. The secret appears only once. Store it securely.

    dotenv
    VOICELAB_API_KEY=vlk_your_secret

    Send it in the authorization header:

    http
    Authorization: Bearer vlk_your_secret

    Never put a long-lived key in frontend code, a mobile app, logs, or a URL. See Authentication and API keys for permissions and rotation.

  2. Choose a voice

    Fetch the current language and voice catalogs. Do not hardcode them.

    bash
    curl -fS 'https://api.voicelab.uz/v1/tts/languages' \
  -H "Authorization: Bearer $VOICELAB_API_KEY"

curl -fS 'https://api.voicelab.uz/v1/voices?language=en' \
  -H "Authorization: Bearer $VOICELAB_API_KEY"

    Use a returned voice_... ID in the next request.

  3. Generate speech

    bash
    tts_http_status=$(curl -fS -w '%{http_code}' 'https://api.voicelab.uz/v1/tts' \
  -H "Authorization: Bearer $VOICELAB_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: hello-world-001' \
  -d '{
    "text": "Hello from VoiceLab.",
    "language": "en",
    "voice_id": "voice_01J9NEUTRAL0000000000000001",
    "speed": 1
  }' \
  -o tts-response)
case "$tts_http_status" in
  200) mv tts-response hello.wav ;;
  202) cat tts-response ;; # JSON job metadata; poll status_url
  *) cat tts-response >&2; exit 1 ;;
esac

    200 OK returns mono, 16-bit PCM WAV at 24 kHz. 202 returns a job ID; poll it before downloading audio. Retry submission timeouts with the same idempotency key and body.

  4. Transcribe audio

    bash
    curl -fS 'https://api.voicelab.uz/v1/stt' \
  -H "Authorization: Bearer $VOICELAB_API_KEY" \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -F 'audio=@meeting.mp3;type=audio/mpeg' \
  -F 'language=en' \
  -F 'include_speakers=false'

    Newly accepted uploads return 202, including short clips. Save the returned id and poll GET /v1/stt/transcriptions/{id} until completed or failed. Read transcript only after completion. See the STT reference for upload limits, polling, and error handling.

Next steps ​