Theme

For AI agents ​

Use llms.txt to find the Markdown reference for your task. Read AGENTS.md for credentials, retries, and tool safety. These files are public and need no API key or JavaScript.

For several APIs at once, fetch llms-api.txt. For one API, fetch its page, such as TTS Markdown.

Context Fetching Protocol ​

  1. Fetch https://docs.voicelab.uz/llms.txt and select the relevant reference.
  2. Read the current request fields, authentication, responses, and limits before coding.
  3. If the docs are unavailable or conflict with the response, report what you could not verify. Do not invent routes or copy another provider's contract.

Add these links to your agent's configuration. Publishing AGENTS.md alone neither configures external agents nor grants account permissions.

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 200 WAV audio. For 202, poll GET /v1/tts/generations/{id} until completed or failed; then download audio_url without API credentials.

For STT:

  1. Call POST /v1/stt with multipart audio and a UUID idempotency key.
  2. Save the 202 response's ID. Poll GET /v1/stt/transcriptions/{id} with stt:read until completed or failed. Read transcript only on completion. Resume the same ID after a timeout.
  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. Contact support for llm_model_temporarily_unavailable or llm_usage_pending. These holds require reconciliation; waiting or changing keys does not clear them. An upstream 499 does not prove zero cost.

For browser realtime work, your backend calls POST /v1/ticket with required transport=websocket and service=tts or stt. Success is 201 Created. Use the short-lived ticket only on the matching service. Both services also accept server-side xvl-api-key on the handshake, but never send it together with a ticket. 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": "1 to 5000 Unicode characters; complete JSON body at most 64 KiB" },
        "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 ​

  • Save an idempotency key before a paid request. Reuse it with identical input after a network failure. STT and Voice Isolator uploads require UUIDs.
  • 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 ​