typecast-python 0.3.12__tar.gz → 0.3.14__tar.gz

{typecast_python-0.3.12 → typecast_python-0.3.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: typecast-python
-Version: 0.3.12
+Version: 0.3.14
 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.12 → typecast_python-0.3.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "typecast-python"
-version = "0.3.12"
+version = "0.3.14"
 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.12 → typecast_python-0.3.14}/src/typecast/_user_agent.py

@@ -19,10 +19,12 @@ def attribution_suffix(
     if (
         not isinstance(source, str)
         or not isinstance(generated_by, str)
-        or source not in {"llms", "skill"}
+        or source not in {"llms", "skill", "api-page", "api-docs"}
         or not generated_by
     ):
-        raise ValueError("source (llms or skill) and generated_by must be provided together")
+        raise ValueError(
+            "source (llms, skill, api-page, or api-docs) and generated_by must be provided together"
+        )
     if not _GENERATED_BY_PATTERN.fullmatch(generated_by):
         raise ValueError("generated_by must be a lowercase token of at most 32 characters")
     return f" typecast-integration/1 (source={source}; generated_by={generated_by})"

{typecast_python-0.3.12 → typecast_python-0.3.14}/src/typecast/_voice_clone.py

@@ -36,6 +36,12 @@ def validate_custom_voice_id(voice_id: str) -> None:
         )
 
 
+def validate_voice_id(voice_id: str) -> None:
+    """Reject blank voice IDs before constructing a detail URL."""
+    if not isinstance(voice_id, str) or not voice_id.strip():
+        raise ValueError("voice_id must not be blank")
+
+
 def validate_clone_inputs(audio: AudioInput, name: str) -> tuple[bytes, str]:
     """Pre-validate `clone_voice` inputs and return (audio_bytes, filename).
 

{typecast_python-0.3.12 → typecast_python-0.3.14}/src/typecast/async_client.py

@@ -12,18 +12,21 @@ else:  # pragma: no cover
     aiohttp = None  # type: ignore[assignment]
 
 from . import conf
+from ._user_agent import aiohttp_user_agent, attribution_suffix, httpx_user_agent
 from ._voice_clone import (
     normalize_clone_model,
     validate_clone_inputs,
     validate_custom_voice_id,
+    validate_voice_id,
 )
-from ._user_agent import aiohttp_user_agent, attribution_suffix, httpx_user_agent
 
 if TYPE_CHECKING or sys.version_info < (3, 10):  # pragma: no cover
     from ._httpx_compat import AiohttpCompatSession, ClientTimeout, FormData
-from .client import _guess_audio_mime
-from .client import _output_with_inferred_format
-from .client import _validate_output_path
+from .client import (
+    _guess_audio_mime,
+    _output_with_inferred_format,
+    _validate_output_path,
+)
 from .exceptions import (
     BadRequestError,
     InternalServerError,
@@ -50,6 +53,7 @@ from .models import (
     VoicesResponse,
     VoicesV2Filter,
     VoiceV2Response,
+    VoiceV3Response,
 )
 
 
@@ -90,7 +94,7 @@ class AsyncTypecast:
                 __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()`.
-            source: Integration source, either 'llms' or 'skill'.
+            source: Integration source: 'llms', 'skill', 'api-page', or 'api-docs'.
             generated_by: Lowercase token identifying the coding agent.
 
         Raises:
@@ -388,12 +392,12 @@ class AsyncTypecast:
             else ClientTimeout(total=300, connect=10)
         )
         async with self.session.post(
-            f"{self.host}/v1/voices/clone",
+            f"{self.host}/v1/custom-voices/instant-clone",
             data=form,
             timeout=timeout,
             headers=self._request_headers(),
         ) as response:
-            if response.status != 200:
+            if response.status not in (200, 201):
                 text = await response.text()
                 self._handle_error(response.status, text)
             body = await response.json()
@@ -418,7 +422,7 @@ class AsyncTypecast:
             else ClientTimeout(total=60, connect=10)
         )
         async with self.session.delete(
-            f"{self.host}/v1/voices/{quote(voice_id, safe='')}",
+            f"{self.host}/v1/custom-voices/{quote(voice_id, safe='')}",
             timeout=timeout,
             headers=self._request_headers(),
         ) as response:
@@ -426,6 +430,52 @@ class AsyncTypecast:
                 text = await response.text()
                 self._handle_error(response.status, text)
 
+    async def create_professional_voice(
+        self,
+        audio: Union[str, Path, bytes, BinaryIO],
+        name: str,
+        language: Union[str, LanguageCode],
+        model: Union[str, "TTSModel"],
+    ) -> CustomVoice:
+        """Start an asynchronous professional custom-voice clone."""
+        if self.session is None:
+            raise TypecastError("Client session not initialized; use 'async with'.")
+        audio_bytes, filename = validate_clone_inputs(audio, name)
+        form: Any = aiohttp.FormData() if aiohttp else FormData()
+        form.add_field("name", name)
+        form.add_field("language", str(language.value if hasattr(language, "value") else language))
+        form.add_field("model", normalize_clone_model(model))
+        form.add_field("files", audio_bytes, filename=filename, content_type=_guess_audio_mime(filename))
+        timeout = aiohttp.ClientTimeout(total=300, connect=10) if aiohttp else ClientTimeout(total=300, connect=10)
+        async with self.session.post(
+            f"{self.host}/v1/custom-voices/professional-clone",
+            data=form, timeout=timeout, headers=self._request_headers(),
+        ) as response:
+            if response.status != 202:
+                self._handle_error(response.status, await response.text())
+            return CustomVoice.model_validate(await response.json())
+
+    async def get_custom_voices(self) -> list[CustomVoice]:
+        """List custom voices owned by the authenticated user."""
+        if self.session is None:
+            raise TypecastError("Client session not initialized; use 'async with'.")
+        async with self.session.get(f"{self.host}/v1/custom-voices", headers=self._request_headers()) as response:
+            if response.status != 200:
+                self._handle_error(response.status, await response.text())
+            return [CustomVoice.model_validate(item) for item in await response.json()]
+
+    async def get_custom_voice(self, voice_id: str) -> CustomVoice:
+        """Get a custom voice, including professional-clone status."""
+        if self.session is None:
+            raise TypecastError("Client session not initialized; use 'async with'.")
+        validate_custom_voice_id(voice_id)
+        async with self.session.get(
+            f"{self.host}/v1/custom-voices/{quote(voice_id, safe='')}", headers=self._request_headers()
+        ) as response:
+            if response.status != 200:
+                self._handle_error(response.status, await response.text())
+            return CustomVoice.model_validate(await response.json())
+
     async def voices(self, model: Optional[str] = None) -> list[VoicesResponse]:
         """Get available voices (V1 API) asynchronously.
 
@@ -580,6 +630,36 @@ class AsyncTypecast:
             data = await response.json()
             return VoiceV2Response.model_validate(data)
 
+    async def voices_v3(
+        self, filter: Optional[VoicesV2Filter] = None
+    ) -> list[VoiceV3Response]:
+        """Get voices using the current V3 Voice API asynchronously."""
+        if not self.session:
+            raise TypecastError("Client session not initialized. Use async with.")
+        params = {}
+        if filter:
+            for key, value in filter.model_dump(exclude_none=True).items():
+                params[key] = getattr(value, "value", value)
+        async with self.session.get(
+            f"{self.host}/v3/voices", params=params, headers=self._request_headers()
+        ) as response:
+            if response.status != 200:
+                self._handle_error(response.status, await response.text())
+            return [VoiceV3Response.model_validate(item) for item in await response.json()]
+
+    async def voice_v3(self, voice_id: str) -> VoiceV3Response:
+        """Get a voice by ID using the current V3 Voice API asynchronously."""
+        validate_voice_id(voice_id)
+        if not self.session:
+            raise TypecastError("Client session not initialized. Use async with.")
+        async with self.session.get(
+            f"{self.host}/v3/voices/{quote(voice_id, safe='')}",
+            headers=self._request_headers(),
+        ) as response:
+            if response.status != 200:
+                self._handle_error(response.status, await response.text())
+            return VoiceV3Response.model_validate(await response.json())
+
     async def recommend_voices(
         self, query: str, count: int = 5
     ) -> list[RecommendedVoice]:

{typecast_python-0.3.12 → typecast_python-0.3.14}/src/typecast/client.py

@@ -11,12 +11,13 @@ else:  # pragma: no cover
     requests = None  # type: ignore[assignment]
 
 from . import conf
+from ._user_agent import attribution_suffix, httpx_user_agent, requests_user_agent
 from ._voice_clone import (
     normalize_clone_model,
     validate_clone_inputs,
     validate_custom_voice_id,
+    validate_voice_id,
 )
-from ._user_agent import attribution_suffix, httpx_user_agent, requests_user_agent
 
 if TYPE_CHECKING or sys.version_info < (3, 10):  # pragma: no cover
     from ._httpx_compat import RequestsCompatSession
@@ -47,6 +48,7 @@ from .models import (
     VoicesResponse,
     VoicesV2Filter,
     VoiceV2Response,
+    VoiceV3Response,
 )
 
 
@@ -124,7 +126,7 @@ class Typecast:
                 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()`.
-            source: Integration source, either 'llms' or 'skill'.
+            source: Integration source: 'llms', 'skill', 'api-page', or 'api-docs'.
             generated_by: Lowercase token identifying the coding agent.
 
         Raises:
@@ -418,13 +420,13 @@ class Typecast:
         if per_request:
             headers.update(per_request)
         response = self.session.post(
-            f"{self.host}/v1/voices/clone",
+            f"{self.host}/v1/custom-voices/instant-clone",
             files=files,
             data=data,
             headers=headers,
             timeout=(10, 300),
         )
-        if response.status_code != 200:
+        if response.status_code not in (200, 201):
             self._handle_error(response.status_code, response.text)
         return CustomVoice.model_validate(response.json())
 
@@ -440,13 +442,58 @@ class Typecast:
         """
         validate_custom_voice_id(voice_id)
         response = self.session.delete(
-            f"{self.host}/v1/voices/{quote(voice_id, safe='')}",
+            f"{self.host}/v1/custom-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)
 
+    def create_professional_voice(
+        self,
+        audio: Union[str, Path, bytes, BinaryIO],
+        name: str,
+        language: Union[str, LanguageCode],
+        model: Union[str, "TTSModel"],
+    ) -> CustomVoice:
+        """Start an asynchronous professional custom-voice clone.
+
+        Poll :meth:`get_custom_voice` until the returned status is
+        ``"completed"`` or ``"failed"``.
+        """
+        audio_bytes, filename = validate_clone_inputs(audio, name)
+        model_str = normalize_clone_model(model)
+        response = self.session.post(
+            f"{self.host}/v1/custom-voices/professional-clone",
+            files={"files": (filename, audio_bytes, _guess_audio_mime(filename))},
+            data={"name": name, "language": str(language.value if hasattr(language, "value") else language), "model": model_str},
+            headers={"Content-Type": None, **(self._request_headers() or {})},
+            timeout=(10, 300),
+        )
+        if response.status_code != 202:
+            self._handle_error(response.status_code, response.text)
+        return CustomVoice.model_validate(response.json())
+
+    def get_custom_voices(self) -> list[CustomVoice]:
+        """List custom voices owned by the authenticated user."""
+        response = self.session.get(
+            f"{self.host}/v1/custom-voices", headers=self._request_headers()
+        )
+        if response.status_code != 200:
+            self._handle_error(response.status_code, response.text)
+        return [CustomVoice.model_validate(item) for item in response.json()]
+
+    def get_custom_voice(self, voice_id: str) -> CustomVoice:
+        """Get a custom voice, including professional-clone status."""
+        validate_custom_voice_id(voice_id)
+        response = self.session.get(
+            f"{self.host}/v1/custom-voices/{quote(voice_id, safe='')}",
+            headers=self._request_headers(),
+        )
+        if response.status_code != 200:
+            self._handle_error(response.status_code, response.text)
+        return CustomVoice.model_validate(response.json())
+
     def voices(self, model: Optional[str] = None) -> list[VoicesResponse]:
         """Get available voices (V1 API).
 
@@ -579,6 +626,32 @@ class Typecast:
 
         return VoiceV2Response.model_validate(response.json())
 
+    def voices_v3(
+        self, filter: Optional[VoicesV2Filter] = None
+    ) -> list[VoiceV3Response]:
+        """Get voices using the current V3 Voice API."""
+        params = {}
+        if filter:
+            for key, value in filter.model_dump(exclude_none=True).items():
+                params[key] = getattr(value, "value", value)
+        response = self.session.get(
+            f"{self.host}/v3/voices", params=params, headers=self._request_headers()
+        )
+        if response.status_code != 200:
+            self._handle_error(response.status_code, response.text)
+        return [VoiceV3Response.model_validate(item) for item in response.json()]
+
+    def voice_v3(self, voice_id: str) -> VoiceV3Response:
+        """Get a voice by ID using the current V3 Voice API."""
+        validate_voice_id(voice_id)
+        response = self.session.get(
+            f"{self.host}/v3/voices/{quote(voice_id, safe='')}",
+            headers=self._request_headers(),
+        )
+        if response.status_code != 200:
+            self._handle_error(response.status_code, response.text)
+        return VoiceV3Response.model_validate(response.json())
+
     def recommend_voices(self, query: str, count: int = 5) -> list[RecommendedVoice]:
         """Recommend voices from a text description.
 

{typecast_python-0.3.12 → typecast_python-0.3.14}/src/typecast/models/__init__.py

@@ -22,12 +22,14 @@ from .voices import (
     AgeEnum,
     CustomVoice,
     GenderEnum,
+    LocalizedVoiceName,
     ModelInfo,
     RecommendedVoice,
     UseCaseEnum,
     VoicesResponse,
     VoicesV2Filter,
     VoiceV2Response,
+    VoiceV3Response,
 )
 
 __all__ = [
@@ -40,6 +42,7 @@ __all__ = [
     "Error",
     "GenderEnum",
     "LanguageCode",
+    "LocalizedVoiceName",
     "Limits",
     "ModelInfo",
     "Output",
@@ -59,6 +62,7 @@ __all__ = [
     "TTSWithTimestampsResponse",
     "UseCaseEnum",
     "VoiceV2Response",
+    "VoiceV3Response",
     "VoicesResponse",
     "VoicesV2Filter",
 ]

{typecast_python-0.3.12 → typecast_python-0.3.14}/src/typecast/models/subscription.py

@@ -25,6 +25,11 @@ class Limits(BaseModel):
     concurrency_limit: int = Field(
         description="Maximum number of concurrent requests allowed"
     )
+    custom_voice_slot: int = Field(
+        default=0,
+        ge=0,
+        description="Maximum active custom voices allowed by the current plan",
+    )
 
 
 class SubscriptionResponse(BaseModel):

{typecast_python-0.3.12 → typecast_python-0.3.14}/src/typecast/models/voices.py

@@ -70,6 +70,26 @@ class VoiceV2Response(BaseModel):
     use_cases: Optional[List[str]] = None
 
 
+class LocalizedVoiceName(BaseModel):
+    """English and Korean display names returned by the V3 Voice API."""
+
+    eng: str
+    kor: str
+
+
+class VoiceV3Response(BaseModel):
+    """V3 Voice response with localized name and preview metadata."""
+
+    voice_id: str
+    voice_name: LocalizedVoiceName
+    models: List[ModelInfo]
+    voice_type: str
+    gender: Optional[GenderEnum] = None
+    age: Optional[AgeEnum] = None
+    use_cases: Optional[List[str]] = None
+    preview_url: Optional[str] = None
+
+
 class RecommendedVoice(BaseModel):
     """Recommended voice result.
 
@@ -93,7 +113,7 @@ class VoicesV2Filter(BaseModel):
 
 
 class CustomVoice(BaseModel):
-    """Quick-cloned custom voice returned by `POST /v1/voices/clone`.
+    """Custom voice returned by the Custom Voice API.
 
     Attributes:
         voice_id: Custom voice identifier with `uc_` prefix.
@@ -105,3 +125,7 @@ class CustomVoice(BaseModel):
     voice_id: str = Field(..., description="Custom voice identifier (uc_ prefix)")
     name: str = Field(..., description="Human-readable voice name")
     model: str = Field(..., description="Engine model: ssfm-v21 or ssfm-v30")
+    source: Optional[str] = Field(default=None, description="instant or professional")
+    status: Optional[str] = Field(default=None, description="Cloning status")
+    error: Optional[str] = Field(default=None, description="Safe failure reason when status is failed")
+    created_at: Optional[str] = Field(default=None, description="UTC creation timestamp")