typecast-python 0.3.7__tar.gz → 0.3.9__tar.gz

{typecast_python-0.3.7 → typecast_python-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.3.7
+Version: 0.3.9
 Summary: Official Typecast Python SDK - Convert text to lifelike speech using AI-powered voices
 Project-URL: Homepage, https://typecast.ai
 Project-URL: Documentation, https://typecast.ai/docs/overview
@@ -217,26 +217,30 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
-Requires-Dist: aiohttp>=3.14.0
+Requires-Python: <3.15,>=3.8
+Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: requests>=2.28.0
 Requires-Dist: typing-extensions>=4.0.0
 Provides-Extra: dev
 Requires-Dist: aioresponses>=0.7.6; extra == 'dev'
-Requires-Dist: black>=23.0.0; extra == 'dev'
-Requires-Dist: flake8>=6.0.0; extra == 'dev'
+Requires-Dist: black<25.0.0,>=23.0.0; extra == 'dev'
+Requires-Dist: flake8<6.0.0,>=5.0.0; extra == 'dev'
 Requires-Dist: isort>=5.0.0; extra == 'dev'
-Requires-Dist: mypy>=1.0.0; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
-Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: mypy<1.11.0,>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<1.0.0,>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov<6.0.0,>=5.0.0; extra == 'dev'
 Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
-Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: pytest<9.0.0,>=7.0.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -250,7 +254,7 @@ Convert text to lifelike speech using AI-powered voices
 [![PyPI version](https://img.shields.io/pypi/v/typecast-python.svg?style=flat-square)](https://pypi.org/project/typecast-python/)
 [![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg?style=flat-square)](../docs/coverage-policy.md)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square)](LICENSE)
-[![Python](https://img.shields.io/badge/Python-3.9+-3776ab.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
+[![Python](https://img.shields.io/badge/Python-3.8--3.14-3776ab.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
 
 [Documentation](https://typecast.ai/docs) | [API Reference](https://typecast.ai/docs/api-reference) | [Get API Key](https://typecast.ai/developers/api/api-key)
 

{typecast_python-0.3.7 → typecast_python-0.3.9}/README.md

@@ -9,7 +9,7 @@ Convert text to lifelike speech using AI-powered voices
 [![PyPI version](https://img.shields.io/pypi/v/typecast-python.svg?style=flat-square)](https://pypi.org/project/typecast-python/)
 [![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg?style=flat-square)](../docs/coverage-policy.md)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square)](LICENSE)
-[![Python](https://img.shields.io/badge/Python-3.9+-3776ab.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
+[![Python](https://img.shields.io/badge/Python-3.8--3.14-3776ab.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
 
 [Documentation](https://typecast.ai/docs) | [API Reference](https://typecast.ai/docs/api-reference) | [Get API Key](https://typecast.ai/developers/api/api-key)
 

{typecast_python-0.3.7 → typecast_python-0.3.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "typecast-python"
-version = "0.3.7"
+version = "0.3.9"
 description = "Official Typecast Python SDK - Convert text to lifelike speech using AI-powered voices"
 authors = [
     {name = "Neosapience", email = "help@typecast.ai"}
@@ -14,22 +14,26 @@ maintainers = [
 ]
 license = {file = "LICENSE"}
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.8,<3.15"
 keywords = ["typecast", "tts", "text-to-speech", "ai", "voice", "audio", "speech-synthesis", "voice-generation"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Topic :: Multimedia :: Sound/Audio :: Speech",
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "aiohttp>=3.14.0",
+    "aiohttp>=3.9.0",
     "requests>=2.28.0",
     "pydantic>=2.0.0",
     "typing-extensions>=4.0.0",
@@ -37,14 +41,14 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=7.0.0",
-    "pytest-cov>=7.0.0",
+    "pytest>=7.0.0,<9.0.0",
+    "pytest-cov>=5.0.0,<6.0.0",
     "pytest-mock>=3.14.0",
-    "pytest-asyncio>=0.21.0",
+    "pytest-asyncio>=0.21.0,<1.0.0",
     "aioresponses>=0.7.6",
-    "black>=23.0.0",
-    "flake8>=6.0.0",
-    "mypy>=1.0.0",
+    "black>=23.0.0,<25.0.0",
+    "flake8>=5.0.0,<6.0.0",
+    "mypy>=1.0.0,<1.11.0",
     "isort>=5.0.0",
 ]
 
@@ -86,18 +90,21 @@ multi_line_output = 3
 
 [dependency-groups]
 dev = [
-    "pytest>=7.0.0",
-    "pytest-cov>=7.0.0",
+    "pytest>=7.0.0,<9.0.0",
+    "pytest-cov>=5.0.0,<6.0.0",
     "pytest-mock>=3.14.0",
-    "pytest-asyncio>=0.21.0",
+    "pytest-asyncio>=0.21.0,<1.0.0",
     "aioresponses>=0.7.6",
-    "python-dotenv>=1.1.1",
+    "python-dotenv>=1.0.0,<2.0.0",
     "ruff>=0.14.0",
 ]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
+markers = [
+    "e2e: end-to-end tests against the real Typecast API (require credentials)",
+]
 filterwarnings = [
     "ignore::DeprecationWarning",
 ]

{typecast_python-0.3.7 → typecast_python-0.3.9}/src/typecast/__init__.py

@@ -19,6 +19,7 @@ from .models import (
     OutputStream,
     PlanTier,
     Prompt,
+    RecommendedVoice,
     SubscriptionResponse,
     TTSRequest,
     TTSRequestStream,
@@ -48,6 +49,7 @@ __all__ = [
     "OutputStream",
     "PlanTier",
     "Prompt",
+    "RecommendedVoice",
     "SubscriptionResponse",
     "TTSRequest",
     "TTSRequestStream",

{typecast_python-0.3.7 → typecast_python-0.3.9}/src/typecast/async_client.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import asyncio
 from pathlib import Path
 from typing import AsyncIterator, BinaryIO, Optional, Union
@@ -29,6 +31,7 @@ from .models import (
     CustomVoice,
     LanguageCode,
     Output,
+    RecommendedVoice,
     SubscriptionResponse,
     TTSModel,
     TTSPrompt,
@@ -62,34 +65,48 @@ class AsyncTypecast:
         ...         f.write(response.audio_data)
     """
 
-    def __init__(self, host: Optional[str] = None, api_key: Optional[str] = None):
+    def __init__(
+        self,
+        host: Optional[str] = None,
+        api_key: Optional[str] = None,
+        session: Optional[aiohttp.ClientSession] = None,
+    ):
         """Initialize the async Typecast client.
 
         Args:
             host: API host URL. Defaults to TYPECAST_API_HOST env var
                 or 'https://api.typecast.ai'.
             api_key: API key for authentication. Defaults to TYPECAST_API_KEY env var.
+            session: Optional externally-managed aiohttp.ClientSession. When provided,
+                __aenter__ will not create a new session and __aexit__ will not close it
+                (the caller owns its lifecycle). Auth headers (`X-API-KEY`, `User-Agent`)
+                are attached per-request via `_request_headers()`.
 
         Raises:
-            ValueError: If no API key is provided and TYPECAST_API_KEY is not set.
+            ValueError: If no API key is provided and TYPECAST_API_KEY is not set
+                for the default host.
         """
         self.host = conf.get_host(host)
         self.api_key = conf.get_api_key(api_key)
         if not self.api_key and conf.is_default_host(self.host):
             raise ValueError("API key is required for the default Typecast API host")
-        self.session: Optional[aiohttp.ClientSession] = None
+        self._owns_session = session is None
+        self.session: Optional[aiohttp.ClientSession] = session
 
     async def __aenter__(self):
-        # Auth header at session scope; per-request Content-Type is set by aiohttp
-        # (json= auto-sets application/json, data=FormData() auto-sets multipart).
-        headers = {"User-Agent": aiohttp_user_agent(self.host)}
-        if self.api_key:
-            headers["X-API-KEY"] = self.api_key
-        self.session = aiohttp.ClientSession(headers=headers)
+        # When an external session is injected, do not create a new one.
+        # Per-request auth headers are attached via _request_headers() on each call.
+        if self.session is None:
+            headers = {"User-Agent": aiohttp_user_agent(self.host)}
+            if self.api_key:
+                headers["X-API-KEY"] = self.api_key
+            self.session = aiohttp.ClientSession(headers=headers)
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
-        if self.session:
+        # Only close sessions we created. External sessions are caller-owned;
+        # leave the reference intact so the client can be re-entered.
+        if self.session and self._owns_session:
             await self.session.close()
 
     def _handle_error(self, status_code: int, response_text: str):
@@ -114,6 +131,20 @@ class AsyncTypecast:
                 status_code=status_code,
             )
 
+    def _request_headers(self) -> Optional[dict]:
+        """Headers to attach to each individual request.
+
+        For owned sessions, auth is set at session scope, so return None and let
+        aiohttp use the session headers. For external sessions, the session has
+        no auth headers, so we attach X-API-KEY and User-Agent per-request.
+        """
+        if self._owns_session:
+            return None
+        headers = {"User-Agent": aiohttp_user_agent(self.host)}
+        if self.api_key:
+            headers["X-API-KEY"] = self.api_key
+        return headers
+
     async def text_to_speech(self, request: TTSRequest) -> TTSResponse:
         """Convert text to speech asynchronously.
 
@@ -135,7 +166,9 @@ class AsyncTypecast:
             raise TypecastError("Client session not initialized. Use async with.")
         endpoint = "/v1/text-to-speech"
         async with self.session.post(
-            f"{self.host}{endpoint}", json=request.model_dump(exclude_none=True)
+            f"{self.host}{endpoint}",
+            json=request.model_dump(exclude_none=True),
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 error_text = await response.text()
@@ -177,7 +210,8 @@ class AsyncTypecast:
                 seed=seed,
             )
         )
-        await asyncio.to_thread(output_path.write_bytes, response.audio_data)
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, output_path.write_bytes, response.audio_data)
         return response
 
     async def text_to_speech_stream(
@@ -218,12 +252,13 @@ class AsyncTypecast:
             f"{self.host}{endpoint}",
             json=request.model_dump(exclude_none=True),
             timeout=stream_timeout,
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 error_text = await response.text()
                 self._handle_error(response.status, error_text)
 
-            async for chunk in response.content.iter_chunked(chunk_size):
+            async for chunk in response.content.iter_chunked(chunk_size):  # pragma: no branch
                 yield chunk
 
     async def text_to_speech_with_timestamps(
@@ -261,6 +296,7 @@ class AsyncTypecast:
             f"{self.host}{endpoint}",
             json=request.model_dump(exclude_none=True),
             params=params,
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 text = await response.text()
@@ -310,6 +346,7 @@ class AsyncTypecast:
             f"{self.host}/v1/voices/clone",
             data=form,
             timeout=timeout,
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 text = await response.text()
@@ -334,6 +371,7 @@ class AsyncTypecast:
         async with self.session.delete(
             f"{self.host}/v1/voices/{quote(voice_id, safe='')}",
             timeout=timeout,
+            headers=self._request_headers(),
         ) as response:
             if response.status not in (200, 204):
                 text = await response.text()
@@ -360,7 +398,9 @@ class AsyncTypecast:
             params["model"] = model
 
         async with self.session.get(
-            f"{self.host}{endpoint}", params=params
+            f"{self.host}{endpoint}",
+            params=params,
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 error_text = await response.text()
@@ -388,7 +428,9 @@ class AsyncTypecast:
             raise TypecastError("Client session not initialized. Use async with.")
         endpoint = f"/v1/voices/{voice_id}"
 
-        async with self.session.get(f"{self.host}{endpoint}") as response:
+        async with self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        ) as response:
             if response.status != 200:
                 error_text = await response.text()
                 self._handle_error(response.status, error_text)
@@ -425,7 +467,9 @@ class AsyncTypecast:
                 params[key] = getattr(value, "value", value)
 
         async with self.session.get(
-            f"{self.host}{endpoint}", params=params
+            f"{self.host}{endpoint}",
+            params=params,
+            headers=self._request_headers(),
         ) as response:
             if response.status != 200:
                 error_text = await response.text()
@@ -452,7 +496,9 @@ class AsyncTypecast:
         if not self.session:
             raise TypecastError("Client session not initialized. Use async with.")
         endpoint = "/v1/users/me/subscription"
-        async with self.session.get(f"{self.host}{endpoint}") as response:
+        async with self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        ) as response:
             if response.status != 200:
                 error_text = await response.text()
                 self._handle_error(response.status, error_text)
@@ -475,10 +521,37 @@ class AsyncTypecast:
             raise TypecastError("Client session not initialized. Use async with.")
         endpoint = f"/v2/voices/{voice_id}"
 
-        async with self.session.get(f"{self.host}{endpoint}") as response:
+        async with self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        ) as response:
             if response.status != 200:
                 error_text = await response.text()
                 self._handle_error(response.status, error_text)
 
             data = await response.json()
             return VoiceV2Response.model_validate(data)
+
+    async def recommend_voices(
+        self, query: str, count: int = 5
+    ) -> list[RecommendedVoice]:
+        """Recommend voices from a text description.
+
+        Recommendation results only include ``voice_id``, ``voice_name``, and
+        ``score``. Use ``voice_v2`` or ``voices_v2`` to fetch detailed metadata
+        for returned voice IDs.
+        """
+        if count < 1 or count > 10:
+            raise ValueError("count must be between 1 and 10")
+        if not self.session:
+            raise TypecastError("Client session not initialized. Use async with.")
+
+        async with self.session.get(
+            f"{self.host}/v1/voices/recommendations",
+            params={"query": query, "count": count},
+        ) as response:
+            if response.status != 200:
+                error_text = await response.text()
+                self._handle_error(response.status, error_text)
+
+            data = await response.json()
+            return [RecommendedVoice.model_validate(item) for item in data]

{typecast_python-0.3.7 → typecast_python-0.3.9}/src/typecast/client.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from pathlib import Path
 from typing import BinaryIO, Iterator, Optional, Union
 from urllib.parse import quote
@@ -26,6 +28,7 @@ from .models import (
     CustomVoice,
     LanguageCode,
     Output,
+    RecommendedVoice,
     SubscriptionResponse,
     TTSModel,
     TTSPrompt,
@@ -96,13 +99,22 @@ class Typecast:
         ...     f.write(response.audio_data)
     """
 
-    def __init__(self, host: Optional[str] = None, api_key: Optional[str] = None):
+    def __init__(
+        self,
+        host: Optional[str] = None,
+        api_key: Optional[str] = None,
+        session: Optional[requests.Session] = None,
+    ):
         """Initialize the Typecast client.
 
         Args:
             host: API host URL. Defaults to TYPECAST_API_HOST env var
                 or 'https://api.typecast.ai'.
             api_key: API key for authentication. Defaults to TYPECAST_API_KEY env var.
+            session: Optional externally-managed requests.Session. When provided,
+                the client will not create a new session nor close it; auth headers
+                (`X-API-KEY`, `User-Agent`) are attached per-request via
+                `_request_headers()`.
 
         Raises:
             ValueError: If no API key is provided and TYPECAST_API_KEY is not set.
@@ -111,14 +123,18 @@ class Typecast:
         self.api_key = conf.get_api_key(api_key)
         if not self.api_key and conf.is_default_host(self.host):
             raise ValueError("API key is required for the default Typecast API host")
-        self.session = requests.Session()
-        headers = {
-            "Content-Type": "application/json",
-            "User-Agent": requests_user_agent(self.host),
-        }
-        if self.api_key:
-            headers["X-API-KEY"] = self.api_key
-        self.session.headers.update(headers)
+        self._owns_session = session is None
+        if session is not None:
+            self.session = session
+        else:
+            self.session = requests.Session()
+            headers = {
+                "Content-Type": "application/json",
+                "User-Agent": requests_user_agent(self.host),
+            }
+            if self.api_key:
+                headers["X-API-KEY"] = self.api_key
+            self.session.headers.update(headers)
 
     def _handle_error(self, status_code: int, response_text: str):
         """Handle HTTP error responses with specific exception types."""
@@ -142,6 +158,20 @@ class Typecast:
                 status_code=status_code,
             )
 
+    def _request_headers(self) -> Optional[dict]:
+        """Headers to attach to each individual request.
+
+        For owned sessions, auth is set at session scope, so return None and let
+        requests use the session headers. For external sessions, the session has
+        no auth headers, so we attach X-API-KEY and User-Agent per-request.
+        """
+        if self._owns_session:
+            return None
+        headers = {"User-Agent": requests_user_agent(self.host)}
+        if self.api_key:
+            headers["X-API-KEY"] = self.api_key
+        return headers
+
     def text_to_speech(self, request: TTSRequest) -> TTSResponse:
         """Convert text to speech.
 
@@ -160,7 +190,9 @@ class Typecast:
         """
         endpoint = "/v1/text-to-speech"
         response = self.session.post(
-            f"{self.host}{endpoint}", json=request.model_dump(exclude_none=True)
+            f"{self.host}{endpoint}",
+            json=request.model_dump(exclude_none=True),
+            headers=self._request_headers(),
         )
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
@@ -252,6 +284,7 @@ class Typecast:
             json=request.model_dump(exclude_none=True),
             stream=True,
             timeout=(10, 300),
+            headers=self._request_headers(),
         )
         if response.status_code != 200:
             error_text = response.text
@@ -299,6 +332,7 @@ class Typecast:
             json=request.model_dump(exclude_none=True),
             params=params,
             timeout=(10, 300),
+            headers=self._request_headers(),
         )
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
@@ -335,12 +369,19 @@ class Typecast:
         }
         data = {"name": name, "model": model_str}
         # Remove the session-level Content-Type so requests can set the
-        # correct multipart/form-data boundary for this request.
+        # correct multipart/form-data boundary for this request. For external
+        # sessions, also attach the per-request auth headers (X-API-KEY,
+        # User-Agent); _request_headers() returns None for owned sessions, so
+        # owned-session behavior is unchanged.
+        headers = {"Content-Type": None}
+        per_request = self._request_headers()
+        if per_request:
+            headers.update(per_request)
         response = self.session.post(
             f"{self.host}/v1/voices/clone",
             files=files,
             data=data,
-            headers={"Content-Type": None},
+            headers=headers,
             timeout=(10, 300),
         )
         if response.status_code != 200:
@@ -361,6 +402,7 @@ class Typecast:
         response = self.session.delete(
             f"{self.host}/v1/voices/{quote(voice_id, safe='')}",
             timeout=(10, 60),
+            headers=self._request_headers(),
         )
         if response.status_code not in (200, 204):
             self._handle_error(response.status_code, response.text)
@@ -383,7 +425,9 @@ class Typecast:
         if model:
             params["model"] = model
 
-        response = self.session.get(f"{self.host}{endpoint}", params=params)
+        response = self.session.get(
+            f"{self.host}{endpoint}", params=params, headers=self._request_headers()
+        )
 
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
@@ -406,7 +450,9 @@ class Typecast:
             This method is deprecated. Use voices_v2() for enhanced metadata.
         """
         endpoint = f"/v1/voices/{voice_id}"
-        response = self.session.get(f"{self.host}{endpoint}")
+        response = self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        )
 
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
@@ -440,7 +486,9 @@ class Typecast:
             for key, value in filter_dict.items():
                 params[key] = getattr(value, "value", value)
 
-        response = self.session.get(f"{self.host}{endpoint}", params=params)
+        response = self.session.get(
+            f"{self.host}{endpoint}", params=params, headers=self._request_headers()
+        )
 
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
@@ -462,7 +510,9 @@ class Typecast:
             InternalServerError: On server-side failures.
         """
         endpoint = "/v1/users/me/subscription"
-        response = self.session.get(f"{self.host}{endpoint}")
+        response = self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        )
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
         return SubscriptionResponse.model_validate(response.json())
@@ -480,9 +530,33 @@ class Typecast:
             NotFoundError: If the voice ID does not exist.
         """
         endpoint = f"/v2/voices/{voice_id}"
-        response = self.session.get(f"{self.host}{endpoint}")
+        response = self.session.get(
+            f"{self.host}{endpoint}", headers=self._request_headers()
+        )
 
         if response.status_code != 200:
             self._handle_error(response.status_code, response.text)
 
         return VoiceV2Response.model_validate(response.json())
+
+    def recommend_voices(self, query: str, count: int = 5) -> list[RecommendedVoice]:
+        """Recommend voices from a text description.
+
+        Recommendation results only include ``voice_id``, ``voice_name``, and
+        ``score``. Use ``voice_v2`` or ``voices_v2`` to fetch detailed metadata
+        for returned voice IDs.
+
+        Args:
+            query: Text description of the desired voice.
+            count: Number of recommendations to return, from 1 to 10. Defaults to 5.
+        """
+        if count < 1 or count > 10:
+            raise ValueError("count must be between 1 and 10")
+
+        response = self.session.get(
+            f"{self.host}/v1/voices/recommendations",
+            params={"query": query, "count": count},
+        )
+        if response.status_code != 200:
+            self._handle_error(response.status_code, response.text)
+        return [RecommendedVoice.model_validate(item) for item in response.json()]

{typecast_python-0.3.7 → typecast_python-0.3.9}/src/typecast/models/__init__.py

@@ -23,6 +23,7 @@ from .voices import (
     CustomVoice,
     GenderEnum,
     ModelInfo,
+    RecommendedVoice,
     UseCaseEnum,
     VoicesResponse,
     VoicesV2Filter,
@@ -46,6 +47,7 @@ __all__ = [
     "PlanTier",
     "Prompt",
     "PresetPrompt",
+    "RecommendedVoice",
     "SmartPrompt",
     "SubscriptionResponse",
     "TTSModel",

{typecast_python-0.3.7 → typecast_python-0.3.9}/src/typecast/models/tts.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 from enum import Enum
-from typing import Literal, Optional, Union
+from typing import List, Literal, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
@@ -330,7 +332,7 @@ def _group_into_cues(
     word_mode=True: parts are joined with a single space.
     word_mode=False: parts are concatenated directly.
 
-    Returns list[(text, start, end)] tuples.
+    Returns List[(text, start, end)] tuples.
     """
     cues = []
     cur_text_parts = []
@@ -404,11 +406,11 @@ class TTSWithTimestampsResponse(BaseModel):
     audio: str = Field(description="Base64-encoded audio bytes.")
     audio_format: Literal["wav", "mp3"] = Field(description="Audio encoding format.")
     audio_duration: float = Field(description="Length of audio in seconds.")
-    words: Optional[list[AlignmentSegmentWord]] = Field(
+    words: Optional[List[AlignmentSegmentWord]] = Field(
         default=None,
         description="Word-level timestamps; null when granularity=char.",
     )
-    characters: Optional[list[AlignmentSegmentCharacter]] = Field(
+    characters: Optional[List[AlignmentSegmentCharacter]] = Field(
         default=None,
         description="Character-level timestamps; null when granularity=word.",
     )

{typecast_python-0.3.7 → typecast_python-0.3.9}/src/typecast/models/voices.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 from enum import Enum
-from typing import Optional
+from typing import List, Optional
 
 from pydantic import BaseModel, Field
 
@@ -12,7 +14,7 @@ class VoicesResponse(BaseModel):
     voice_id: str
     voice_name: str
     model: str
-    emotions: list[str]
+    emotions: List[str]
 
 
 class GenderEnum(str, Enum):
@@ -54,7 +56,7 @@ class ModelInfo(BaseModel):
     """Model information with supported emotions"""
 
     version: TTSModel
-    emotions: list[str]
+    emotions: List[str]
 
 
 class VoiceV2Response(BaseModel):
@@ -62,10 +64,23 @@ class VoiceV2Response(BaseModel):
 
     voice_id: str
     voice_name: str
-    models: list[ModelInfo]
+    models: List[ModelInfo]
     gender: Optional[GenderEnum] = None
     age: Optional[AgeEnum] = None
-    use_cases: Optional[list[str]] = None
+    use_cases: Optional[List[str]] = None
+
+
+class RecommendedVoice(BaseModel):
+    """Recommended voice result.
+
+    Recommendation results only include the matched voice ID, voice name, and
+    similarity score. Use ``voice_v2`` or ``voices_v2`` to fetch detailed voice
+    metadata for a returned ``voice_id``.
+    """
+
+    voice_id: str
+    voice_name: str
+    score: float
 
 
 class VoicesV2Filter(BaseModel):