Theme

For AI agents ​

Start with /llms.txt. It contains the official SDK packages, authentication rules, and the complete endpoint inventory. Use /llms-api.txt when you need full request contracts, response shapes, realtime protocols, and error behavior.

Environment ​

bash
export VOICELAB_API_KEY=vlk_your_secret

Keep this secret in the tool runtime, never in a model prompt or browser bundle. Product endpoints authenticate with Authorization: Bearer $VOICELAB_API_KEY. Account-management endpoints require a user access JWT instead.

For TTS:

  1. Call GET /v1/tts/languages.
  2. Call GET /v1/voices?language={code}.
  3. Call POST /v1/tts with a unique idempotency key.
  4. Save the binary WAV response.

For STT:

  1. Call POST /v1/stt with multipart audio and a UUID idempotency key.
  2. If the API returns 202, poll GET /v1/stt/transcriptions/{id}.
  3. Use the history, editor, or export endpoints when the task requires durable output.

For Voice Isolator:

  1. Use a key with audio_isolation Access.
  2. Submit multipart file to POST /v1/voice-isolations with a UUID idempotency key. Reuse that key and content on retries.
  3. Poll job detail, including MP3 preparation after inference completes. Stop on a failed job or failed audio conversion.
  4. Download audio_url without forwarding the API key. Refresh detail when a signed URL expires.
  5. Request an export only if a different format is needed. DELETE hides history and does not cancel processing or erase audio.

For LLM:

  1. Use a key with llm Access and read GET /v1/models for IDs, prices, and limits.
  2. Send POST /v1/chat/completions with caller-supplied messages and a unique idempotency key.
  3. For SSE, parse events and wait for [DONE]; HTTP 200 alone is insufficient.
  4. Capture X-LLM-Request-ID and inspect GET /v1/llm/requests/{id} after an interrupted response or duplicate retry.
  5. Execute validated function calls in your application. Submit tool results in a new paid completion with a new idempotency key.
  6. Stop on llm_usage_pending and contact support. Do not retry under new keys.

For realtime work, call POST /v1/ticket and use the returned short-lived ticket in the WebSocket URL. Never place the API key itself in a WebSocket URL.

Tool definitions ​

Resolve voice_id from the voice catalog before calling the TTS tool.

json
[
  {
    "name": "voicelab_tts",
    "description": "Generate a 24 kHz mono WAV file from text with VoiceLab.",
    "input_schema": {
      "type": "object",
      "properties": {
        "text": { "type": "string", "description": "UTF-8 text, at most 1000 bytes" },
        "language": { "type": "string", "description": "Code returned by GET /v1/tts/languages" },
        "voice_id": { "type": "string", "description": "Opaque voice_... ID returned by GET /v1/voices" },
        "speed": { "type": "number", "minimum": 0.5, "maximum": 2.0, "default": 1.0 }
      },
      "required": ["text", "language", "voice_id"]
    }
  },
  {
    "name": "voicelab_stt",
    "description": "Transcribe an audio file with VoiceLab and optionally request speaker labels.",
    "input_schema": {
      "type": "object",
      "properties": {
        "file_path": { "type": "string", "description": "Path to MP3, WAV, M4A/AAC, OGG/Opus, WebM/Opus, or FLAC audio" },
        "language": { "type": "string", "enum": ["uz", "en", "ru"] },
        "include_speakers": { "type": "boolean", "default": false }
      },
      "required": ["file_path", "language"]
    }
  }
]

Retry rules ​

  • Use a new TTS idempotency key for every new generation. On a network failure, retry the identical body with the same key.
  • Use a new UUID for each new STT audio/field combination. Retry an identical upload with the same UUID.
  • Honor Retry-After for 429 and use jittered exponential backoff.
  • Do not automatically retry validation or authorization failures.
  • Log request_id for support, but never log API keys or realtime tickets.

References ​