runapi-elevenlabs 0.1.0__tar.gz

runapi_elevenlabs-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: runapi-elevenlabs
+Version: 0.1.0
+Summary: ElevenLabs speech, dialogue, sound, and audio client for RunAPI
+Project-URL: Homepage, https://runapi.ai/models/elevenlabs
+Project-URL: Documentation, https://runapi.ai/docs#sdk-elevenlabs
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,audio,elevenlabs,runapi,sdk,speech-to-text,text-to-speech
+Requires-Python: >=3.9
+Requires-Dist: runapi-core
+Description-Content-Type: text/markdown
+
+# Elevenlabs API Python SDK for RunAPI
+
+The elevenlabs api Python SDK is the language-specific package for ElevenLabs on RunAPI. Use this elevenlabs api package for voice, dialogue, transcription, sound effect, and cleanup flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Python.
+
+This elevenlabs api README is the Python package guide inside the public `elevenlabs-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/elevenlabs; for API reference, use https://runapi.ai/docs#elevenlabs; for SDK docs, use https://runapi.ai/docs#sdk-elevenlabs.
+
+## Install
+
+```bash
+pip install runapi-elevenlabs
+```
+
+## Quick start
+
+```python
+from runapi.elevenlabs import ElevenlabsClient
+
+client = ElevenlabsClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_speech.create(
+    model="text-to-speech-turbo-v2.5",
+    text="Hello from RunAPI",
+)
+status = client.text_to_speech.get(task.id)
+
+transcription = client.speech_to_text.create(
+    source_audio_url="https://example.com/clip.mp3",
+)
+```
+
+Use `create` when you want to submit a task and return quickly, `get` when you need the latest task state, and `run` when a script should create and poll until completion:
+
+```python
+result = client.text_to_speech.run(
+    model="text-to-speech-turbo-v2.5",
+    text="A calm narrator voice reading the morning news",
+)
+print(result.audios[0].url)
+```
+
+In web request handlers, prefer `create` plus webhook or later `get` polling so a worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.
+
+## Language notes
+
+Pass parameters as keyword arguments and catch the `runapi.elevenlabs` error classes when building audio jobs or scripts. The available resources are `text_to_speech`, `text_to_dialogue`, `text_to_sound`, `speech_to_text`, and `isolate_audio`. Keep `RUNAPI_API_KEY` in the environment or your secret manager; never commit API keys or callback secrets.
+
+## Links
+
+- Model page: https://runapi.ai/models/elevenlabs
+- SDK docs: https://runapi.ai/docs#sdk-elevenlabs
+- Product docs: https://runapi.ai/docs#elevenlabs
+- Pricing and rate limits: https://runapi.ai/models/elevenlabs/text-to-speech-turbo-v2.5
+- Provider comparison: https://runapi.ai/providers/elevenlabs
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/elevenlabs-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_elevenlabs-0.1.0/README.md

@@ -0,0 +1,61 @@
+# Elevenlabs API Python SDK for RunAPI
+
+The elevenlabs api Python SDK is the language-specific package for ElevenLabs on RunAPI. Use this elevenlabs api package for voice, dialogue, transcription, sound effect, and cleanup flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Python.
+
+This elevenlabs api README is the Python package guide inside the public `elevenlabs-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/elevenlabs; for API reference, use https://runapi.ai/docs#elevenlabs; for SDK docs, use https://runapi.ai/docs#sdk-elevenlabs.
+
+## Install
+
+```bash
+pip install runapi-elevenlabs
+```
+
+## Quick start
+
+```python
+from runapi.elevenlabs import ElevenlabsClient
+
+client = ElevenlabsClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_speech.create(
+    model="text-to-speech-turbo-v2.5",
+    text="Hello from RunAPI",
+)
+status = client.text_to_speech.get(task.id)
+
+transcription = client.speech_to_text.create(
+    source_audio_url="https://example.com/clip.mp3",
+)
+```
+
+Use `create` when you want to submit a task and return quickly, `get` when you need the latest task state, and `run` when a script should create and poll until completion:
+
+```python
+result = client.text_to_speech.run(
+    model="text-to-speech-turbo-v2.5",
+    text="A calm narrator voice reading the morning news",
+)
+print(result.audios[0].url)
+```
+
+In web request handlers, prefer `create` plus webhook or later `get` polling so a worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files in your own durable storage within 7 days; do not treat returned URLs as long-term assets.
+
+## Language notes
+
+Pass parameters as keyword arguments and catch the `runapi.elevenlabs` error classes when building audio jobs or scripts. The available resources are `text_to_speech`, `text_to_dialogue`, `text_to_sound`, `speech_to_text`, and `isolate_audio`. Keep `RUNAPI_API_KEY` in the environment or your secret manager; never commit API keys or callback secrets.
+
+## Links
+
+- Model page: https://runapi.ai/models/elevenlabs
+- SDK docs: https://runapi.ai/docs#sdk-elevenlabs
+- Product docs: https://runapi.ai/docs#elevenlabs
+- Pricing and rate limits: https://runapi.ai/models/elevenlabs/text-to-speech-turbo-v2.5
+- Provider comparison: https://runapi.ai/providers/elevenlabs
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/elevenlabs-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_elevenlabs-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runapi-elevenlabs"
+version = "0.1.0"
+description = "ElevenLabs speech, dialogue, sound, and audio client for RunAPI"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [{ name = "RunAPI", email = "contact@runapi.ai" }]
+keywords = ["runapi", "elevenlabs", "text-to-speech", "speech-to-text", "audio", "ai", "sdk"]
+dependencies = ["runapi-core"]
+
+[project.urls]
+Homepage = "https://runapi.ai/models/elevenlabs"
+Documentation = "https://runapi.ai/docs#sdk-elevenlabs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/runapi"]
+
+[tool.uv]
+package = true
+
+[tool.uv.sources]
+runapi-core = { path = "../runapi-core", editable = true }
+
+[dependency-groups]
+dev = ["pytest>=8"]

runapi_elevenlabs-0.1.0/src/runapi/elevenlabs/__init__.py

@@ -0,0 +1,24 @@
+"""ElevenLabs client for RunAPI."""
+
+from runapi.core import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    TaskFailedError,
+    TaskTimeoutError,
+    ValidationError,
+)
+
+from .client import ElevenlabsClient
+
+__all__ = [
+    "ElevenlabsClient",
+    "AuthenticationError",
+    "RateLimitError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "ValidationError",
+    "TaskFailedError",
+    "TaskTimeoutError",
+]

runapi_elevenlabs-0.1.0/src/runapi/elevenlabs/client.py

@@ -0,0 +1,35 @@
+"""ElevenLabs client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ClientOptions, HttpClient, resolve_api_key
+
+from .resources.isolate_audio import IsolateAudio
+from .resources.speech_to_text import SpeechToText
+from .resources.text_to_dialogue import TextToDialogue
+from .resources.text_to_sound import TextToSound
+from .resources.text_to_speech import TextToSpeech
+
+
+class ElevenlabsClient:
+    """ElevenLabs speech, dialogue, sound, and audio client.
+
+    Example::
+
+        client = ElevenlabsClient(api_key="sk-...")
+        result = client.text_to_speech.run(
+            model="text-to-speech-turbo-v2.5", text="Hello from RunAPI"
+        )
+    """
+
+    def __init__(self, api_key: Optional[str] = None, **options: Any) -> None:
+        resolved_api_key = resolve_api_key(api_key)
+        client_options = ClientOptions(api_key=resolved_api_key, **options)
+        http = client_options.http_client or HttpClient(client_options)
+        self.text_to_speech = TextToSpeech(http)
+        self.text_to_dialogue = TextToDialogue(http)
+        self.text_to_sound = TextToSound(http)
+        self.speech_to_text = SpeechToText(http)
+        self.isolate_audio = IsolateAudio(http)

runapi_elevenlabs-0.1.0/src/runapi/elevenlabs/resources/__init__.py

@@ -0,0 +1,13 @@
+from .isolate_audio import IsolateAudio
+from .speech_to_text import SpeechToText
+from .text_to_dialogue import TextToDialogue
+from .text_to_sound import TextToSound
+from .text_to_speech import TextToSpeech
+
+__all__ = [
+    "TextToSpeech",
+    "TextToDialogue",
+    "TextToSound",
+    "SpeechToText",
+    "IsolateAudio",
+]

runapi_elevenlabs-0.1.0/src/runapi/elevenlabs/resources/isolate_audio.py

@@ -0,0 +1,55 @@
+"""ElevenLabs isolate-audio resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runapi.core import Resource, ValidationError
+
+from ..types import AudioTaskResponse, CompletedAudioTaskResponse
+
+
+class IsolateAudio(Resource):
+    """Isolate voice from background noise in audio with ElevenLabs models."""
+
+    ENDPOINT = "/api/v1/elevenlabs/isolate_audio"
+
+    RESPONSE_CLASS = AudioTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedAudioTaskResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create an isolate-audio task and poll until it completes.
+
+        Args:
+            **params: Isolate-audio parameters (model, prompt, ...).
+
+        Returns:
+            The completed isolate-audio response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create an isolate-audio task and return immediately with an id.
+
+        Args:
+            **params: Isolate-audio parameters (model, prompt, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        if compacted.get("source_audio_url") is None:
+            raise ValidationError("source_audio_url is required")
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of an isolate-audio task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current isolate-audio status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")

runapi_elevenlabs-0.1.0/src/runapi/elevenlabs/resources/speech_to_text.py

@@ -0,0 +1,55 @@
+"""ElevenLabs speech-to-text resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runapi.core import Resource, ValidationError
+
+from ..types import CompletedSpeechToTextResponse, SpeechToTextResponse
+
+
+class SpeechToText(Resource):
+    """Transcribe speech audio to text with ElevenLabs models."""
+
+    ENDPOINT = "/api/v1/elevenlabs/speech_to_text"
+
+    RESPONSE_CLASS = SpeechToTextResponse
+    COMPLETED_RESPONSE_CLASS = CompletedSpeechToTextResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create a speech-to-text task and poll until it completes.
+
+        Args:
+            **params: Speech-to-text parameters (model, prompt, ...).
+
+        Returns:
+            The completed speech-to-text response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a speech-to-text task and return immediately with an id.
+
+        Args:
+            **params: Speech-to-text parameters (model, prompt, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        if compacted.get("source_audio_url") is None:
+            raise ValidationError("source_audio_url is required")
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of a speech-to-text task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current speech-to-text status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")

runapi_elevenlabs-0.1.0/src/runapi/elevenlabs/resources/text_to_dialogue.py

@@ -0,0 +1,55 @@
+"""ElevenLabs text-to-dialogue resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runapi.core import Resource, ValidationError
+
+from ..types import AudioTaskResponse, CompletedAudioTaskResponse
+
+
+class TextToDialogue(Resource):
+    """Generate multi-speaker dialogue audio with ElevenLabs models."""
+
+    ENDPOINT = "/api/v1/elevenlabs/text_to_dialogue"
+
+    RESPONSE_CLASS = AudioTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedAudioTaskResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create a text-to-dialogue task and poll until it completes.
+
+        Args:
+            **params: Text-to-dialogue parameters (model, prompt, ...).
+
+        Returns:
+            The completed text-to-dialogue response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a text-to-dialogue task and return immediately with an id.
+
+        Args:
+            **params: Text-to-dialogue parameters (model, prompt, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        if compacted.get("dialogue") is None:
+            raise ValidationError("dialogue is required")
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of a text-to-dialogue task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current text-to-dialogue status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")

runapi_elevenlabs-0.1.0/src/runapi/elevenlabs/resources/text_to_sound.py

@@ -0,0 +1,62 @@
+"""ElevenLabs text-to-sound resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    TEXT_TO_SOUND_OUTPUT_FORMATS,
+    AudioTaskResponse,
+    CompletedAudioTaskResponse,
+)
+
+
+class TextToSound(Resource):
+    """Generate sound effects from text prompts with ElevenLabs models."""
+
+    ENDPOINT = "/api/v1/elevenlabs/text_to_sound"
+
+    RESPONSE_CLASS = AudioTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedAudioTaskResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create a text-to-sound task and poll until it completes.
+
+        Args:
+            **params: Text-to-sound parameters (model, prompt, ...).
+
+        Returns:
+            The completed text-to-sound response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a text-to-sound task and return immediately with an id.
+
+        Args:
+            **params: Text-to-sound parameters (model, prompt, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        if compacted.get("text") is None:
+            raise ValidationError("text is required")
+        output_format = compacted.get("output_format")
+        if output_format is not None and output_format not in TEXT_TO_SOUND_OUTPUT_FORMATS:
+            raise ValidationError("Invalid output_format")
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of a text-to-sound task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current text-to-sound status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")

runapi_elevenlabs-0.1.0/src/runapi/elevenlabs/resources/text_to_speech.py

@@ -0,0 +1,69 @@
+"""ElevenLabs text-to-speech resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    TEXT_TO_SPEECH_MODELS,
+    AudioTaskResponse,
+    CompletedAudioTaskResponse,
+)
+
+
+class TextToSpeech(Resource):
+    """Generate speech audio from text with ElevenLabs models."""
+
+    ENDPOINT = "/api/v1/elevenlabs/text_to_speech"
+
+    RESPONSE_CLASS = AudioTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedAudioTaskResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create a text-to-speech task and poll until it completes.
+
+        Args:
+            **params: Text-to-speech parameters (model, prompt, ...).
+
+        Returns:
+            The completed text-to-speech response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a text-to-speech task and return immediately with an id.
+
+        Args:
+            **params: Text-to-speech parameters (model, prompt, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        self._validate_params(compacted)
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of a text-to-speech task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current text-to-speech status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        model = params.get("model")
+        if model is None:
+            raise ValidationError("model is required")
+        if model not in TEXT_TO_SPEECH_MODELS:
+            raise ValidationError(f"Invalid model: {model}")
+        if params.get("text") is None:
+            raise ValidationError("text is required")
+        if model == "text-to-speech-multilingual-v2" and params.get("voice") is None:
+            raise ValidationError("voice is required for text-to-speech-multilingual-v2")

runapi_elevenlabs-0.1.0/src/runapi/elevenlabs/types.py

@@ -0,0 +1,64 @@
+"""ElevenLabs model lists, enums, and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+TEXT_TO_SPEECH_MODELS = [
+    "text-to-speech-turbo-v2.5",
+    "text-to-speech-multilingual-v2",
+]
+DEFAULT_TEXT_TO_SPEECH_VOICE = "EkK5I93UQWFDigLMpZcX"
+TEXT_TO_SOUND_OUTPUT_FORMATS = [
+    "mp3_22050_32",
+    "mp3_44100_32",
+    "mp3_44100_64",
+    "mp3_44100_96",
+    "mp3_44100_128",
+    "mp3_44100_192",
+    "pcm_8000",
+    "pcm_16000",
+    "pcm_22050",
+    "pcm_24000",
+    "pcm_44100",
+    "pcm_48000",
+    "ulaw_8000",
+    "alaw_8000",
+    "opus_48000_32",
+    "opus_48000_64",
+    "opus_48000_96",
+    "opus_48000_128",
+    "opus_48000_192",
+]
+
+
+class Audio(BaseModel):
+    url = optional(str)
+
+
+class AsyncTaskResponse(TaskResponse):
+    id = required(str)
+    status = optional(str, enum=lambda: TaskResponse.Status.ALL)
+
+
+class AudioTaskResponse(AsyncTaskResponse):
+    """Task status/result for ElevenLabs audio generation."""
+    audios = optional([lambda: Audio])
+    error = optional(str)
+
+
+class SpeechToTextResponse(AsyncTaskResponse):
+    """Task status/result for ElevenLabs speech-to-text."""
+    text = optional(str)
+    error = optional(str)
+
+
+# Narrowed responses returned by ``run()`` methods once polling observes
+# ``status: "completed"``. Result fields are required so consumers never have to
+# null-check them on a successful task.
+class CompletedAudioTaskResponse(AudioTaskResponse):
+    audios = required([lambda: Audio])
+
+
+class CompletedSpeechToTextResponse(SpeechToTextResponse):
+    text = required(str)

runapi_elevenlabs-0.1.0/tests/test_client.py

@@ -0,0 +1,220 @@
+import pytest
+
+from runapi.core import config
+from runapi.core.errors import AuthenticationError, ValidationError
+from runapi.elevenlabs import ElevenlabsClient
+from runapi.elevenlabs.resources.isolate_audio import IsolateAudio
+from runapi.elevenlabs.resources.speech_to_text import SpeechToText
+from runapi.elevenlabs.resources.text_to_dialogue import TextToDialogue
+from runapi.elevenlabs.resources.text_to_sound import TextToSound
+from runapi.elevenlabs.resources.text_to_speech import TextToSpeech
+from runapi.elevenlabs.types import (
+    AudioTaskResponse,
+    CompletedAudioTaskResponse,
+    CompletedSpeechToTextResponse,
+    SpeechToTextResponse,
+)
+
+
+class FakeHttp:
+    def __init__(self, *responses):
+        self._responses = list(responses)
+        self.calls = []
+
+    def request(self, method, path, body=None, options=None):
+        self.calls.append((method, path, body))
+        if self._responses:
+            return self._responses.pop(0)
+        return {"id": "task_1", "status": "pending"}
+
+
+@pytest.fixture(autouse=True)
+def reset_config(monkeypatch):
+    monkeypatch.delenv("RUNAPI_API_KEY", raising=False)
+    monkeypatch.setattr(config, "api_key", None)
+    yield
+
+
+# --- auth -----------------------------------------------------------------
+
+
+def test_accepts_api_key_parameter():
+    assert isinstance(ElevenlabsClient(api_key="k", http_client=FakeHttp()), ElevenlabsClient)
+
+
+def test_falls_back_to_global(monkeypatch):
+    monkeypatch.setattr(config, "api_key", "global-key")
+    assert isinstance(ElevenlabsClient(http_client=FakeHttp()), ElevenlabsClient)
+
+
+def test_falls_back_to_env(monkeypatch):
+    monkeypatch.setenv("RUNAPI_API_KEY", "env-key")
+    assert isinstance(ElevenlabsClient(http_client=FakeHttp()), ElevenlabsClient)
+
+
+def test_raises_without_api_key():
+    with pytest.raises(AuthenticationError, match="API key is required"):
+        ElevenlabsClient()
+
+
+# --- injection / accessors ------------------------------------------------
+
+
+def test_uses_injected_http_client():
+    fake = FakeHttp()
+    client = ElevenlabsClient(api_key="k", http_client=fake)
+    assert client.text_to_speech._http is fake
+    assert client.text_to_dialogue._http is fake
+    assert client.text_to_sound._http is fake
+    assert client.speech_to_text._http is fake
+    assert client.isolate_audio._http is fake
+
+
+def test_exposes_resource_accessors():
+    client = ElevenlabsClient(api_key="k", http_client=FakeHttp())
+    assert isinstance(client.text_to_speech, TextToSpeech)
+    assert isinstance(client.text_to_dialogue, TextToDialogue)
+    assert isinstance(client.text_to_sound, TextToSound)
+    assert isinstance(client.speech_to_text, SpeechToText)
+    assert isinstance(client.isolate_audio, IsolateAudio)
+
+
+# --- request shapes -------------------------------------------------------
+
+
+def test_text_to_speech_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = ElevenlabsClient(api_key="k", http_client=fake)
+    result = client.text_to_speech.create(
+        model="text-to-speech-turbo-v2.5", text="hello", voice=None
+    )
+    assert fake.calls == [
+        ("post", "/api/v1/elevenlabs/text_to_speech", {"model": "text-to-speech-turbo-v2.5", "text": "hello"}),
+    ]
+    assert isinstance(result, AudioTaskResponse)
+
+
+def test_text_to_speech_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = ElevenlabsClient(api_key="k", http_client=fake)
+    client.text_to_speech.get("t1")
+    assert fake.calls == [("get", "/api/v1/elevenlabs/text_to_speech/t1", None)]
+
+
+def test_text_to_dialogue_create_shape():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = ElevenlabsClient(api_key="k", http_client=fake)
+    client.text_to_dialogue.create(dialogue=[{"text": "Hi", "voice": "Rachel"}])
+    assert fake.calls == [
+        ("post", "/api/v1/elevenlabs/text_to_dialogue", {"dialogue": [{"text": "Hi", "voice": "Rachel"}]}),
+    ]
+
+
+def test_text_to_sound_create_shape():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = ElevenlabsClient(api_key="k", http_client=fake)
+    client.text_to_sound.create(text="rain on a tin roof", output_format="mp3_44100_128")
+    assert fake.calls == [
+        ("post", "/api/v1/elevenlabs/text_to_sound", {"text": "rain on a tin roof", "output_format": "mp3_44100_128"}),
+    ]
+
+
+def test_speech_to_text_create_shape():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = ElevenlabsClient(api_key="k", http_client=fake)
+    result = client.speech_to_text.create(source_audio_url="https://x/a.mp3")
+    assert fake.calls == [
+        ("post", "/api/v1/elevenlabs/speech_to_text", {"source_audio_url": "https://x/a.mp3"}),
+    ]
+    assert isinstance(result, SpeechToTextResponse)
+
+
+def test_isolate_audio_create_shape():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = ElevenlabsClient(api_key="k", http_client=fake)
+    client.isolate_audio.create(source_audio_url="https://x/a.mp3")
+    assert fake.calls == [
+        ("post", "/api/v1/elevenlabs/isolate_audio", {"source_audio_url": "https://x/a.mp3"}),
+    ]
+
+
+# --- run() narrowing ------------------------------------------------------
+
+
+def test_text_to_speech_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "audios": [{"url": "https://x/y.mp3"}]},
+    )
+    client = ElevenlabsClient(api_key="k", http_client=fake)
+    result = client.text_to_speech.run(model="text-to-speech-turbo-v2.5", text="hi there")
+    assert isinstance(result, CompletedAudioTaskResponse)
+    assert result.audios[0].url == "https://x/y.mp3"
+
+
+def test_speech_to_text_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "text": "transcribed words"},
+    )
+    client = ElevenlabsClient(api_key="k", http_client=fake)
+    result = client.speech_to_text.run(source_audio_url="https://x/a.mp3")
+    assert isinstance(result, CompletedSpeechToTextResponse)
+    assert result.text == "transcribed words"
+
+
+# --- validation -----------------------------------------------------------
+
+
+def test_text_to_speech_requires_model():
+    client = ElevenlabsClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model is required"):
+        client.text_to_speech.create(text="hi")
+
+
+def test_text_to_speech_rejects_unknown_model():
+    client = ElevenlabsClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid model: nope"):
+        client.text_to_speech.create(model="nope", text="hi")
+
+
+def test_text_to_speech_requires_text():
+    client = ElevenlabsClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="text is required"):
+        client.text_to_speech.create(model="text-to-speech-turbo-v2.5")
+
+
+def test_text_to_speech_multilingual_requires_voice():
+    client = ElevenlabsClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="voice is required for text-to-speech-multilingual-v2"):
+        client.text_to_speech.create(model="text-to-speech-multilingual-v2", text="hi")
+
+
+def test_text_to_dialogue_requires_dialogue():
+    client = ElevenlabsClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="dialogue is required"):
+        client.text_to_dialogue.create()
+
+
+def test_text_to_sound_requires_text():
+    client = ElevenlabsClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="text is required"):
+        client.text_to_sound.create()
+
+
+def test_text_to_sound_rejects_invalid_output_format():
+    client = ElevenlabsClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid output_format"):
+        client.text_to_sound.create(text="rain", output_format="flac_99")
+
+
+def test_speech_to_text_requires_source_audio_url():
+    client = ElevenlabsClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_audio_url is required"):
+        client.speech_to_text.create()
+
+
+def test_isolate_audio_requires_source_audio_url():
+    client = ElevenlabsClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_audio_url is required"):
+        client.isolate_audio.create()