vocal-sdk 0.3.0__tar.gz

vocal_sdk-0.3.0/.gitignore

@@ -0,0 +1,74 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+env/
+
+# UV
+uv.lock
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Jupyter
+.ipynb_checkpoints
+
+# Model cache
+.cache/
+models/
+*.ckpt
+*.pth
+*.pt
+*.safetensors
+
+# Audio files (test data)
+*.mp3
+*.wav
+*.m4a
+*.ogg
+*.flac
+
+# Logs
+*.log
+logs/
+
+# Environment variables
+.env
+.env.local
+
+# OS
+Thumbs.db

vocal_sdk-0.3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include ../../../README.md
+include ../../../LICENSE
+recursive-include vocal_sdk *.py
+include openapi.json

vocal_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: vocal-sdk
+Version: 0.3.0
+Summary: Python SDK for Vocal API - Auto-generated OpenAI-compatible client
+Project-URL: Homepage, https://github.com/niradler/vocal
+Project-URL: Documentation, https://github.com/niradler/vocal#readme
+Project-URL: Repository, https://github.com/niradler/vocal
+Project-URL: Issues, https://github.com/niradler/vocal/issues
+Author: Vocal Contributors
+License: SSPL-1.0
+Keywords: api-client,client,openai-compatible,sdk,speech-to-text,tts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.25.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: numpy>=1.24.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'

vocal_sdk-0.3.0/README.md

@@ -0,0 +1,64 @@
+# Vocal SDK
+
+Auto-generated Python SDK for the Vocal API.
+
+## Installation
+
+```bash
+cd packages/sdk
+uv pip install -e .
+```
+
+## Usage
+
+```python
+from vocal_sdk import VocalSDK
+
+# Initialize client
+client = VocalSDK(base_url="http://localhost:8000")
+
+# Check health
+health = client.health()
+print(health)
+
+# List models
+models = client.models.list()
+for model in models['models']:
+    print(f"{model['id']}: {model['status']}")
+
+# Download a model if needed
+model_id = "Systran/faster-whisper-tiny"
+model_info = client.models.get(model_id)
+if model_info['status'] != 'available':
+    client.models.download(model_id)
+
+# Transcribe audio
+result = client.audio.transcribe(
+    file="path/to/audio.mp3",
+    model=model_id,
+    language="en"  # optional
+)
+print(f"Transcription: {result['text']}")
+print(f"Language: {result['language']}")
+print(f"Duration: {result['duration']}s")
+```
+
+## Regenerating the SDK
+
+When the API changes, regenerate the SDK models:
+
+```bash
+# 1. Make sure API is running
+uv run uvicorn vocal_api.main:app --port 8000
+
+# 2. Download latest OpenAPI spec
+curl http://localhost:8000/openapi.json -o packages/sdk/openapi.json
+
+# 3. Generate models (optional - for type hints)
+cd packages/sdk
+uv run python scripts/generate.py
+```
+
+## API Documentation
+
+Interactive API docs available at: http://localhost:8000/docs

vocal_sdk-0.3.0/openapi.json

@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"Vocal API","description":"Generic Speech AI Platform (STT + TTS)","version":"0.1.0"},"paths":{"/v1/audio/transcriptions":{"post":{"tags":["transcription"],"summary":"Transcribe audio","description":"Transcribe audio file to text using specified model","operationId":"create_transcription_v1_audio_transcriptions_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_transcription_v1_audio_transcriptions_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/audio/translations":{"post":{"tags":["transcription"],"summary":"Translate audio to English","description":"Translate audio to English text","operationId":"create_translation_v1_audio_translations_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_translation_v1_audio_translations_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/models":{"get":{"tags":["models"],"summary":"List models","description":"List all available models (Ollama-style)","operationId":"list_models_v1_models_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"task","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/models/{model_id}":{"get":{"tags":["models"],"summary":"Get model info","description":"Get detailed information about a specific model","operationId":"get_model_v1_models__model_id__get","parameters":[{"name":"model_id","in":"path","required":true,"schema":{"type":"string","title":"Model Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["models"],"summary":"Delete model","description":"Remove a downloaded model","operationId":"delete_model_v1_models__model_id__delete","parameters":[{"name":"model_id","in":"path","required":true,"schema":{"type":"string","title":"Model Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/models/{model_id}/download":{"post":{"tags":["models"],"summary":"Download model","description":"Download a model for local use (Ollama-style pull)","operationId":"download_model_v1_models__model_id__download_post","parameters":[{"name":"model_id","in":"path","required":true,"schema":{"type":"string","title":"Model Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelDownloadProgress"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/models/{model_id}/download/status":{"get":{"tags":["models"],"summary":"Get download status","description":"Check model download progress","operationId":"get_download_status_v1_models__model_id__download_status_get","parameters":[{"name":"model_id","in":"path","required":true,"schema":{"type":"string","title":"Model Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelDownloadProgress"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/":{"get":{"tags":["health"],"summary":"Root","description":"API health check","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"tags":["health"],"summary":"Health","description":"Detailed health check","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Body_create_transcription_v1_audio_transcriptions_post":{"properties":{"file":{"type":"string","format":"binary","title":"File","description":"Audio file to transcribe"},"model":{"type":"string","title":"Model","description":"Model ID","default":"Systran/faster-whisper-tiny"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Language code"},"prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prompt","description":"Style prompt"},"response_format":{"$ref":"#/components/schemas/TranscriptionFormat","description":"Output format","default":"json"},"temperature":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Temperature","default":0.0}},"type":"object","required":["file"],"title":"Body_create_transcription_v1_audio_transcriptions_post"},"Body_create_translation_v1_audio_translations_post":{"properties":{"file":{"type":"string","format":"binary","title":"File"},"model":{"type":"string","title":"Model","default":"Systran/faster-whisper-tiny"}},"type":"object","required":["file"],"title":"Body_create_translation_v1_audio_translations_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ModelBackend":{"type":"string","enum":["faster_whisper","transformers","ctranslate2","nemo","onnx","custom"],"title":"ModelBackend","description":"Model inference backend"},"ModelDownloadProgress":{"properties":{"model_id":{"type":"string","title":"Model Id"},"status":{"type":"string","title":"Status"},"progress":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Progress","default":0.0},"downloaded_bytes":{"type":"integer","title":"Downloaded Bytes","default":0},"total_bytes":{"type":"integer","title":"Total Bytes","default":0},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["model_id","status"],"title":"ModelDownloadProgress","description":"Model download progress"},"ModelInfo":{"properties":{"id":{"type":"string","title":"Id","description":"Unique model identifier"},"name":{"type":"string","title":"Name","description":"Human-readable model name"},"provider":{"$ref":"#/components/schemas/ModelProvider","description":"Model provider"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"size":{"type":"integer","title":"Size","description":"Model size in bytes","default":0},"size_readable":{"type":"string","title":"Size Readable","description":"Human-readable size","default":"Unknown"},"parameters":{"type":"string","title":"Parameters","description":"Number of parameters","default":"Unknown"},"languages":{"items":{"type":"string"},"type":"array","title":"Languages","description":"Supported languages"},"backend":{"$ref":"#/components/schemas/ModelBackend","description":"Inference backend"},"status":{"$ref":"#/components/schemas/ModelStatus","description":"Current model status"},"source_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Source Url"},"license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License"},"recommended_vram":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recommended Vram"},"task":{"$ref":"#/components/schemas/ModelTask","description":"Task type"},"local_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Local Path"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["id","name","provider","backend","status","task"],"title":"ModelInfo","description":"Model information schema"},"ModelListResponse":{"properties":{"models":{"items":{"$ref":"#/components/schemas/ModelInfo"},"type":"array","title":"Models"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["models","total"],"title":"ModelListResponse","description":"List of available models"},"ModelProvider":{"type":"string","enum":["huggingface","local","custom"],"title":"ModelProvider","description":"Model provider/source"},"ModelStatus":{"type":"string","enum":["available","downloading","not_downloaded","error"],"title":"ModelStatus","description":"Model download/availability status"},"ModelTask":{"type":"string","enum":["stt","tts"],"title":"ModelTask","description":"Model task type"},"TranscriptionFormat":{"type":"string","enum":["json","text","srt","vtt","verbose_json"],"title":"TranscriptionFormat","description":"Output format for transcription"},"TranscriptionResponse":{"properties":{"text":{"type":"string","title":"Text","description":"Full transcribed text"},"language":{"type":"string","title":"Language","description":"Detected or specified language"},"duration":{"type":"number","title":"Duration","description":"Audio duration in seconds"},"segments":{"anyOf":[{"items":{"$ref":"#/components/schemas/TranscriptionSegment"},"type":"array"},{"type":"null"}],"title":"Segments"},"words":{"anyOf":[{"items":{"$ref":"#/components/schemas/TranscriptionWord"},"type":"array"},{"type":"null"}],"title":"Words"}},"type":"object","required":["text","language","duration"],"title":"TranscriptionResponse","description":"Response schema for transcription","example":{"duration":2.5,"language":"en","segments":[{"end":2.5,"id":0,"start":0.0,"text":"Hello, how are you today?"}],"text":"Hello, how are you today?"}},"TranscriptionSegment":{"properties":{"id":{"type":"integer","title":"Id"},"start":{"type":"number","title":"Start","description":"Start time in seconds"},"end":{"type":"number","title":"End","description":"End time in seconds"},"text":{"type":"string","title":"Text","description":"Transcribed text"},"tokens":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Tokens"},"temperature":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Temperature"},"avg_logprob":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Logprob"},"compression_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Compression Ratio"},"no_speech_prob":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"No Speech Prob"}},"type":"object","required":["id","start","end","text"],"title":"TranscriptionSegment","description":"A segment of transcribed text with timing"},"TranscriptionWord":{"properties":{"word":{"type":"string","title":"Word"},"start":{"type":"number","title":"Start"},"end":{"type":"number","title":"End"},"probability":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Probability"}},"type":"object","required":["word","start","end"],"title":"TranscriptionWord","description":"Word-level timestamp"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}

vocal_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "vocal-sdk"
+version = "0.3.0"
+description = "Python SDK for Vocal API - Auto-generated OpenAI-compatible client"
+requires-python = ">=3.11"
+license = { text = "SSPL-1.0" }
+authors = [
+    { name = "Vocal Contributors" }
+]
+keywords = ["sdk", "client", "speech-to-text", "tts", "openai-compatible", "api-client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.31.0",
+    "pydantic>=2.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/niradler/vocal"
+Documentation = "https://github.com/niradler/vocal#readme"
+Repository = "https://github.com/niradler/vocal"
+Issues = "https://github.com/niradler/vocal/issues"
+
+[project.optional-dependencies]
+dev = [
+    "datamodel-code-generator>=0.25.0",
+]
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "numpy>=1.24.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

vocal_sdk-0.3.0/scripts/generate.py

@@ -0,0 +1,46 @@
+"""
+Generate Python SDK from OpenAPI spec
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def generate_sdk():
+    """Generate SDK from OpenAPI spec"""
+    sdk_dir = Path(__file__).parent.parent
+    openapi_file = sdk_dir / "openapi.json"
+    output_dir = sdk_dir / "vocal_sdk"
+
+    if not openapi_file.exists():
+        print(f"Error: {openapi_file} not found")
+        print("Download it first:")
+        print("  curl http://localhost:8000/openapi.json -o packages/sdk/openapi.json")
+        sys.exit(1)
+
+    print("Generating SDK from OpenAPI spec...")
+
+    # Generate Pydantic models
+    subprocess.run(
+        [
+            "datamodel-codegen",
+            "--input",
+            str(openapi_file),
+            "--input-file-type",
+            "openapi",
+            "--output",
+            str(output_dir / "models.py"),
+            "--field-constraints",
+            "--use-standard-collections",
+        ],
+        check=True,
+    )
+
+    print(f"✓ Generated models at {output_dir / 'models.py'}")
+    print("\nSDK generated successfully!")
+    print(f"Location: {output_dir}")
+
+
+if __name__ == "__main__":
+    generate_sdk()

vocal_sdk-0.3.0/vocal_sdk/__init__.py

@@ -0,0 +1,10 @@
+"""
+Vocal SDK - Python client for Vocal API
+
+Auto-generated from OpenAPI specification.
+"""
+
+from .client import AudioAPI, ModelsAPI, VocalSDK
+
+__version__ = "0.3.0"
+__all__ = ["VocalSDK", "ModelsAPI", "AudioAPI"]

vocal_sdk-0.3.0/vocal_sdk/client.py

@@ -0,0 +1,327 @@
+"""
+Vocal SDK - Auto-generated client for Vocal API
+
+This SDK provides a clean Python interface to the Vocal API.
+Models are auto-generated from the OpenAPI spec.
+"""
+
+from pathlib import Path
+from typing import Any, BinaryIO
+from urllib.parse import urljoin
+
+import requests
+
+
+class VocalSDK:
+    """
+    Vocal SDK Client
+
+    Example:
+        >>> from vocal_sdk import VocalSDK
+        >>> client = VocalSDK(base_url="http://localhost:8000")
+        >>>
+        >>> # List models
+        >>> models = client.models.list()
+        >>> print(f"Found {len(models['models'])} models")
+        >>>
+        >>> # Transcribe audio
+        >>> result = client.audio.transcribe("recording.mp3")
+        >>> print(result['text'])
+        >>>
+        >>> # Text to speech
+        >>> audio = client.audio.text_to_speech("Hello, world!")
+        >>> with open("output.wav", "wb") as f:
+        >>>     f.write(audio)
+    """
+
+    def __init__(self, base_url: str = "http://localhost:8000", timeout: int = 300):
+        """
+        Initialize Vocal SDK
+
+        Args:
+            base_url: Base URL of Vocal API
+            timeout: Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+
+        # Namespaced APIs
+        self.models = ModelsAPI(self)
+        self.audio = AudioAPI(self)
+
+    def _request(self, method: str, endpoint: str, **kwargs) -> dict[str, Any]:
+        """Make HTTP request to API"""
+        url = urljoin(self.base_url + "/", endpoint.lstrip("/"))
+
+        if "timeout" not in kwargs:
+            kwargs["timeout"] = self.timeout
+
+        response = self.session.request(method, url, **kwargs)
+        response.raise_for_status()
+
+        return response.json()
+
+    def _request_raw(self, method: str, endpoint: str, **kwargs) -> bytes:
+        """Make HTTP request and return raw bytes"""
+        url = urljoin(self.base_url + "/", endpoint.lstrip("/"))
+
+        if "timeout" not in kwargs:
+            kwargs["timeout"] = self.timeout
+
+        response = self.session.request(method, url, **kwargs)
+        response.raise_for_status()
+
+        return response.content
+
+    def health(self) -> dict[str, Any]:
+        """Check API health"""
+        return self._request("GET", "/health")
+
+
+class ModelsAPI:
+    """Models API namespace"""
+
+    def __init__(self, client: VocalSDK):
+        self.client = client
+
+    def list(self, status: str | None = None, task: str | None = None) -> dict[str, Any]:
+        """
+        List all available models
+
+        Args:
+            status: Filter by status (available, downloading, not_downloaded)
+            task: Filter by task (stt, tts)
+
+        Returns:
+            Dictionary with 'models' list and 'total' count
+        """
+        params = {}
+        if status:
+            params["status"] = status
+        if task:
+            params["task"] = task
+
+        return self.client._request("GET", "/v1/models", params=params)
+
+    def get(self, model_id: str) -> dict[str, Any]:
+        """
+        Get model information
+
+        Args:
+            model_id: Model identifier (e.g., "Systran/faster-whisper-tiny")
+
+        Returns:
+            Model information dictionary
+        """
+        return self.client._request("GET", f"/v1/models/{model_id}")
+
+    def download(self, model_id: str, quantization: str | None = None) -> dict[str, Any]:
+        """
+        Download a model (Ollama-style pull)
+
+        Args:
+            model_id: Model identifier
+            quantization: Optional quantization format
+
+        Returns:
+            Download progress information
+        """
+        data = {}
+        if quantization:
+            data["quantization"] = quantization
+
+        return self.client._request("POST", f"/v1/models/{model_id}/download", json=data if data else None)
+
+    def download_status(self, model_id: str) -> dict[str, Any]:
+        """
+        Check download status for a model
+
+        Args:
+            model_id: Model identifier
+
+        Returns:
+            Download status information
+        """
+        return self.client._request("GET", f"/v1/models/{model_id}/download/status")
+
+    def delete(self, model_id: str) -> dict[str, Any]:
+        """
+        Delete a downloaded model
+
+        Args:
+            model_id: Model identifier
+
+        Returns:
+            Deletion confirmation
+        """
+        return self.client._request("DELETE", f"/v1/models/{model_id}")
+
+
+class AudioAPI:
+    """Audio API namespace"""
+
+    def __init__(self, client: VocalSDK):
+        self.client = client
+
+    def transcribe(
+        self,
+        file: str | Path | BinaryIO,
+        model: str = "Systran/faster-whisper-tiny",
+        language: str | None = None,
+        response_format: str = "json",
+        temperature: float = 0.0,
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        Transcribe audio to text
+
+        Args:
+            file: Path to audio file or file-like object
+            model: Model to use for transcription
+            language: Language code (e.g., "en", "es") or None for auto-detect
+            response_format: Output format (json, text, srt, vtt)
+            temperature: Sampling temperature (0.0-1.0)
+            **kwargs: Additional parameters
+
+        Returns:
+            Transcription result with text, language, duration, segments
+
+        Example:
+            >>> result = client.audio.transcribe("audio.mp3")
+            >>> print(result['text'])
+            >>> print(f"Language: {result['language']}")
+        """
+        if isinstance(file, (str, Path)):
+            with open(file, "rb") as f:
+                return self._transcribe_file(f, model, language, response_format, temperature, **kwargs)
+        else:
+            return self._transcribe_file(file, model, language, response_format, temperature, **kwargs)
+
+    def _transcribe_file(
+        self,
+        file_obj: BinaryIO,
+        model: str,
+        language: str | None,
+        response_format: str,
+        temperature: float,
+        **kwargs,
+    ) -> dict[str, Any]:
+        """Internal method to transcribe file object"""
+        files = {"file": file_obj}
+        data = {
+            "model": model,
+            "response_format": response_format,
+            "temperature": temperature,
+            **kwargs,
+        }
+
+        if language:
+            data["language"] = language
+
+        return self.client._request("POST", "/v1/audio/transcriptions", files=files, data=data)
+
+    def translate(
+        self,
+        file: str | Path | BinaryIO,
+        model: str = "Systran/faster-whisper-tiny",
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        Translate audio to English
+
+        Args:
+            file: Path to audio file or file-like object
+            model: Model to use for translation
+            **kwargs: Additional parameters
+
+        Returns:
+            Translation result
+        """
+        if isinstance(file, (str, Path)):
+            with open(file, "rb") as f:
+                files = {"file": f}
+                data = {"model": model, **kwargs}
+                return self.client._request("POST", "/v1/audio/translations", files=files, data=data)
+        else:
+            files = {"file": file}
+            data = {"model": model, **kwargs}
+            return self.client._request("POST", "/v1/audio/translations", files=files, data=data)
+
+    def text_to_speech(
+        self,
+        text: str,
+        model: str = "pyttsx3",
+        voice: str | None = None,
+        speed: float = 1.0,
+        response_format: str = "wav",
+        output_file: str | Path | None = None,
+    ) -> bytes:
+        """
+        Convert text to speech (TTS)
+
+        Args:
+            text: Text to convert to speech
+            model: TTS model to use (default: 'pyttsx3' for system TTS)
+            voice: Voice ID to use (None for default)
+            speed: Speech speed multiplier (0.25 to 4.0)
+            response_format: Audio format (currently only 'wav' supported)
+            output_file: Optional path to save audio file
+
+        Returns:
+            Audio data as bytes
+
+        Example:
+            >>> audio = client.audio.text_to_speech("Hello, world!")
+            >>> with open("output.wav", "wb") as f:
+            >>>     f.write(audio)
+
+            >>> # Or save directly
+            >>> client.audio.text_to_speech("Hello!", output_file="hello.wav")
+
+            >>> # Use specific TTS model
+            >>> audio = client.audio.text_to_speech(
+            ...     "Hello!",
+            ...     model="hexgrad/Kokoro-82M"
+            ... )
+        """
+        data = {
+            "model": model,
+            "input": text,
+            "speed": speed,
+            "response_format": response_format,
+        }
+
+        if voice:
+            data["voice"] = voice
+
+        audio_data = self.client._request_raw("POST", "/v1/audio/speech", json=data)
+
+        if output_file:
+            output_path = Path(output_file)
+            output_path.write_bytes(audio_data)
+
+        return audio_data
+
+    def list_voices(self, model: str | None = None) -> dict[str, Any]:
+        """
+        List available TTS voices
+
+        Args:
+            model: Optional model ID to list voices for a specific model
+
+        Returns:
+            Dictionary with 'voices' list and 'total' count
+
+        Example:
+            >>> voices = client.audio.list_voices()
+            >>> for voice in voices['voices']:
+            >>>     print(f"{voice['id']}: {voice['name']} ({voice['language']})")
+        """
+        params = {}
+        if model:
+            params["model"] = model
+        return self.client._request("GET", "/v1/audio/voices", params=params)
+
+
+__all__ = ["VocalSDK", "ModelsAPI", "AudioAPI"]