typecast-python 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

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/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/conf.py

@@ -5,12 +5,21 @@ TYPECAST_API_HOST = "https://api.typecast.ai"
 
 def get_host(host=None):
     if host:  # Parameter takes priority
-        return host
+        return normalize_host(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
+    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
-    return os.getenv("TYPECAST_API_KEY")  # Return from environment variable
+        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/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.dist-info → typecast_python-0.3.4.dist-info}/METADATA

@@ -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.dist-info → typecast_python-0.3.4.dist-info}/RECORD

@@ -1,16 +1,16 @@
 typecast/__init__.py,sha256=3pdJqNkXCZ7svzqab4sBR_qwyoM5E2sPjfuci1g1Ub8,1047
 typecast/_voice_clone.py,sha256=TN2tbB3b5lC5uFCBnbERhz37bNJlbv6VZ-vj70EfTs4,3464
-typecast/async_client.py,sha256=8mab1ai_P1TdQilR1l29n5Cg40F7lN960shODemXXWs,17287
-typecast/client.py,sha256=PRFF7hj8Ih88dRl0ZiLcRRD8N4ofPPbYMZAKpk_b89w,15212
-typecast/conf.py,sha256=Fn_T4XW7BaHRnj0tP11BT5at3Y-db7oGcbBA_E1fmF0,479
+typecast/async_client.py,sha256=5Tz6j2waj4XHgHhoaxM__W3YcJxUS7r8Wc3RkZA-LBc,18645
+typecast/client.py,sha256=oMjYK6NEYivY5ICSst-ZKH13ORnbzfGGlC_ZLhxk_PM,17461
+typecast/conf.py,sha256=yfOHYZDvIshWWMriN5wE0GFPR8AX3zv4Rg2655OvA9Q,724
 typecast/exceptions.py,sha256=Y0ZzYebe8zOSOSAHbXfKR0G_RJgdmZXxi15Z7ZxPLIk,1568
 typecast/utils.py,sha256=XuNuX7gW8_CGKqZ-cv_tKlPVMPBluAYJBw2clwmjIMI,708
 typecast/models/__init__.py,sha256=UEPUjg86fpCMXUvAzcNgxSPPhuPwCY9aQbzK3w90Fj0,1203
 typecast/models/error.py,sha256=XomIjx7jvlCjItqzJuCAT4mXC9jwTjxR8lLDUk6P8KA,152
 typecast/models/subscription.py,sha256=EIaAAo3cCRw8LYT_O6D9AVwxqIHrWCijzl4UTx7FZB8,894
-typecast/models/tts.py,sha256=IDz4IN2d4MCkATB_rVlaEoMS7EgWlQsW0tIP8k67LHo,16001
+typecast/models/tts.py,sha256=uZ8QEevpAnRF-W4_hoEx4EA1WP1TN0ZJIak1OYE1ThQ,16370
 typecast/models/voices.py,sha256=-EXP35jDy7_G30k5bDnVrFJHp6svEDTA5jJ8oHAgXNQ,2310
-typecast_python-0.3.2.dist-info/METADATA,sha256=juL719j6AgB5jgCHsCTNQ-4eKi3tKQnCuQZb0d42qXo,25530
-typecast_python-0.3.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-typecast_python-0.3.2.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
-typecast_python-0.3.2.dist-info/RECORD,,
+typecast_python-0.3.4.dist-info/METADATA,sha256=TS2HvMhG4jAK_Y7r_dQK2Kiun3gz696PXUsuGDWZgyA,25530
+typecast_python-0.3.4.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+typecast_python-0.3.4.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
+typecast_python-0.3.4.dist-info/RECORD,,