typecast-python 0.3.2__tar.gz → 0.3.4__tar.gz

{typecast_python-0.3.2 → typecast_python-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.3.2
+Version: 0.3.4
 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

{typecast_python-0.3.2 → typecast_python-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "typecast-python"
-version = "0.3.2"
+version = "0.3.4"
 description = "Official Typecast Python SDK - Convert text to lifelike speech using AI-powered voices"
 authors = [
     {name = "Neosapience", email = "help@typecast.ai"}

{typecast_python-0.3.2 → typecast_python-0.3.4}/src/typecast/async_client.py

@@ -1,3 +1,4 @@
+import asyncio
 from pathlib import Path
 from typing import AsyncIterator, BinaryIO, Optional, Union
 from urllib.parse import quote
@@ -11,6 +12,8 @@ from ._voice_clone import (
     validate_custom_voice_id,
 )
 from .client import _guess_audio_mime
+from .client import _output_with_inferred_format
+from .client import _validate_output_path
 from .exceptions import (
     BadRequestError,
     InternalServerError,
@@ -23,8 +26,11 @@ from .exceptions import (
 )
 from .models import (
     CustomVoice,
+    LanguageCode,
+    Output,
     SubscriptionResponse,
     TTSModel,
+    TTSPrompt,
     TTSRequest,
     TTSRequestStream,
     TTSRequestWithTimestamps,
@@ -68,6 +74,8 @@ class AsyncTypecast:
         """
         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
 
     async def __aenter__(self):
@@ -139,6 +147,38 @@ class AsyncTypecast:
                 format=response.headers.get("Content-Type", "audio/wav").split("/")[-1],
             )
 
+    async def generate_to_file(
+        self,
+        path: Union[str, Path],
+        *,
+        text: str,
+        voice_id: str,
+        model: TTSModel = TTSModel.SSFM_V30,
+        language: Optional[Union[LanguageCode, str]] = None,
+        prompt: Optional[TTSPrompt] = None,
+        output: Optional[Output] = None,
+        seed: Optional[int] = None,
+    ) -> TTSResponse:
+        """Convert text to speech and write the audio bytes to a file.
+
+        Browse available API voices at
+        ``https://typecast.ai/developers/api/voices``.
+        """
+        output_path = _validate_output_path(path)
+        response = await self.text_to_speech(
+            TTSRequest(
+                text=text,
+                voice_id=voice_id,
+                model=model,
+                language=language,
+                prompt=prompt,
+                output=_output_with_inferred_format(output, path),
+                seed=seed,
+            )
+        )
+        await asyncio.to_thread(output_path.write_bytes, response.audio_data)
+        return response
+
     async def text_to_speech_stream(
         self, request: TTSRequestStream, chunk_size: int = 8192
     ) -> AsyncIterator[bytes]:

{typecast_python-0.3.2 → typecast_python-0.3.4}/src/typecast/client.py

@@ -22,8 +22,11 @@ from .exceptions import (
 )
 from .models import (
     CustomVoice,
+    LanguageCode,
+    Output,
     SubscriptionResponse,
     TTSModel,
+    TTSPrompt,
     TTSRequest,
     TTSRequestStream,
     TTSRequestWithTimestamps,
@@ -35,6 +38,33 @@ from .models import (
 )
 
 
+def _infer_audio_format_from_path(path: Union[str, Path]) -> Optional[str]:
+    suffix = Path(path).suffix.lower()
+    if suffix == ".mp3":
+        return "mp3"
+    if suffix == ".wav":
+        return "wav"
+    return None
+
+
+def _output_with_inferred_format(
+    output: Optional[Output],
+    path: Union[str, Path],
+) -> Optional[Output]:
+    audio_format = _infer_audio_format_from_path(path)
+    if audio_format is None or (output is not None and output.audio_format is not None):
+        return output
+    if output is None:
+        return Output(audio_format=audio_format)
+    return output.model_copy(update={"audio_format": audio_format})
+
+
+def _validate_output_path(path: Union[str, Path]) -> Path:
+    if isinstance(path, str) and not path.strip():
+        raise ValueError("path cannot be empty")
+    return Path(path)
+
+
 def _guess_audio_mime(filename: str) -> str:
     """Guess audio MIME type from filename extension; fall back to octet-stream."""
     lower = filename.lower()
@@ -77,10 +107,13 @@ class Typecast:
         """
         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 = requests.Session()
-        self.session.headers.update(
-            {"X-API-KEY": self.api_key, "Content-Type": "application/json"}
-        )
+        headers = {"Content-Type": "application/json"}
+        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."""
@@ -133,6 +166,40 @@ class Typecast:
             format=response.headers.get("Content-Type", "audio/wav").split("/")[-1],
         )
 
+    def generate_to_file(
+        self,
+        path: Union[str, Path],
+        *,
+        text: str,
+        voice_id: str,
+        model: TTSModel = TTSModel.SSFM_V30,
+        language: Optional[Union[LanguageCode, str]] = None,
+        prompt: Optional[TTSPrompt] = None,
+        output: Optional[Output] = None,
+        seed: Optional[int] = None,
+    ) -> TTSResponse:
+        """Convert text to speech and write the audio bytes to a file.
+
+        ``model`` defaults to ``ssfm-v30``. If ``output.audio_format`` is not
+        set, the format is inferred from a ``.mp3`` or ``.wav`` extension.
+        Browse available API voices at
+        ``https://typecast.ai/developers/api/voices``.
+        """
+        output_path = _validate_output_path(path)
+        response = self.text_to_speech(
+            TTSRequest(
+                text=text,
+                voice_id=voice_id,
+                model=model,
+                language=language,
+                prompt=prompt,
+                output=_output_with_inferred_format(output, path),
+                seed=seed,
+            )
+        )
+        output_path.write_bytes(response.audio_data)
+        return response
+
     def text_to_speech_stream(
         self, request: TTSRequestStream, chunk_size: int = 8192
     ) -> Iterator[bytes]:

typecast_python-0.3.4/src/typecast/conf.py

@@ -0,0 +1,25 @@
+import os
+
+TYPECAST_API_HOST = "https://api.typecast.ai"
+
+
+def get_host(host=None):
+    if host:  # Parameter takes priority
+        return normalize_host(host)
+    env_host = os.getenv("TYPECAST_API_HOST")  # Check environment variable
+    return normalize_host(env_host) if env_host else TYPECAST_API_HOST  # Use default if not set
+
+
+def get_api_key(api_key=None):
+    if api_key:  # Parameter takes priority
+        return api_key.strip()
+    env_key = os.getenv("TYPECAST_API_KEY")  # Return from environment variable
+    return env_key.strip() if env_key else None
+
+
+def normalize_host(host):
+    return host.strip().rstrip("/")
+
+
+def is_default_host(host):
+    return normalize_host(host).lower() == TYPECAST_API_HOST

{typecast_python-0.3.2 → typecast_python-0.3.4}/src/typecast/models/tts.py

@@ -158,7 +158,11 @@ class TTSRequest(BaseModel):
     model_config = ConfigDict(json_schema_extra={"exclude_none": True})
 
     voice_id: str = Field(
-        description="Voice ID", examples=["tc_62a8975e695ad26f7fb514d1"]
+        description=(
+            "Voice ID. Browse available API voices at "
+            "https://typecast.ai/developers/api/voices."
+        ),
+        examples=["tc_62a8975e695ad26f7fb514d1"],
     )
     text: str = Field(description="Text", examples=["Hello. How are you?"])
     model: TTSModel = Field(description="Voice model name", examples=["ssfm-v21"])
@@ -202,7 +206,11 @@ class TTSRequestStream(BaseModel):
     model_config = ConfigDict(json_schema_extra={"exclude_none": True})
 
     voice_id: str = Field(
-        description="Voice ID", examples=["tc_62a8975e695ad26f7fb514d1"]
+        description=(
+            "Voice ID. Browse available API voices at "
+            "https://typecast.ai/developers/api/voices."
+        ),
+        examples=["tc_62a8975e695ad26f7fb514d1"],
     )
     text: str = Field(description="Text", examples=["Hello. How are you?"])
     model: TTSModel = Field(description="Voice model name", examples=["ssfm-v21"])
@@ -253,7 +261,11 @@ class TTSRequestWithTimestamps(BaseModel):
     model_config = ConfigDict(json_schema_extra={"exclude_none": True})
 
     voice_id: str = Field(
-        description="Voice ID", examples=["tc_62a8975e695ad26f7fb514d1"]
+        description=(
+            "Voice ID. Browse available API voices at "
+            "https://typecast.ai/developers/api/voices."
+        ),
+        examples=["tc_62a8975e695ad26f7fb514d1"],
     )
     text: str = Field(description="Text", examples=["Hello. How are you?"])
     model: TTSModel = Field(description="Voice model name", examples=["ssfm-v30"])

typecast_python-0.3.2/src/typecast/conf.py

@@ -1,16 +0,0 @@
-import os
-
-TYPECAST_API_HOST = "https://api.typecast.ai"
-
-
-def get_host(host=None):
-    if host:  # Parameter takes priority
-        return host
-    env_host = os.getenv("TYPECAST_API_HOST")  # Check environment variable
-    return env_host if env_host else TYPECAST_API_HOST  # Use default if not set
-
-
-def get_api_key(api_key=None):
-    if api_key:  # Parameter takes priority
-        return api_key
-    return os.getenv("TYPECAST_API_KEY")  # Return from environment variable