voicekit-client 0.1.0__tar.gz

voicekit_client-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: voicekit-client
+Version: 0.1.0
+Summary: Official Python SDK for VoiceKit (synthesis, transcription, analysis, moderation, batches).
+Author: VoiceKit
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://ttsapi.ru
+Project-URL: Documentation, https://ttsapi.ru/swagger
+Keywords: tts,speech,synthesis,transcription,stt,voice,russian
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+Provides-Extra: streaming
+Requires-Dist: websockets>=12.0; extra == "streaming"
+
+# VoiceKit — Python SDK
+
+Official Python wrapper for [VoiceKit](https://ttsapi.ru):
+neural speech synthesis, transcription, sentiment analysis, and batch operations.
+
+## Install
+
+```bash
+pip install voicekit-client
+```
+
+## Quick start
+
+```python
+from voicekit import VoiceKitClient, b64
+
+client = VoiceKitClient(api_key="YOUR_KEY")
+
+# Synthesis → raw audio bytes
+audio = client.synthesize("Привет! Это синтез русской речи.", voice="preset_anna", format="mp3")
+with open("speech.mp3", "wb") as f:
+    f.write(audio)
+
+# Streaming (Pro/Business)
+for chunk in client.synthesize_stream("Первое предложение. Второе."):
+    pass  # write chunks to a file or socket
+
+# Transcription (async → poll)
+job = client.transcribe("audio.wav", keyterms=["диагноз"])
+result = client.get_transcription_job(job["job_id"])
+while result["status"] not in ("completed", "failed"):
+    result = client.get_transcription_job(job["job_id"])
+
+# Short-file sync transcription
+transcript = client.transcribe_sync("audio.wav")
+
+# Analysis (sentiment + keywords + entities)
+analysis = client.analyze_sync("audio.wav")
+
+# Text intelligence
+lang = client.detect_language("Как дела?")
+topics = client.topics("Нейросети и алгоритмы")
+summary = client.summarize("Длинный текст для резюме.", max_sentences=3)
+moderation = client.moderate("Это оскорбительное сообщение.")
+
+# Batches
+batch = client.batch_synthesize([
+    {"text": "Первый текст", "voice": "preset_anna"},
+    {"text": "Второй текст", "voice": "dmitri"},
+])
+status = client.get_batch(batch["batch_id"])
+
+analysis_batch = client.batch_analyze([
+    {"audio": b64("a.wav"), "language": "ru"},
+    {"audio": b64("b.wav"), "language": "ru"},
+])
+
+# Voice cloning (Pro/Business)
+clone = client.create_clone_voice(
+    name="My voice",
+    prompt_text="Точный текст образца.",
+    samples="reference.wav",
+)
+print(client.list_clone_voices())
+client.delete_clone_voice(clone["id"])
+
+# VAD (speech segments)
+segments = client.vad("audio.wav")
+
+# Account
+usage = client.usage()
+balance = client.billing_balance()
+```
+
+### Audio effects (Pro/Business)
+
+```python
+# Inline during synthesis — the chain is applied to the synthesized audio
+audio = client.synthesize(
+    "Привет!",
+    effects='[{"type":"reverb","room_size":0.5},{"type":"pitch","semitones":2}]',
+)
+
+# Async processing of an existing file
+import time
+
+job = client.apply_audio_effects("voice.mp3", [{"type": "compressor", "ratio": 3}])
+while client.get_audio_effects_job(job["job_id"])["status"] not in ("completed", "failed"):
+    time.sleep(1)
+result = client.download_audio_effects(job["job_id"])
+open("voice_fx.mp3", "wb").write(result)
+```
+
+### WebSocket streaming (Pro/Business)
+
+Требует опциональной зависимости:
+
+```bash
+pip install "voicekit-client[streaming]"
+```
+
+```python
+import asyncio
+
+async def main():
+    client = VoiceKitClient(api_key="YOUR_KEY")
+
+    stream = await client.transcribe_stream(language="ru", keyterms=["диагноз"])
+    await stream.send_audio(pcm16_chunk_1)   # raw PCM16, 16 kHz mono
+    await stream.send_audio(pcm16_chunk_2)
+    await stream.stop()                       # finalize the utterance
+    async for event in stream:                # session / vad / partial / final / error
+        print(event["type"], event)
+    await stream.close()
+
+    vad = await client.vad_stream()           # VAD events only (speech_started/ended)
+    await vad.send_audio(pcm16_chunk)
+    await vad.stop()
+    async for event in vad:
+        print(event["type"], event)
+    await vad.close()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `api_key` | — | API key (required) |
+| `base_url` | `https://ttsapi.ru` | API base URL (e.g. `http://localhost:5080` for local dev) |
+| `timeout` | `120.0` | Per-request timeout in seconds |
+
+Errors raise `VoiceKitError` with `.status` (HTTP status), `.code` (machine-readable
+code) and `.message`.

voicekit_client-0.1.0/README.md

@@ -0,0 +1,135 @@
+# VoiceKit — Python SDK
+
+Official Python wrapper for [VoiceKit](https://ttsapi.ru):
+neural speech synthesis, transcription, sentiment analysis, and batch operations.
+
+## Install
+
+```bash
+pip install voicekit-client
+```
+
+## Quick start
+
+```python
+from voicekit import VoiceKitClient, b64
+
+client = VoiceKitClient(api_key="YOUR_KEY")
+
+# Synthesis → raw audio bytes
+audio = client.synthesize("Привет! Это синтез русской речи.", voice="preset_anna", format="mp3")
+with open("speech.mp3", "wb") as f:
+    f.write(audio)
+
+# Streaming (Pro/Business)
+for chunk in client.synthesize_stream("Первое предложение. Второе."):
+    pass  # write chunks to a file or socket
+
+# Transcription (async → poll)
+job = client.transcribe("audio.wav", keyterms=["диагноз"])
+result = client.get_transcription_job(job["job_id"])
+while result["status"] not in ("completed", "failed"):
+    result = client.get_transcription_job(job["job_id"])
+
+# Short-file sync transcription
+transcript = client.transcribe_sync("audio.wav")
+
+# Analysis (sentiment + keywords + entities)
+analysis = client.analyze_sync("audio.wav")
+
+# Text intelligence
+lang = client.detect_language("Как дела?")
+topics = client.topics("Нейросети и алгоритмы")
+summary = client.summarize("Длинный текст для резюме.", max_sentences=3)
+moderation = client.moderate("Это оскорбительное сообщение.")
+
+# Batches
+batch = client.batch_synthesize([
+    {"text": "Первый текст", "voice": "preset_anna"},
+    {"text": "Второй текст", "voice": "dmitri"},
+])
+status = client.get_batch(batch["batch_id"])
+
+analysis_batch = client.batch_analyze([
+    {"audio": b64("a.wav"), "language": "ru"},
+    {"audio": b64("b.wav"), "language": "ru"},
+])
+
+# Voice cloning (Pro/Business)
+clone = client.create_clone_voice(
+    name="My voice",
+    prompt_text="Точный текст образца.",
+    samples="reference.wav",
+)
+print(client.list_clone_voices())
+client.delete_clone_voice(clone["id"])
+
+# VAD (speech segments)
+segments = client.vad("audio.wav")
+
+# Account
+usage = client.usage()
+balance = client.billing_balance()
+```
+
+### Audio effects (Pro/Business)
+
+```python
+# Inline during synthesis — the chain is applied to the synthesized audio
+audio = client.synthesize(
+    "Привет!",
+    effects='[{"type":"reverb","room_size":0.5},{"type":"pitch","semitones":2}]',
+)
+
+# Async processing of an existing file
+import time
+
+job = client.apply_audio_effects("voice.mp3", [{"type": "compressor", "ratio": 3}])
+while client.get_audio_effects_job(job["job_id"])["status"] not in ("completed", "failed"):
+    time.sleep(1)
+result = client.download_audio_effects(job["job_id"])
+open("voice_fx.mp3", "wb").write(result)
+```
+
+### WebSocket streaming (Pro/Business)
+
+Требует опциональной зависимости:
+
+```bash
+pip install "voicekit-client[streaming]"
+```
+
+```python
+import asyncio
+
+async def main():
+    client = VoiceKitClient(api_key="YOUR_KEY")
+
+    stream = await client.transcribe_stream(language="ru", keyterms=["диагноз"])
+    await stream.send_audio(pcm16_chunk_1)   # raw PCM16, 16 kHz mono
+    await stream.send_audio(pcm16_chunk_2)
+    await stream.stop()                       # finalize the utterance
+    async for event in stream:                # session / vad / partial / final / error
+        print(event["type"], event)
+    await stream.close()
+
+    vad = await client.vad_stream()           # VAD events only (speech_started/ended)
+    await vad.send_audio(pcm16_chunk)
+    await vad.stop()
+    async for event in vad:
+        print(event["type"], event)
+    await vad.close()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `api_key` | — | API key (required) |
+| `base_url` | `https://ttsapi.ru` | API base URL (e.g. `http://localhost:5080` for local dev) |
+| `timeout` | `120.0` | Per-request timeout in seconds |
+
+Errors raise `VoiceKitError` with `.status` (HTTP status), `.code` (machine-readable
+code) and `.message`.

voicekit_client-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "voicekit-client"
+version = "0.1.0"
+description = "Official Python SDK for VoiceKit (synthesis, transcription, analysis, moderation, batches)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "LicenseRef-Proprietary"
+authors = [{ name = "VoiceKit" }]
+keywords = ["tts", "speech", "synthesis", "transcription", "stt", "voice", "russian"]
+dependencies = ["httpx>=0.24"]
+
+[project.optional-dependencies]
+streaming = ["websockets>=12.0"]
+
+[project.urls]
+Homepage = "https://ttsapi.ru"
+Documentation = "https://ttsapi.ru/swagger"
+
+[tool.setuptools.packages.find]
+include = ["voicekit*"]

voicekit_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

voicekit_client-0.1.0/voicekit/__init__.py

@@ -0,0 +1,11 @@
+from voicekit.client import VoiceKitClient, VoiceKitError
+from voicekit.streaming import TranscriptionStream, VadStream, WsStream
+
+__all__ = [
+    "VoiceKitClient",
+    "VoiceKitError",
+    "TranscriptionStream",
+    "VadStream",
+    "WsStream",
+]
+__version__ = "0.1.0"

voicekit_client-0.1.0/voicekit/client.py

@@ -0,0 +1,545 @@
+"""Official Python SDK for VoiceKit.
+
+Usage::
+
+    from voicekit import VoiceKitClient
+
+    client = VoiceKitClient(api_key="YOUR_KEY")
+
+    audio = client.synthesize("Привет!", voice="preset_anna", format="mp3")
+    with open("speech.mp3", "wb") as f:
+        f.write(audio)
+
+    job = client.transcribe("audio.wav")            # async → job id
+    result = client.get_transcription_job(job["job_id"])
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from typing import Any, BinaryIO, Iterable, Iterator, Optional, Union
+from urllib.parse import urlencode, urlsplit, urlunsplit
+
+import httpx
+
+from .streaming import TranscriptionStream, VadStream, websockets_connect
+
+DEFAULT_BASE_URL = "https://ttsapi.ru"
+
+
+class VoiceKitError(Exception):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(self, status: int, message: str, code: str = "") -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+        self.code = code
+
+
+AudioSource = Union[str, bytes, BinaryIO, os.PathLike]
+
+
+class VoiceKitClient:
+    """Thin, typed wrapper over the VoiceKit REST API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = 120.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._base_url = base_url.rstrip("/")
+        self._headers = {"X-Api-Key": api_key}
+        self._timeout = timeout
+
+    # ──────────────────────── Synthesis ────────────────────────────────
+
+    def synthesize(
+        self,
+        text: str,
+        *,
+        voice: str = "preset_anna",
+        format: str = "mp3",
+        sample_rate: Optional[int] = None,
+        speed: Optional[float] = None,
+        pitch: Optional[float] = None,
+        emotion: Optional[str] = None,
+        ssml: Optional[bool] = None,
+        put_accent: Optional[bool] = None,
+        put_yo: Optional[bool] = None,
+        normalize: Optional[bool] = None,
+        model: Optional[str] = None,
+        language: Optional[str] = None,
+        effects: Optional[str] = None,
+    ) -> bytes:
+        """Synthesize speech and return the raw audio bytes.
+
+        ``effects`` is an optional JSON-encoded string holding an array of
+        effect descriptors applied after synthesis (Pro/Business).
+        """
+        body = _compact(
+            text=text,
+            voice=voice,
+            format=format,
+            sample_rate=sample_rate,
+            speed=speed,
+            pitch=pitch,
+            emotion=emotion,
+            ssml=ssml,
+            put_accent=put_accent,
+            put_yo=put_yo,
+            normalize=normalize,
+            model=model,
+            language=language,
+            effects=effects,
+        )
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.post("/v1/synthesize", headers=self._headers, json=body)
+            _raise_for_status(response)
+            return response.content
+
+    def synthesize_stream(
+        self,
+        text: str,
+        *,
+        voice: str = "preset_anna",
+        format: str = "mp3",
+        **kwargs: Any,
+    ) -> Iterator[bytes]:
+        """Synthesize and yield audio chunks as they are produced (Pro/Business)."""
+        body = _compact(text=text, voice=voice, format=format, **kwargs)
+        with httpx.stream(
+            "POST",
+            f"{self._base_url}/v1/synthesize/stream",
+            headers=self._headers,
+            json=body,
+            timeout=self._timeout,
+        ) as response:
+            _raise_for_status(response)
+            yield from response.iter_bytes()
+
+    def synthesize_async(
+        self,
+        text: str,
+        *,
+        voice: str = "preset_anna",
+        format: str = "wav",
+        sample_rate: Optional[int] = None,
+        speed: Optional[float] = None,
+        model: Optional[str] = None,
+        language: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Queue a long-form (audiobook) synthesis job.
+
+        Poll with :meth:`get_synthesis_job` and download the produced WAV with
+        :meth:`download_synthesis_audio`. Long-form synthesis returns WAV only.
+        """
+        body = _compact(
+            text=text,
+            voice=voice,
+            format=format,
+            sample_rate=sample_rate,
+            speed=speed,
+            model=model,
+            language=language,
+        )
+        params = {"webhookUrl": webhook_url} if webhook_url else None
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.post(
+                "/v1/synthesize/async", headers=self._headers, json=body, params=params
+            )
+            _raise_for_status(response)
+            return response.json()
+
+    def get_synthesis_job(self, job_id: str) -> dict[str, Any]:
+        """Poll a long-form synthesis job; returns the audiobook manifest when done."""
+        return self._get_json(f"/v1/synthesize/async/{job_id}")
+
+    def download_synthesis_audio(self, job_id: str) -> bytes:
+        """Download the produced WAV for a completed long-form synthesis job."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.get(
+                f"/v1/synthesize/async/{job_id}/audio", headers=self._headers
+            )
+            _raise_for_status(response)
+            return response.content
+
+    def voices(self) -> list[dict[str, Any]]:
+        """Return the voice catalog."""
+        return self._get_json("/v1/voices")
+
+    def voice(self, voice_id: str) -> dict[str, Any]:
+        """Return one voice by id (e.g. ``preset_anna``)."""
+        return self._get_json(f"/v1/voices/{voice_id}")
+
+    # ──────────────────────── Voice cloning ────────────────────────────
+
+    def create_clone_voice(
+        self,
+        name: str,
+        prompt_text: str,
+        samples: Union[AudioSource, Iterable[AudioSource]],
+        language: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Create a cloned voice from reference audio (Pro/Business).
+
+        ``samples`` is one or more reference audio files; ``prompt_text`` is the
+        exact transcript of the reference clip.
+        """
+        sample_list = [samples] if _is_audio_source(samples) else list(samples)
+        files = [("samples", _file_tuple(sample)) for sample in sample_list]
+        data = _compact(name=name, prompt_text=prompt_text, language=language)
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.post(
+                "/v1/voices/clone", headers=self._headers, files=files, data=data
+            )
+            _raise_for_status(response)
+            return response.json()
+
+    def list_clone_voices(self) -> list[dict[str, Any]]:
+        """List the caller's cloned voices."""
+        return self._get_json("/v1/voices/clone")
+
+    def get_clone_voice(self, clone_id: str) -> dict[str, Any]:
+        """Return one cloned voice by id."""
+        return self._get_json(f"/v1/voices/clone/{clone_id}")
+
+    def delete_clone_voice(self, clone_id: str) -> None:
+        """Delete a cloned voice (and its reference latents)."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.delete(
+                f"/v1/voices/clone/{clone_id}", headers=self._headers
+            )
+            _raise_for_status(response)
+
+    # ──────────────────────── Transcription ────────────────────────────
+
+    def transcribe(
+        self,
+        audio: AudioSource,
+        *,
+        language: Optional[str] = None,
+        diarization: bool = False,
+        webhook_url: Optional[str] = None,
+        keyterms: Optional[Iterable[str]] = None,
+    ) -> dict[str, Any]:
+        """Start an async transcription job; poll with get_transcription_job()."""
+        files = {"audio": _file_tuple(audio)}
+        data = _compact(language=language, diarization=diarization, webhookUrl=webhook_url)
+        if keyterms:
+            data["keyterms"] = ",".join(keyterms)
+        return self._post_form("/v1/transcribe", files=files, data=data)
+
+    def transcribe_sync(
+        self,
+        audio: AudioSource,
+        *,
+        language: Optional[str] = None,
+        diarization: bool = False,
+        keyterms: Optional[Iterable[str]] = None,
+    ) -> dict[str, Any]:
+        """Transcribe a short file (≤ 3 min) synchronously."""
+        files = {"audio": _file_tuple(audio)}
+        data = _compact(language=language, diarization=diarization)
+        if keyterms:
+            data["keyterms"] = ",".join(keyterms)
+        return self._post_form("/v1/transcribe/sync", files=files, data=data)
+
+    def get_transcription_job(self, job_id: str) -> dict[str, Any]:
+        return self._get_json(f"/v1/transcribe/{job_id}")
+
+    def subtitles(self, job_id: str, format: str = "vtt") -> str:
+        """Download VTT/SRT subtitles for a completed transcription job."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.get(
+                f"/v1/transcribe/{job_id}/subtitles",
+                headers=self._headers,
+                params={"format": format},
+            )
+            _raise_for_status(response)
+            return response.text
+
+    def vad(self, audio: AudioSource) -> dict[str, Any]:
+        """Detect speech segments in an audio file (Silero VAD)."""
+        return self._post_form(
+            "/v1/vad", files={"audio": _file_tuple(audio)}, data={}
+        )
+
+    # ──────────────────────── Analysis ─────────────────────────────────
+
+    def analyze(
+        self,
+        audio: AudioSource,
+        *,
+        language: Optional[str] = None,
+        diarization: bool = False,
+        webhook_url: Optional[str] = None,
+        keyterms: Optional[Iterable[str]] = None,
+    ) -> dict[str, Any]:
+        """Start an async analysis job; poll with get_analysis_job()."""
+        files = {"audio": _file_tuple(audio)}
+        data = _compact(language=language, diarization=diarization, webhookUrl=webhook_url)
+        if keyterms:
+            data["keyterms"] = ",".join(keyterms)
+        return self._post_form("/v1/analyze", files=files, data=data)
+
+    def analyze_sync(
+        self,
+        audio: AudioSource,
+        *,
+        language: Optional[str] = None,
+        diarization: bool = False,
+        emotions: bool = True,
+        keywords: bool = True,
+        entities: bool = True,
+        keyterms: Optional[Iterable[str]] = None,
+    ) -> dict[str, Any]:
+        """Analyze a short file (≤ 3 min) synchronously."""
+        files = {"audio": _file_tuple(audio)}
+        data = _compact(
+            language=language,
+            diarization=diarization,
+            emotions=emotions,
+            keywords=keywords,
+            entities=entities,
+        )
+        if keyterms:
+            data["keyterms"] = ",".join(keyterms)
+        return self._post_form("/v1/analyze/sync", files=files, data=data)
+
+    def get_analysis_job(self, job_id: str) -> dict[str, Any]:
+        return self._get_json(f"/v1/analyze/{job_id}")
+
+    # ──────────────────────── Text intelligence ────────────────────────
+
+    def detect_language(self, text: str) -> dict[str, Any]:
+        return self._post_json("/v1/detect-language", {"text": text})
+
+    def redact(self, text: str, language: Optional[str] = None) -> dict[str, Any]:
+        return self._post_json("/v1/redact", _compact(text=text, language=language))
+
+    def topics(self, text: str, language: Optional[str] = None) -> dict[str, Any]:
+        return self._post_json("/v1/analyze/topics", _compact(text=text, language=language))
+
+    def summarize(
+        self, text: str, language: Optional[str] = None, max_sentences: Optional[int] = None
+    ) -> dict[str, Any]:
+        return self._post_json(
+            "/v1/analyze/summarize",
+            _compact(text=text, language=language, max_sentences=max_sentences),
+        )
+
+    def moderate(self, text: str, language: Optional[str] = None) -> dict[str, Any]:
+        """Flag profanity, insults and hate speech in raw text."""
+        return self._post_json("/v1/moderate", _compact(text=text, language=language))
+
+    # ──────────────────────── Audio / video effects ───────────────────
+
+    def apply_audio_effects(
+        self,
+        audio: AudioSource,
+        effects: Iterable[dict[str, Any]],
+        *,
+        output_format: str = "wav",
+        webhook_url: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Start an async audio-effects job; poll with get_audio_effects_job().
+
+        ``effects`` is a list of effect descriptors, e.g.
+        ``[{"type": "reverb", "room_size": 0.5}]``.
+        """
+        files = {"audio": _file_tuple(audio)}
+        data = {"effects": json.dumps(list(effects), ensure_ascii=False), "output_format": output_format}
+        if webhook_url:
+            data["webhookUrl"] = webhook_url
+        return self._post_form("/v1/audio/effects", files=files, data=data)
+
+    def get_audio_effects_job(self, job_id: str) -> dict[str, Any]:
+        """Poll an audio-effects job; returns the manifest when completed."""
+        return self._get_json(f"/v1/audio/effects/{job_id}")
+
+    def download_audio_effects(self, job_id: str) -> bytes:
+        """Download the produced audio for a completed audio-effects job."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.get(f"/v1/audio/effects/{job_id}/audio", headers=self._headers)
+            _raise_for_status(response)
+            return response.content
+
+    def apply_video_effects(
+        self,
+        video: AudioSource,
+        effects: Iterable[dict[str, Any]],
+        *,
+        mode: str = "mux",
+        audio: Optional[AudioSource] = None,
+        output_format: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """Start an async video-effects job; poll with get_video_effects_job().
+
+        ``mode`` is ``mux`` (video output) or ``audio`` (processed audio
+        extracted from the video). For ``mux`` you may pass a separate ``audio``
+        file to replace the video's audio track.
+        """
+        files = {"video": _file_tuple(video, "video/mp4")}
+        if audio is not None:
+            files["audio"] = _file_tuple(audio)
+        data = {"effects": json.dumps(list(effects), ensure_ascii=False), "mode": mode}
+        if output_format:
+            data["output_format"] = output_format
+        if webhook_url:
+            data["webhookUrl"] = webhook_url
+        return self._post_form("/v1/video/effects", files=files, data=data)
+
+    def get_video_effects_job(self, job_id: str) -> dict[str, Any]:
+        """Poll a video-effects job; returns the manifest when completed."""
+        return self._get_json(f"/v1/video/effects/{job_id}")
+
+    def download_video_effects(self, job_id: str) -> bytes:
+        """Download the produced artifact (video or audio) for a video-effects job."""
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.get(f"/v1/video/effects/{job_id}/file", headers=self._headers)
+            _raise_for_status(response)
+            return response.content
+
+    # ──────────────────────── Batch ────────────────────────────────────
+
+    def batch_synthesize(self, items: Iterable[dict[str, Any]]) -> dict[str, Any]:
+        """Queue a batch of synthesis requests; poll with get_batch()."""
+        return self._post_json("/v1/batch/synthesize", {"items": list(items)})
+
+    def batch_analyze(
+        self,
+        items: Iterable[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Queue a batch of analysis requests; each item needs inline base64 `audio`."""
+        return self._post_json("/v1/batch/analyze", {"items": list(items)})
+
+    def get_batch(self, batch_id: str) -> dict[str, Any]:
+        return self._get_json(f"/v1/batch/{batch_id}")
+
+    # ──────────────────────── Account ──────────────────────────────────
+
+    def usage(self) -> dict[str, Any]:
+        """Current monthly character usage for the authenticated key."""
+        return self._get_json("/v1/usage")
+
+    def billing_balance(self) -> dict[str, Any]:
+        """Current balance, plan and recent transactions."""
+        return self._get_json("/v1/billing/balance")
+
+    # ──────────────────────── Streaming (WebSocket) ────────────────────
+
+    async def transcribe_stream(
+        self,
+        *,
+        language: Optional[str] = None,
+        keyterms: Optional[Iterable[str]] = None,
+        interim: bool = True,
+    ) -> TranscriptionStream:
+        """Open a streaming transcription session (Pro/Business).
+
+        Send PCM16 chunks with ``send_audio()``, finalize with ``stop()``, then
+        iterate the returned object to receive JSON events.
+        """
+        params: dict[str, Any] = {"language": language, "interim": interim}
+        if keyterms:
+            params["keyterms"] = ",".join(keyterms)
+        return TranscriptionStream(
+            await websockets_connect(self._ws_url("/v1/transcribe/stream", params))
+        )
+
+    async def vad_stream(self) -> VadStream:
+        """Open a streaming turn-detection session (VAD events only)."""
+        return VadStream(
+            await websockets_connect(self._ws_url("/v1/vad/stream", {}))
+        )
+
+    # ──────────────────────── Transport ────────────────────────────────
+
+    def _get_json(self, path: str) -> Any:
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.get(path, headers=self._headers)
+            _raise_for_status(response)
+            return response.json()
+
+    def _post_json(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.post(path, headers=self._headers, json=body)
+            _raise_for_status(response)
+            return response.json()
+
+    def _post_form(
+        self,
+        path: str,
+        *,
+        files: dict[str, Any],
+        data: dict[str, Any],
+    ) -> dict[str, Any]:
+        with httpx.Client(base_url=self._base_url, timeout=self._timeout) as http:
+            response = http.post(path, headers=self._headers, files=files, data=data)
+            _raise_for_status(response)
+            return response.json()
+
+    def _ws_url(self, path: str, params: dict[str, Any]) -> str:
+        """Build a ``ws(s)://`` URL for a streaming endpoint from the base URL."""
+        parts = urlsplit(self._base_url)
+        scheme = "wss" if parts.scheme == "https" else "ws"
+        query = urlencode(_query_params(params))
+        return urlunsplit((scheme, parts.netloc, path, query, ""))
+
+
+# ──────────────────────── Helpers ──────────────────────────────────────
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    code = ""
+    detail = response.text
+    try:
+        payload = response.json()
+        code = payload.get("code", "")
+        detail = payload.get("detail") or payload.get("title") or detail
+    except ValueError:
+        pass
+    raise VoiceKitError(response.status_code, detail, code)
+
+
+def _compact(**kwargs: Any) -> dict[str, Any]:
+    return {key: value for key, value in kwargs.items() if value is not None}
+
+
+def _file_tuple(audio: AudioSource, content_type: str = "audio/wav") -> tuple[str, bytes, str]:
+    if isinstance(audio, bytes):
+        return ("audio.wav", audio, content_type)
+    if hasattr(audio, "read"):
+        data = audio.read()  # type: ignore[union-attr]
+        return ("audio.wav", data, content_type)
+    with open(os.fspath(audio), "rb") as f:
+        return (os.path.basename(os.fspath(audio)), f.read(), content_type)
+
+
+def _is_audio_source(value: Any) -> bool:
+    return isinstance(value, (str, bytes, os.PathLike)) or hasattr(value, "read")
+
+
+def _query_params(params: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None or value == "":
+            continue
+        out[key] = "true" if value is True else "false" if value is False else value
+    return out
+
+
+def b64(audio: AudioSource) -> str:
+    """Encode audio (bytes or a file path) as base64 for batch_analyze()."""
+    _, data, _ = _file_tuple(audio)
+    return base64.b64encode(data).decode("ascii")

voicekit_client-0.1.0/voicekit/streaming.py

@@ -0,0 +1,84 @@
+"""WebSocket streaming helpers for VoiceKit.
+
+Streaming requires the optional dependency::
+
+    pip install "voicekit[streaming]"
+
+Both helpers send raw PCM16 (16 kHz, mono, little-endian) binary frames to the
+server and receive JSON events back (`session`, `vad`, `partial`, `final`,
+`error`). See the API docs for the full event schema.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Optional
+
+try:  # optional dependency — imported lazily so the core SDK stays light
+    import websockets
+except ImportError:  # pragma: no cover
+    websockets = None
+
+
+def _require_websockets() -> Any:
+    if websockets is None:
+        raise ImportError(
+            "WebSocket streaming requires the 'websockets' package. "
+            'Install it with: pip install "voicekit[streaming]"'
+        )
+    return websockets
+
+
+async def websockets_connect(url: str) -> Any:
+    ws = _require_websockets()
+    return await ws.connect(url)
+
+
+class WsStream:
+    """A connected streaming session (transcription or VAD)."""
+
+    def __init__(self, ws: Any) -> None:
+        self._ws = ws
+
+    async def send_audio(self, pcm16: bytes) -> None:
+        """Send raw PCM16 (16 kHz, mono, little-endian) as a binary frame."""
+        await self._ws.send(pcm16)
+
+    async def send_text(self, payload: Any) -> None:
+        """Send a text frame; dicts/lists are JSON-encoded."""
+        if isinstance(payload, str):
+            await self._ws.send(payload)
+        else:
+            await self._ws.send(json.dumps(payload, ensure_ascii=False))
+
+    async def stop(self) -> None:
+        """Signal end of speech so the server finalizes the utterance."""
+        await self.send_text({"type": "stop"})
+
+    async def recv_event(self) -> Optional[dict[str, Any]]:
+        """Receive the next JSON event, or ``None`` when the session closed."""
+        try:
+            message = await self._ws.recv()
+        except _require_websockets().exceptions.ConnectionClosed:
+            return None
+        return message if isinstance(message, dict) else json.loads(message)
+
+    async def close(self) -> None:
+        await self._ws.close()
+
+    def __aiter__(self) -> AsyncIterator[dict[str, Any]]:
+        return self
+
+    async def __anext__(self) -> dict[str, Any]:
+        event = await self.recv_event()
+        if event is None:
+            raise StopAsyncIteration
+        return event
+
+
+class TranscriptionStream(WsStream):
+    """Streaming transcription session (``WS /v1/transcribe/stream``)."""
+
+
+class VadStream(WsStream):
+    """Streaming turn detection session (``WS /v1/vad/stream``)."""

voicekit_client-0.1.0/voicekit_client.egg-info/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: voicekit-client
+Version: 0.1.0
+Summary: Official Python SDK for VoiceKit (synthesis, transcription, analysis, moderation, batches).
+Author: VoiceKit
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://ttsapi.ru
+Project-URL: Documentation, https://ttsapi.ru/swagger
+Keywords: tts,speech,synthesis,transcription,stt,voice,russian
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+Provides-Extra: streaming
+Requires-Dist: websockets>=12.0; extra == "streaming"
+
+# VoiceKit — Python SDK
+
+Official Python wrapper for [VoiceKit](https://ttsapi.ru):
+neural speech synthesis, transcription, sentiment analysis, and batch operations.
+
+## Install
+
+```bash
+pip install voicekit-client
+```
+
+## Quick start
+
+```python
+from voicekit import VoiceKitClient, b64
+
+client = VoiceKitClient(api_key="YOUR_KEY")
+
+# Synthesis → raw audio bytes
+audio = client.synthesize("Привет! Это синтез русской речи.", voice="preset_anna", format="mp3")
+with open("speech.mp3", "wb") as f:
+    f.write(audio)
+
+# Streaming (Pro/Business)
+for chunk in client.synthesize_stream("Первое предложение. Второе."):
+    pass  # write chunks to a file or socket
+
+# Transcription (async → poll)
+job = client.transcribe("audio.wav", keyterms=["диагноз"])
+result = client.get_transcription_job(job["job_id"])
+while result["status"] not in ("completed", "failed"):
+    result = client.get_transcription_job(job["job_id"])
+
+# Short-file sync transcription
+transcript = client.transcribe_sync("audio.wav")
+
+# Analysis (sentiment + keywords + entities)
+analysis = client.analyze_sync("audio.wav")
+
+# Text intelligence
+lang = client.detect_language("Как дела?")
+topics = client.topics("Нейросети и алгоритмы")
+summary = client.summarize("Длинный текст для резюме.", max_sentences=3)
+moderation = client.moderate("Это оскорбительное сообщение.")
+
+# Batches
+batch = client.batch_synthesize([
+    {"text": "Первый текст", "voice": "preset_anna"},
+    {"text": "Второй текст", "voice": "dmitri"},
+])
+status = client.get_batch(batch["batch_id"])
+
+analysis_batch = client.batch_analyze([
+    {"audio": b64("a.wav"), "language": "ru"},
+    {"audio": b64("b.wav"), "language": "ru"},
+])
+
+# Voice cloning (Pro/Business)
+clone = client.create_clone_voice(
+    name="My voice",
+    prompt_text="Точный текст образца.",
+    samples="reference.wav",
+)
+print(client.list_clone_voices())
+client.delete_clone_voice(clone["id"])
+
+# VAD (speech segments)
+segments = client.vad("audio.wav")
+
+# Account
+usage = client.usage()
+balance = client.billing_balance()
+```
+
+### Audio effects (Pro/Business)
+
+```python
+# Inline during synthesis — the chain is applied to the synthesized audio
+audio = client.synthesize(
+    "Привет!",
+    effects='[{"type":"reverb","room_size":0.5},{"type":"pitch","semitones":2}]',
+)
+
+# Async processing of an existing file
+import time
+
+job = client.apply_audio_effects("voice.mp3", [{"type": "compressor", "ratio": 3}])
+while client.get_audio_effects_job(job["job_id"])["status"] not in ("completed", "failed"):
+    time.sleep(1)
+result = client.download_audio_effects(job["job_id"])
+open("voice_fx.mp3", "wb").write(result)
+```
+
+### WebSocket streaming (Pro/Business)
+
+Требует опциональной зависимости:
+
+```bash
+pip install "voicekit-client[streaming]"
+```
+
+```python
+import asyncio
+
+async def main():
+    client = VoiceKitClient(api_key="YOUR_KEY")
+
+    stream = await client.transcribe_stream(language="ru", keyterms=["диагноз"])
+    await stream.send_audio(pcm16_chunk_1)   # raw PCM16, 16 kHz mono
+    await stream.send_audio(pcm16_chunk_2)
+    await stream.stop()                       # finalize the utterance
+    async for event in stream:                # session / vad / partial / final / error
+        print(event["type"], event)
+    await stream.close()
+
+    vad = await client.vad_stream()           # VAD events only (speech_started/ended)
+    await vad.send_audio(pcm16_chunk)
+    await vad.stop()
+    async for event in vad:
+        print(event["type"], event)
+    await vad.close()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `api_key` | — | API key (required) |
+| `base_url` | `https://ttsapi.ru` | API base URL (e.g. `http://localhost:5080` for local dev) |
+| `timeout` | `120.0` | Per-request timeout in seconds |
+
+Errors raise `VoiceKitError` with `.status` (HTTP status), `.code` (machine-readable
+code) and `.message`.

voicekit_client-0.1.0/voicekit_client.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+voicekit/__init__.py
+voicekit/client.py
+voicekit/streaming.py
+voicekit_client.egg-info/PKG-INFO
+voicekit_client.egg-info/SOURCES.txt
+voicekit_client.egg-info/dependency_links.txt
+voicekit_client.egg-info/requires.txt
+voicekit_client.egg-info/top_level.txt

voicekit_client-0.1.0/voicekit_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

voicekit_client-0.1.0/voicekit_client.egg-info/requires.txt

@@ -0,0 +1,4 @@
+httpx>=0.24
+
+[streaming]
+websockets>=12.0

voicekit_client-0.1.0/voicekit_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+voicekit