typecast-python 0.1.8__py3-none-any.whl → 0.2.0__py3-none-any.whl

typecast/__init__.py

@@ -11,14 +11,19 @@ from .exceptions import (
     UnprocessableEntityError,
 )
 from .models import (
+    Credits,
     Error,
     LanguageCode,
+    Limits,
     Output,
+    OutputStream,
+    PlanTier,
     Prompt,
+    SubscriptionResponse,
     TTSRequest,
+    TTSRequestStream,
     TTSResponse,
     VoicesResponse,
-    WebSocketMessage,
 )
 
 __all__ = [
@@ -35,12 +40,17 @@ __all__ = [
     "UnauthorizedError",
     "UnprocessableEntityError",
     # Models
+    "Credits",
     "Error",
     "LanguageCode",
+    "Limits",
     "Output",
+    "OutputStream",
+    "PlanTier",
     "Prompt",
+    "SubscriptionResponse",
     "TTSRequest",
+    "TTSRequestStream",
     "TTSResponse",
     "VoicesResponse",
-    "WebSocketMessage",
 ]

typecast/async_client.py

@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import AsyncIterator, Optional
 
 import aiohttp
 
@@ -13,7 +13,15 @@ from .exceptions import (
     UnauthorizedError,
     UnprocessableEntityError,
 )
-from .models import TTSRequest, TTSResponse, VoicesResponse, VoiceV2Response, VoicesV2Filter
+from .models import (
+    SubscriptionResponse,
+    TTSRequest,
+    TTSRequestStream,
+    TTSResponse,
+    VoicesResponse,
+    VoicesV2Filter,
+    VoiceV2Response,
+)
 
 
 class AsyncTypecast:
@@ -117,6 +125,49 @@ class AsyncTypecast:
                 format=response.headers.get("Content-Type", "audio/wav").split("/")[-1],
             )
 
+    async def text_to_speech_stream(
+        self, request: TTSRequestStream, chunk_size: int = 8192
+    ) -> AsyncIterator[bytes]:
+        """Stream synthesized audio from `POST /v1/text-to-speech/stream`.
+
+        Async generator that yields audio chunks as the server emits them.
+        For WAV the first chunk contains the WAV header (declared with size
+        0xFFFFFFFF for streaming) followed by PCM data; subsequent chunks are
+        PCM only. For MP3 each chunk contains independently-decodable frames.
+
+        Args:
+            request: Streaming TTS request. Uses `OutputStream`, which omits
+                `volume` and `target_lufs` (not supported by the streaming
+                endpoint).
+            chunk_size: Maximum bytes returned per yielded chunk.
+
+        Yields:
+            Audio chunk bytes in the order produced by the server.
+
+        Raises:
+            TypecastError: If the client session is not initialized.
+            BadRequestError, UnauthorizedError, PaymentRequiredError,
+            NotFoundError, UnprocessableEntityError, RateLimitError,
+            InternalServerError, TypecastError: depending on response status.
+        """
+        if not isinstance(chunk_size, int) or isinstance(chunk_size, bool) or chunk_size < 1:
+            raise ValueError("chunk_size must be a positive integer")
+        if not self.session:
+            raise TypecastError("Client session not initialized. Use async with.")
+        endpoint = "/v1/text-to-speech/stream"
+        stream_timeout = aiohttp.ClientTimeout(sock_connect=10, sock_read=300)
+        async with self.session.post(
+            f"{self.host}{endpoint}",
+            json=request.model_dump(exclude_none=True),
+            timeout=stream_timeout,
+        ) 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):
+                yield chunk
+
     async def voices(self, model: Optional[str] = None) -> list[VoicesResponse]:
         """Get available voices (V1 API) asynchronously.
 
@@ -196,12 +247,11 @@ class AsyncTypecast:
         params = {}
         if filter:
             filter_dict = filter.model_dump(exclude_none=True)
-            # Convert enum values to strings
+            # Convert enum values to their underlying str representation.
+            # Every VoicesV2Filter field is an Optional[Enum], so getattr
+            # falls back only if a future non-enum field is added.
             for key, value in filter_dict.items():
-                if hasattr(value, "value"):
-                    params[key] = value.value
-                else:
-                    params[key] = value
+                params[key] = getattr(value, "value", value)
 
         async with self.session.get(
             f"{self.host}{endpoint}", params=params
@@ -213,6 +263,31 @@ class AsyncTypecast:
             data = await response.json()
             return [VoiceV2Response.model_validate(item) for item in data]
 
+    async def get_my_subscription(self) -> SubscriptionResponse:
+        """Get the authenticated user's current subscription asynchronously.
+
+        Returns plan tier, credit usage, and concurrency limits. Use this to
+        check remaining credits or verify your plan before making TTS calls.
+
+        Returns:
+            SubscriptionResponse with plan, credits, and limits.
+
+        Raises:
+            TypecastError: If the client session is not initialized.
+            UnauthorizedError: If the API key is invalid.
+            RateLimitError: If the rate limit was exceeded.
+            InternalServerError: On server-side failures.
+        """
+        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:
+            if response.status != 200:
+                error_text = await response.text()
+                self._handle_error(response.status, error_text)
+            data = await response.json()
+            return SubscriptionResponse.model_validate(data)
+
     async def voice_v2(self, voice_id: str) -> VoiceV2Response:
         """Get a specific voice by ID with enhanced metadata (V2 API)
 

typecast/client.py

@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import Iterator, Optional
 
 import requests
 
@@ -13,7 +13,15 @@ from .exceptions import (
     UnauthorizedError,
     UnprocessableEntityError,
 )
-from .models import TTSRequest, TTSResponse, VoicesResponse, VoiceV2Response, VoicesV2Filter
+from .models import (
+    SubscriptionResponse,
+    TTSRequest,
+    TTSRequestStream,
+    TTSResponse,
+    VoicesResponse,
+    VoicesV2Filter,
+    VoiceV2Response,
+)
 
 
 class Typecast:
@@ -104,6 +112,55 @@ class Typecast:
             format=response.headers.get("Content-Type", "audio/wav").split("/")[-1],
         )
 
+    def text_to_speech_stream(
+        self, request: TTSRequestStream, chunk_size: int = 8192
+    ) -> Iterator[bytes]:
+        """Stream synthesized audio from `POST /v1/text-to-speech/stream`.
+
+        Yields raw audio chunks as the server produces them. For WAV the
+        first chunk contains the WAV header (declared with size 0xFFFFFFFF
+        for streaming) followed by PCM data; subsequent chunks are PCM only.
+        For MP3 each chunk contains independently-decodable MP3 frames.
+
+        The HTTP response is held open until the iterator is exhausted or
+        garbage-collected, so callers should consume the iterator promptly
+        (e.g. inside a `for` loop or by writing chunks to disk).
+
+        Args:
+            request: Streaming TTS request. Uses `OutputStream`, which omits
+                `volume` and `target_lufs` (not supported by the streaming
+                endpoint).
+            chunk_size: Maximum bytes returned per yielded chunk.
+
+        Yields:
+            Audio chunk bytes in the order produced by the server.
+
+        Raises:
+            BadRequestError, UnauthorizedError, PaymentRequiredError,
+            NotFoundError, UnprocessableEntityError, RateLimitError,
+            InternalServerError, TypecastError: depending on response status.
+        """
+        if not isinstance(chunk_size, int) or isinstance(chunk_size, bool) or chunk_size < 1:
+            raise ValueError("chunk_size must be a positive integer")
+        endpoint = "/v1/text-to-speech/stream"
+        response = self.session.post(
+            f"{self.host}{endpoint}",
+            json=request.model_dump(exclude_none=True),
+            stream=True,
+            timeout=(10, 300),
+        )
+        if response.status_code != 200:
+            error_text = response.text
+            response.close()
+            self._handle_error(response.status_code, error_text)
+
+        try:
+            for chunk in response.iter_content(chunk_size=chunk_size):
+                if chunk:
+                    yield chunk
+        finally:
+            response.close()
+
     def voices(self, model: Optional[str] = None) -> list[VoicesResponse]:
         """Get available voices (V1 API).
 
@@ -173,12 +230,11 @@ class Typecast:
         params = {}
         if filter:
             filter_dict = filter.model_dump(exclude_none=True)
-            # Convert enum values to strings
+            # Convert enum values to their underlying str representation.
+            # Every VoicesV2Filter field is an Optional[Enum], so getattr
+            # falls back only if a future non-enum field is added.
             for key, value in filter_dict.items():
-                if hasattr(value, "value"):
-                    params[key] = value.value
-                else:
-                    params[key] = value
+                params[key] = getattr(value, "value", value)
 
         response = self.session.get(f"{self.host}{endpoint}", params=params)
 
@@ -187,6 +243,26 @@ class Typecast:
 
         return [VoiceV2Response.model_validate(item) for item in response.json()]
 
+    def get_my_subscription(self) -> SubscriptionResponse:
+        """Get the authenticated user's current subscription.
+
+        Returns plan tier, credit usage, and concurrency limits. Use this to
+        check remaining credits or verify your plan before making TTS calls.
+
+        Returns:
+            SubscriptionResponse with plan, credits, and limits.
+
+        Raises:
+            UnauthorizedError: If the API key is invalid.
+            RateLimitError: If the rate limit was exceeded.
+            InternalServerError: On server-side failures.
+        """
+        endpoint = "/v1/users/me/subscription"
+        response = self.session.get(f"{self.host}{endpoint}")
+        if response.status_code != 200:
+            self._handle_error(response.status_code, response.text)
+        return SubscriptionResponse.model_validate(response.json())
+
     def voice_v2(self, voice_id: str) -> VoiceV2Response:
         """Get a specific voice by ID with enhanced metadata (V2 API)
 

typecast/models/__init__.py

@@ -1,17 +1,19 @@
 from .error import Error
+from .subscription import Credits, Limits, PlanTier, SubscriptionResponse
 from .tts import (
     EmotionPreset,
     LanguageCode,
     Output,
+    OutputStream,
     PresetPrompt,
     Prompt,
     SmartPrompt,
     TTSModel,
     TTSPrompt,
     TTSRequest,
+    TTSRequestStream,
     TTSResponse,
 )
-from .tts_wss import WebSocketMessage
 from .voices import (
     AgeEnum,
     GenderEnum,
@@ -24,6 +26,7 @@ from .voices import (
 
 __all__ = [
     "TTSRequest",
+    "TTSRequestStream",
     "TTSModel",
     "TTSPrompt",
     "Prompt",
@@ -31,6 +34,7 @@ __all__ = [
     "SmartPrompt",
     "EmotionPreset",
     "Output",
+    "OutputStream",
     "TTSResponse",
     "VoicesResponse",
     "VoiceV2Response",
@@ -40,6 +44,9 @@ __all__ = [
     "AgeEnum",
     "UseCaseEnum",
     "Error",
-    "WebSocketMessage",
     "LanguageCode",
+    "PlanTier",
+    "Credits",
+    "Limits",
+    "SubscriptionResponse",
 ]

typecast/models/subscription.py

@@ -0,0 +1,35 @@
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class PlanTier(str, Enum):
+    """Subscription plan tier."""
+
+    FREE = "free"
+    LITE = "lite"
+    PLUS = "plus"
+    CUSTOM = "custom"
+
+
+class Credits(BaseModel):
+    """Credit usage information."""
+
+    plan_credits: int = Field(description="Total credits provided by the plan")
+    used_credits: int = Field(description="Number of credits used")
+
+
+class Limits(BaseModel):
+    """Usage limit information."""
+
+    concurrency_limit: int = Field(
+        description="Maximum number of concurrent requests allowed"
+    )
+
+
+class SubscriptionResponse(BaseModel):
+    """Response from `GET /v1/users/me/subscription`."""
+
+    plan: PlanTier = Field(description="Current subscription plan tier")
+    credits: Credits = Field(description="Credit usage information")
+    limits: Limits = Field(description="Usage limit information")

typecast/models/tts.py

@@ -174,3 +174,41 @@ class TTSResponse(BaseModel):
     audio_data: bytes
     duration: float
     format: str = "wav"
+
+
+class OutputStream(BaseModel):
+    """Audio output settings for streaming mode.
+
+    Streaming mode does not support `volume` or `target_lufs` because the
+    server has to commit each chunk before the full waveform is known.
+    Passing either field raises a validation error so misuse fails fast.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    audio_pitch: Optional[int] = Field(default=0, ge=-12, le=12)
+    audio_tempo: Optional[float] = Field(default=1.0, ge=0.5, le=2.0)
+    audio_format: Optional[str] = Field(
+        default="wav", description="Audio format", examples=["wav", "mp3"]
+    )
+
+
+class TTSRequestStream(BaseModel):
+    """Request body for `POST /v1/text-to-speech/stream`.
+
+    Mirrors `TTSRequest` but uses `OutputStream` (no volume / target_lufs).
+    """
+
+    model_config = ConfigDict(json_schema_extra={"exclude_none": True})
+
+    voice_id: str = Field(
+        description="Voice ID", examples=["tc_62a8975e695ad26f7fb514d1"]
+    )
+    text: str = Field(description="Text", examples=["Hello. How are you?"])
+    model: TTSModel = Field(description="Voice model name", examples=["ssfm-v21"])
+    language: Optional[Union[LanguageCode, str]] = Field(
+        None, description="Language code (ISO 639-3)", examples=["eng"]
+    )
+    prompt: Optional[TTSPrompt] = None
+    output: Optional[OutputStream] = None
+    seed: Optional[int] = None

{typecast_python-0.1.8.dist-info → typecast_python-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.1.8
+Version: 0.2.0
 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
@@ -226,15 +226,15 @@ Requires-Python: >=3.11
 Requires-Dist: aiohttp>=3.8.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: requests>=2.28.0
-Requires-Dist: sseclient-py>=1.7.2
 Requires-Dist: typing-extensions>=4.0.0
-Requires-Dist: websockets>=10.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: 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: pytest-mock>=3.14.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -248,6 +248,7 @@ Description-Content-Type: text/markdown
 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/)
 

typecast_python-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+typecast/__init__.py,sha256=3pdJqNkXCZ7svzqab4sBR_qwyoM5E2sPjfuci1g1Ub8,1047
+typecast/async_client.py,sha256=NJY2CWuCD3CVcqHuNwezIk39X8YTnkpQeJGdfhv6bqw,12341
+typecast/client.py,sha256=HzCSGDglsCz880x8lXesHFXQIcivc7KXImWiXehWvQc,10514
+typecast/conf.py,sha256=Fn_T4XW7BaHRnj0tP11BT5at3Y-db7oGcbBA_E1fmF0,479
+typecast/exceptions.py,sha256=Y0ZzYebe8zOSOSAHbXfKR0G_RJgdmZXxi15Z7ZxPLIk,1568
+typecast/utils.py,sha256=XuNuX7gW8_CGKqZ-cv_tKlPVMPBluAYJBw2clwmjIMI,708
+typecast/models/__init__.py,sha256=uvDWzZPo01mjHreUtlHBMYiuZ84Tb02LzU3ZpszYg1I,923
+typecast/models/error.py,sha256=XomIjx7jvlCjItqzJuCAT4mXC9jwTjxR8lLDUk6P8KA,152
+typecast/models/subscription.py,sha256=EIaAAo3cCRw8LYT_O6D9AVwxqIHrWCijzl4UTx7FZB8,894
+typecast/models/tts.py,sha256=clwrqky7CtcKjGtLY1h1hnyn2MXXJjXEaZ8iVZXK85c,6739
+typecast/models/voices.py,sha256=VwmK_Ts17QccAaClGYqqstIGJ5RT9Qgj2kxqEoDr6z4,1659
+typecast_python-0.2.0.dist-info/METADATA,sha256=ske3xiM-FStIUYiyDP3k7rYLU538pbTm35pyhll5y3w,22881
+typecast_python-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+typecast_python-0.2.0.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
+typecast_python-0.2.0.dist-info/RECORD,,

typecast/models/tts_wss.py

@@ -1,7 +0,0 @@
-
-from pydantic import BaseModel
-
-
-class WebSocketMessage(BaseModel):
-    type: str
-    payload: dict

typecast/sse.py

@@ -1,35 +0,0 @@
-from typing import AsyncIterator, Optional
-
-import aiohttp
-
-from . import conf
-from .exceptions import TypecastError
-
-
-class TypecastSSE:
-    SSE_URL = f"{conf.get_host()}/v1/text-to-speech/sse"
-
-    def __init__(self, api_key: str):
-        self.api_key = conf.get_api_key(api_key)
-        self.session: Optional[aiohttp.ClientSession] = None
-
-    async def connect(self, endpoint: str) -> AsyncIterator[str]:
-        if self.session:
-            await self.session.close()
-
-        self.session = aiohttp.ClientSession(
-            headers={"X-API-KEY": self.api_key, "Accept": "text/event-stream"}
-        )
-
-        async with self.session.get(f"{self.SSE_URL}/{endpoint}") as response:
-            if response.status != 200:
-                raise TypecastError(f"SSE connection failed: {response.status}")
-
-            async for line in response.content:
-                decoded_line = line.decode("utf-8").strip()
-                if decoded_line.startswith("data: "):
-                    yield decoded_line[6:]
-
-    async def close(self):
-        if self.session:
-            await self.session.close()

typecast/websocket.py

@@ -1,47 +0,0 @@
-import asyncio
-import json
-from typing import Callable, Optional
-
-import websockets
-
-from .exceptions import TypecastError
-from .models import WebSocketMessage
-
-
-class TypecastWebSocket:
-    WS_URL = "wss://api.typecast.ai/v1/ws"
-
-    def __init__(self, api_key: str):
-        self.api_key = api_key
-        self.ws: Optional[websockets.WebSocketClientProtocol] = None
-        self.callbacks: dict[str, Callable] = {}
-
-    async def connect(self):
-        self.ws = await websockets.connect(f"{self.WS_URL}?token={self.api_key}")
-
-        # Start message handler
-        asyncio.create_task(self._message_handler())
-
-    async def _message_handler(self):
-        if not self.ws:
-            return
-
-        async for message in self.ws:
-            data = json.loads(message)
-            msg = WebSocketMessage(**data)
-
-            if msg.type in self.callbacks:
-                await self.callbacks[msg.type](msg.payload)
-
-    def on(self, event_type: str, callback: Callable):
-        """Register event callback"""
-        self.callbacks[event_type] = callback
-
-    async def send(self, message: WebSocketMessage):
-        if not self.ws:
-            raise TypecastError("WebSocket not connected")
-        await self.ws.send(message.model_dump_json())
-
-    async def close(self):
-        if self.ws:
-            await self.ws.close()

typecast_python-0.1.8.dist-info/RECORD

@@ -1,17 +0,0 @@
-typecast/__init__.py,sha256=8xdL3GnADTIsi2KuqPY938opQtN6GbHWnJI0XwjqHPc,871
-typecast/async_client.py,sha256=_v-YHussPMAG4az8XnWdXwb6uh5gcXAhWcpW1Scuf0o,9004
-typecast/client.py,sha256=Kj_IqZ_RgDGaPTylsUsYAQfRO_1PG7NZdEuc8nZ0a4A,7431
-typecast/conf.py,sha256=Fn_T4XW7BaHRnj0tP11BT5at3Y-db7oGcbBA_E1fmF0,479
-typecast/exceptions.py,sha256=Y0ZzYebe8zOSOSAHbXfKR0G_RJgdmZXxi15Z7ZxPLIk,1568
-typecast/sse.py,sha256=yYO2h5E_1-uiIID0TZM03eRZfvgkCStxu-0J6ej4Bpo,1109
-typecast/utils.py,sha256=XuNuX7gW8_CGKqZ-cv_tKlPVMPBluAYJBw2clwmjIMI,708
-typecast/websocket.py,sha256=SwFmk2efGtMLY3UgEtZljZAhULl5HG6KaA-rqfJ0Jaw,1336
-typecast/models/__init__.py,sha256=sF_0YSHXOPebNpNi_RiYAy-GnoG1D7ugHskszQYDsxk,754
-typecast/models/error.py,sha256=XomIjx7jvlCjItqzJuCAT4mXC9jwTjxR8lLDUk6P8KA,152
-typecast/models/tts.py,sha256=51TeFsiCZMzhMWdvP6Q6bKm4KCMjk0OyLPahOPig-yk,5358
-typecast/models/tts_wss.py,sha256=zYfP3oNs5VuOkxI7bu0uSCHDYfSbQWaenqg0lLLqaSc,101
-typecast/models/voices.py,sha256=VwmK_Ts17QccAaClGYqqstIGJ5RT9Qgj2kxqEoDr6z4,1659
-typecast_python-0.1.8.dist-info/METADATA,sha256=MEpG51YSCui99kpJQlUOdoRIBd7Ao6auv58Ybmtj2I0,22726
-typecast_python-0.1.8.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-typecast_python-0.1.8.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
-typecast_python-0.1.8.dist-info/RECORD,,