typecast-python 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

typecast/_voice_clone.py

@@ -0,0 +1,89 @@
+"""Internal helpers for instant cloning (sync/async shared)."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import BinaryIO, Union
+
+CLONING_MAX_FILE_SIZE = 25 * 1024 * 1024  # must match typecast-api `cloning_max_file_size`
+NAME_MIN_LENGTH = 1
+NAME_MAX_LENGTH = 30
+ALLOWED_CLONE_MODELS = frozenset({"ssfm-v21", "ssfm-v30"})
+CUSTOM_VOICE_ID_PREFIX = "uc_"
+
+AudioInput = Union[str, Path, bytes, BinaryIO]
+
+
+def normalize_clone_model(model: object) -> str:
+    """Coerce ``model`` to its string form and reject values outside the API contract.
+
+    Accepts a ``TTSModel`` enum (uses ``.value``) or a string. Raises ``ValueError``
+    when the resolved value is not in :data:`ALLOWED_CLONE_MODELS` so callers fail
+    fast client-side instead of relying on a 422 from the API.
+    """
+    model_str = model.value if hasattr(model, "value") else str(model)
+    if model_str not in ALLOWED_CLONE_MODELS:
+        allowed = ", ".join(sorted(ALLOWED_CLONE_MODELS))
+        raise ValueError(f"model must be one of: {allowed}; got {model_str!r}")
+    return model_str
+
+
+def validate_custom_voice_id(voice_id: str) -> None:
+    """Reject non-custom voice ids before they reach the DELETE endpoint."""
+    if not isinstance(voice_id, str) or not voice_id.startswith(CUSTOM_VOICE_ID_PREFIX):
+        raise ValueError(
+            f"voice_id must start with {CUSTOM_VOICE_ID_PREFIX!r}; got {voice_id!r}"
+        )
+
+
+def validate_clone_inputs(audio: AudioInput, name: str) -> tuple[bytes, str]:
+    """Pre-validate `clone_voice` inputs and return (audio_bytes, filename).
+
+    Args:
+        audio: One of file path (str/Path), raw bytes, or readable binary file object.
+        name: Voice name (1-30 chars).
+
+    Returns:
+        (audio_bytes, filename) — filename is derived from the path/file object,
+        or defaults to "audio.wav" when caller passes raw bytes.
+
+    Raises:
+        ValueError: name length out of range or file too large.
+        FileNotFoundError: path argument refers to a non-existent file.
+        TypeError: audio is none of the accepted types.
+    """
+    if not (NAME_MIN_LENGTH <= len(name) <= NAME_MAX_LENGTH):
+        raise ValueError(
+            f"name must be {NAME_MIN_LENGTH}-{NAME_MAX_LENGTH} characters; got {len(name)}"
+        )
+
+    if isinstance(audio, (str, Path)):
+        path = Path(audio)
+        if not path.exists() or not path.is_file():
+            raise FileNotFoundError(f"audio file not found: {path}")
+        audio_bytes = path.read_bytes()
+        filename = path.name
+    elif isinstance(audio, (bytes, bytearray)):
+        audio_bytes = bytes(audio)
+        filename = "audio.wav"
+    elif hasattr(audio, "read"):
+        audio_bytes = audio.read()
+        if isinstance(audio_bytes, bytearray):
+            audio_bytes = bytes(audio_bytes)
+        if not isinstance(audio_bytes, bytes):
+            raise TypeError(
+                "audio file object must be opened in binary mode and return bytes"
+            )
+        raw_name = getattr(audio, "name", None) or "audio.wav"
+        filename = os.path.basename(str(raw_name).replace("\\", "/"))
+    else:
+        raise TypeError(
+            "audio must be a file path (str/Path), bytes, or readable binary file object"
+        )
+
+    if len(audio_bytes) > CLONING_MAX_FILE_SIZE:
+        raise ValueError(
+            f"audio file exceeds 25MB limit; got {len(audio_bytes)} bytes"
+        )
+
+    return audio_bytes, filename

typecast/async_client.py

@@ -1,8 +1,16 @@
-from typing import AsyncIterator, Optional
+from pathlib import Path
+from typing import AsyncIterator, BinaryIO, Optional, Union
+from urllib.parse import quote
 
 import aiohttp
 
 from . import conf
+from ._voice_clone import (
+    normalize_clone_model,
+    validate_clone_inputs,
+    validate_custom_voice_id,
+)
+from .client import _guess_audio_mime
 from .exceptions import (
     BadRequestError,
     InternalServerError,
@@ -14,7 +22,9 @@ from .exceptions import (
     UnprocessableEntityError,
 )
 from .models import (
+    CustomVoice,
     SubscriptionResponse,
+    TTSModel,
     TTSRequest,
     TTSRequestStream,
     TTSRequestWithTimestamps,
@@ -61,7 +71,9 @@ class AsyncTypecast:
         self.session: Optional[aiohttp.ClientSession] = None
 
     async def __aenter__(self):
-        headers = {"Content-Type": "application/json"}
+        # Auth header at session scope; per-request Content-Type is set by aiohttp
+        # (json= auto-sets application/json, data=FormData() auto-sets multipart).
+        headers = {}
         if self.api_key:
             headers["X-API-KEY"] = self.api_key
         self.session = aiohttp.ClientSession(headers=headers)
@@ -212,6 +224,77 @@ class AsyncTypecast:
             data = await response.json()
         return TTSWithTimestampsResponse.model_validate(data)
 
+    async def clone_voice(
+        self,
+        audio: Union[str, Path, bytes, BinaryIO],
+        name: str,
+        model: Union[str, "TTSModel"],
+    ) -> CustomVoice:
+        """Create a quick-cloned custom voice from an audio sample (async).
+
+        Args:
+            audio: Audio sample. Accepts file path (str/Path), raw bytes,
+                or a readable binary file object. Max 25 MB.
+            name: Voice name, 1-30 characters.
+            model: Engine model. ``"ssfm-v21"`` or ``"ssfm-v30"`` (or ``TTSModel`` enum).
+
+        Returns:
+            ``CustomVoice`` with ``voice_id`` (uc_ prefix), ``name``, and ``model``.
+
+        Raises:
+            ValueError: name length out of range or audio exceeds 25 MB.
+            FileNotFoundError: ``audio`` is a path to a non-existent file.
+            TypecastError: client session not initialized or HTTP error.
+        """
+        if self.session is None:
+            raise TypecastError("Client session not initialized; use 'async with'.")
+
+        audio_bytes, filename = validate_clone_inputs(audio, name)
+        model_str = normalize_clone_model(model)
+
+        form = aiohttp.FormData()
+        form.add_field("name", name)
+        form.add_field("model", model_str)
+        form.add_field(
+            "file",
+            audio_bytes,
+            filename=filename,
+            content_type=_guess_audio_mime(filename),
+        )
+        timeout = aiohttp.ClientTimeout(total=300, connect=10)
+        async with self.session.post(
+            f"{self.host}/v1/voices/clone",
+            data=form,
+            timeout=timeout,
+        ) as response:
+            if response.status != 200:
+                text = await response.text()
+                self._handle_error(response.status, text)
+            body = await response.json()
+            return CustomVoice.model_validate(body)
+
+    async def delete_voice(self, voice_id: str) -> None:
+        """Soft-delete a custom voice (async).
+
+        Args:
+            voice_id: Voice identifier with ``uc_`` prefix.
+
+        Raises:
+            TypecastError subclasses: per HTTP status from the API.
+        """
+        if self.session is None:
+            raise TypecastError("Client session not initialized; use 'async with'.")
+
+        validate_custom_voice_id(voice_id)
+        timeout = aiohttp.ClientTimeout(total=60, connect=10)
+        async with self.session.delete(
+            f"{self.host}/v1/voices/{quote(voice_id, safe='')}",
+            timeout=timeout,
+        ) as response:
+            if response.status not in (200, 204):
+                text = await response.text()
+                self._handle_error(response.status, text)
+
     async def voices(self, model: Optional[str] = None) -> list[VoicesResponse]:
         """Get available voices (V1 API) asynchronously.
 

typecast/client.py

@@ -1,8 +1,15 @@
-from typing import Iterator, Optional
+from pathlib import Path
+from typing import BinaryIO, Iterator, Optional, Union
+from urllib.parse import quote
 
 import requests
 
 from . import conf
+from ._voice_clone import (
+    normalize_clone_model,
+    validate_clone_inputs,
+    validate_custom_voice_id,
+)
 from .exceptions import (
     BadRequestError,
     InternalServerError,
@@ -14,7 +21,9 @@ from .exceptions import (
     UnprocessableEntityError,
 )
 from .models import (
+    CustomVoice,
     SubscriptionResponse,
+    TTSModel,
     TTSRequest,
     TTSRequestStream,
     TTSRequestWithTimestamps,
@@ -26,6 +35,16 @@ from .models import (
 )
 
 
+def _guess_audio_mime(filename: str) -> str:
+    """Guess audio MIME type from filename extension; fall back to octet-stream."""
+    lower = filename.lower()
+    if lower.endswith(".wav"):
+        return "audio/wav"
+    if lower.endswith(".mp3"):
+        return "audio/mpeg"
+    return "application/octet-stream"
+
+
 class Typecast:
     """Synchronous client for the Typecast Text-to-Speech API.
 
@@ -202,6 +221,67 @@ class Typecast:
             self._handle_error(response.status_code, response.text)
         return TTSWithTimestampsResponse.model_validate(response.json())
 
+    def clone_voice(
+        self,
+        audio: Union[str, Path, bytes, BinaryIO],
+        name: str,
+        model: Union[str, "TTSModel"],
+    ) -> CustomVoice:
+        """Create a quick-cloned custom voice from an audio sample.
+
+        Args:
+            audio: Audio sample. Accepts file path (str/Path), raw bytes,
+                or a readable binary file object. Max 25 MB.
+            name: Voice name, 1-30 characters.
+            model: Engine model. ``"ssfm-v21"`` or ``"ssfm-v30"`` (or ``TTSModel`` enum).
+
+        Returns:
+            ``CustomVoice`` with ``voice_id`` (uc_ prefix), ``name``, and ``model``.
+            Use ``voice_id`` directly with ``text_to_speech`` to synthesize.
+
+        Raises:
+            ValueError: name length out of range or audio exceeds 25 MB.
+            FileNotFoundError: ``audio`` is a path to a non-existent file.
+            TypecastError subclasses: per HTTP status from the API.
+        """
+        audio_bytes, filename = validate_clone_inputs(audio, name)
+        model_str = normalize_clone_model(model)
+
+        files = {
+            "file": (filename, audio_bytes, _guess_audio_mime(filename)),
+        }
+        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.
+        response = self.session.post(
+            f"{self.host}/v1/voices/clone",
+            files=files,
+            data=data,
+            headers={"Content-Type": None},
+            timeout=(10, 300),
+        )
+        if response.status_code != 200:
+            self._handle_error(response.status_code, response.text)
+        return CustomVoice.model_validate(response.json())
+
+    def delete_voice(self, voice_id: str) -> None:
+        """Soft-delete a custom voice.
+
+        Args:
+            voice_id: Voice identifier with ``uc_`` prefix (returned by ``clone_voice``).
+
+        Raises:
+            TypecastError subclasses: per HTTP status from the API
+                (e.g., ``NotFoundError`` if the voice doesn't exist or isn't owned).
+        """
+        validate_custom_voice_id(voice_id)
+        response = self.session.delete(
+            f"{self.host}/v1/voices/{quote(voice_id, safe='')}",
+            timeout=(10, 60),
+        )
+        if response.status_code not in (200, 204):
+            self._handle_error(response.status_code, response.text)
+
     def voices(self, model: Optional[str] = None) -> list[VoicesResponse]:
         """Get available voices (V1 API).
 

typecast/models/__init__.py

@@ -20,6 +20,7 @@ from .tts import (
 )
 from .voices import (
     AgeEnum,
+    CustomVoice,
     GenderEnum,
     ModelInfo,
     UseCaseEnum,
@@ -33,6 +34,7 @@ __all__ = [
     "AlignmentSegmentCharacter",
     "AlignmentSegmentWord",
     "Credits",
+    "CustomVoice",
     "EmotionPreset",
     "Error",
     "GenderEnum",

typecast/models/voices.py

@@ -1,7 +1,7 @@
 from enum import Enum
 from typing import Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from .tts import TTSModel
 
@@ -75,3 +75,18 @@ class VoicesV2Filter(BaseModel):
     gender: Optional[GenderEnum] = None
     age: Optional[AgeEnum] = None
     use_cases: Optional[UseCaseEnum] = None
+
+
+class CustomVoice(BaseModel):
+    """Quick-cloned custom voice returned by `POST /v1/voices/clone`.
+
+    Attributes:
+        voice_id: Custom voice identifier with `uc_` prefix.
+            Use this value as `voice_id` in `text_to_speech` / `text_to_speech_with_timestamps`.
+        name: Human-readable name (1-30 chars).
+        model: Engine model the voice was cloned for (`ssfm-v21` or `ssfm-v30`).
+    """
+
+    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")

{typecast_python-0.3.0.dist-info → typecast_python-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typecast-python
-Version: 0.3.0
+Version: 0.3.1
 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
@@ -504,6 +504,53 @@ the two alignment arrays. For non-whitespace languages (Japanese,
 Chinese), pair with `granularity="char"` — word-level alignment will
 collapse the entire sentence into a single segment.
 
+### Instant cloning
+
+Clone a custom voice from a short audio sample (≤ 25 MB), then use it just like any built-in voice. The cloned voice ID has a `uc_` prefix and works with `text_to_speech` directly.
+
+```python
+from typecast import Typecast
+from typecast.models import TTSRequest
+
+client = Typecast(api_key="YOUR_API_KEY")
+
+# 1) Clone
+voice = client.clone_voice(
+    audio="path/to/sample.wav",   # str path | Path | bytes | file object
+    name="my-voice",               # 1-30 chars
+    model="ssfm-v30",              # or "ssfm-v21"
+)
+print(voice.voice_id)              # uc_64a1b2...
+
+# 2) Synthesize with the cloned voice
+audio = client.text_to_speech(TTSRequest(
+    text="Hello from my cloned voice!",
+    voice_id=voice.voice_id,
+    model="ssfm-v30",
+))
+with open("output.wav", "wb") as f:
+    f.write(audio.audio_data)
+
+# 3) Delete when done
+client.delete_voice(voice.voice_id)
+```
+
+**Limits**
+
+- Audio file: max 25 MB. Supported formats: WAV, MP3.
+- Voice name: 1–30 characters.
+- Model: `ssfm-v21` or `ssfm-v30`.
+
+**Async usage** is identical via `AsyncTypecast`:
+
+```python
+from typecast import AsyncTypecast
+
+async with AsyncTypecast(api_key="YOUR_API_KEY") as client:
+    voice = await client.clone_voice(audio="sample.wav", name="my-voice", model="ssfm-v30")
+    await client.delete_voice(voice.voice_id)
+```
+
 ---
 
 ## Supported Languages

typecast_python-0.3.1.dist-info/RECORD

@@ -0,0 +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/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/voices.py,sha256=-EXP35jDy7_G30k5bDnVrFJHp6svEDTA5jJ8oHAgXNQ,2310
+typecast_python-0.3.1.dist-info/METADATA,sha256=pBQbgmi4_SX07Dx5RKO-YPBXMDAPyZwcQXDO3JWoQV4,25529
+typecast_python-0.3.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+typecast_python-0.3.1.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
+typecast_python-0.3.1.dist-info/RECORD,,

typecast_python-0.3.0.dist-info/RECORD

@@ -1,15 +0,0 @@
-typecast/__init__.py,sha256=3pdJqNkXCZ7svzqab4sBR_qwyoM5E2sPjfuci1g1Ub8,1047
-typecast/async_client.py,sha256=vJ6pRVkdKBdiGQHsuMDsRTA9uQPLYucDxNDZBwr1nJk,14231
-typecast/client.py,sha256=0UZnK_OqYJFvd0MSjIogWFmnCVmrXMrfDSom9gih6oM,12261
-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=5XgoOyXO_z78hjpE4dBK-CE6SPhlnb00sFoIb4bW7Ys,1167
-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/voices.py,sha256=VwmK_Ts17QccAaClGYqqstIGJ5RT9Qgj2kxqEoDr6z4,1659
-typecast_python-0.3.0.dist-info/METADATA,sha256=Q156X-kyJJr6qsQ7Sq_JscND1QBBTqcQ8OuTmVbiHOo,24197
-typecast_python-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-typecast_python-0.3.0.dist-info/licenses/LICENSE,sha256=HvtJ-S89uUkuYmt-OvVk4MRxmzwtbn84__qJtSrGU2Q,11348
-typecast_python-0.3.0.dist-info/RECORD,,