cartesia 1.4.0__py3-none-any.whl → 2.0.0a0__py3-none-any.whl

cartesia/tts/client.py

@@ -0,0 +1,407 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+from ..core.client_wrapper import SyncClientWrapper
+from .requests.tts_request_voice_specifier import TtsRequestVoiceSpecifierParams
+from .requests.output_format import OutputFormatParams
+from .types.supported_language import SupportedLanguage
+from ..core.request_options import RequestOptions
+from ..core.serialization import convert_and_respect_annotation_metadata
+from json.decoder import JSONDecodeError
+from ..core.api_error import ApiError
+from .types.web_socket_response import WebSocketResponse
+import httpx_sse
+from ..core.pydantic_utilities import parse_obj_as
+import json
+from ..core.client_wrapper import AsyncClientWrapper
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class TtsClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    def bytes(
+        self,
+        *,
+        model_id: str,
+        transcript: str,
+        voice: TtsRequestVoiceSpecifierParams,
+        output_format: OutputFormatParams,
+        language: typing.Optional[SupportedLanguage] = OMIT,
+        duration: typing.Optional[float] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> typing.Iterator[bytes]:
+        """
+        Parameters
+        ----------
+        model_id : str
+            The ID of the model to use for the generation. See [Models](/build-with-sonic/models) for available models.
+
+        transcript : str
+
+        voice : TtsRequestVoiceSpecifierParams
+
+        output_format : OutputFormatParams
+
+        language : typing.Optional[SupportedLanguage]
+
+        duration : typing.Optional[float]
+            The maximum duration of the audio in seconds. You do not usually need to specify this.
+            If the duration is not appropriate for the length of the transcript, the output audio may be truncated.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration. You can pass in configuration such as `chunk_size`, and more to customize the request and response.
+
+        Yields
+        ------
+        typing.Iterator[bytes]
+
+        Examples
+        --------
+        from cartesia import Cartesia
+
+        client = Cartesia(
+            api_key="YOUR_API_KEY",
+        )
+        client.tts.bytes(
+            model_id="sonic-english",
+            transcript="Hello, world!",
+            voice={"mode": "id", "id": "694f9389-aac1-45b6-b726-9d9369183238"},
+            language="en",
+            output_format={
+                "sample_rate": 44100,
+                "bit_rate": 128000,
+                "container": "mp3",
+            },
+        )
+        """
+        with self._client_wrapper.httpx_client.stream(
+            "tts/bytes",
+            method="POST",
+            json={
+                "model_id": model_id,
+                "transcript": transcript,
+                "voice": convert_and_respect_annotation_metadata(
+                    object_=voice, annotation=TtsRequestVoiceSpecifierParams, direction="write"
+                ),
+                "language": language,
+                "output_format": convert_and_respect_annotation_metadata(
+                    object_=output_format, annotation=OutputFormatParams, direction="write"
+                ),
+                "duration": duration,
+            },
+            request_options=request_options,
+            omit=OMIT,
+        ) as _response:
+            try:
+                if 200 <= _response.status_code < 300:
+                    _chunk_size = request_options.get("chunk_size", None) if request_options is not None else None
+                    for _chunk in _response.iter_bytes(chunk_size=_chunk_size):
+                        yield _chunk
+                    return
+                _response.read()
+                _response_json = _response.json()
+            except JSONDecodeError:
+                raise ApiError(status_code=_response.status_code, body=_response.text)
+            raise ApiError(status_code=_response.status_code, body=_response_json)
+
+    def sse(
+        self,
+        *,
+        model_id: str,
+        transcript: str,
+        voice: TtsRequestVoiceSpecifierParams,
+        output_format: OutputFormatParams,
+        language: typing.Optional[SupportedLanguage] = OMIT,
+        duration: typing.Optional[float] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> typing.Iterator[WebSocketResponse]:
+        """
+        Parameters
+        ----------
+        model_id : str
+            The ID of the model to use for the generation. See [Models](/build-with-sonic/models) for available models.
+
+        transcript : str
+
+        voice : TtsRequestVoiceSpecifierParams
+
+        output_format : OutputFormatParams
+
+        language : typing.Optional[SupportedLanguage]
+
+        duration : typing.Optional[float]
+            The maximum duration of the audio in seconds. You do not usually need to specify this.
+            If the duration is not appropriate for the length of the transcript, the output audio may be truncated.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Yields
+        ------
+        typing.Iterator[WebSocketResponse]
+
+        Examples
+        --------
+        from cartesia import Cartesia
+
+        client = Cartesia(
+            api_key="YOUR_API_KEY",
+        )
+        response = client.tts.sse(
+            model_id="sonic-english",
+            transcript="Hello, world!",
+            voice={"mode": "id", "id": "694f9389-aac1-45b6-b726-9d9369183238"},
+            language="en",
+            output_format={
+                "sample_rate": 44100,
+                "encoding": "pcm_f32le",
+                "container": "raw",
+            },
+        )
+        for chunk in response:
+            yield chunk
+        """
+        with self._client_wrapper.httpx_client.stream(
+            "tts/sse",
+            method="POST",
+            json={
+                "model_id": model_id,
+                "transcript": transcript,
+                "voice": convert_and_respect_annotation_metadata(
+                    object_=voice, annotation=TtsRequestVoiceSpecifierParams, direction="write"
+                ),
+                "language": language,
+                "output_format": convert_and_respect_annotation_metadata(
+                    object_=output_format, annotation=OutputFormatParams, direction="write"
+                ),
+                "duration": duration,
+            },
+            request_options=request_options,
+            omit=OMIT,
+        ) as _response:
+            try:
+                if 200 <= _response.status_code < 300:
+                    _event_source = httpx_sse.EventSource(_response)
+                    for _sse in _event_source.iter_sse():
+                        try:
+                            yield typing.cast(
+                                WebSocketResponse,
+                                parse_obj_as(
+                                    type_=WebSocketResponse,  # type: ignore
+                                    object_=json.loads(_sse.data),
+                                ),
+                            )
+                        except:
+                            pass
+                    return
+                _response.read()
+                _response_json = _response.json()
+            except JSONDecodeError:
+                raise ApiError(status_code=_response.status_code, body=_response.text)
+            raise ApiError(status_code=_response.status_code, body=_response_json)
+
+
+class AsyncTtsClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    async def bytes(
+        self,
+        *,
+        model_id: str,
+        transcript: str,
+        voice: TtsRequestVoiceSpecifierParams,
+        output_format: OutputFormatParams,
+        language: typing.Optional[SupportedLanguage] = OMIT,
+        duration: typing.Optional[float] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> typing.AsyncIterator[bytes]:
+        """
+        Parameters
+        ----------
+        model_id : str
+            The ID of the model to use for the generation. See [Models](/build-with-sonic/models) for available models.
+
+        transcript : str
+
+        voice : TtsRequestVoiceSpecifierParams
+
+        output_format : OutputFormatParams
+
+        language : typing.Optional[SupportedLanguage]
+
+        duration : typing.Optional[float]
+            The maximum duration of the audio in seconds. You do not usually need to specify this.
+            If the duration is not appropriate for the length of the transcript, the output audio may be truncated.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration. You can pass in configuration such as `chunk_size`, and more to customize the request and response.
+
+        Yields
+        ------
+        typing.AsyncIterator[bytes]
+
+        Examples
+        --------
+        import asyncio
+
+        from cartesia import AsyncCartesia
+
+        client = AsyncCartesia(
+            api_key="YOUR_API_KEY",
+        )
+
+
+        async def main() -> None:
+            await client.tts.bytes(
+                model_id="sonic-english",
+                transcript="Hello, world!",
+                voice={"mode": "id", "id": "694f9389-aac1-45b6-b726-9d9369183238"},
+                language="en",
+                output_format={
+                    "sample_rate": 44100,
+                    "bit_rate": 128000,
+                    "container": "mp3",
+                },
+            )
+
+
+        asyncio.run(main())
+        """
+        async with self._client_wrapper.httpx_client.stream(
+            "tts/bytes",
+            method="POST",
+            json={
+                "model_id": model_id,
+                "transcript": transcript,
+                "voice": convert_and_respect_annotation_metadata(
+                    object_=voice, annotation=TtsRequestVoiceSpecifierParams, direction="write"
+                ),
+                "language": language,
+                "output_format": convert_and_respect_annotation_metadata(
+                    object_=output_format, annotation=OutputFormatParams, direction="write"
+                ),
+                "duration": duration,
+            },
+            request_options=request_options,
+            omit=OMIT,
+        ) as _response:
+            try:
+                if 200 <= _response.status_code < 300:
+                    _chunk_size = request_options.get("chunk_size", None) if request_options is not None else None
+                    async for _chunk in _response.aiter_bytes(chunk_size=_chunk_size):
+                        yield _chunk
+                    return
+                await _response.aread()
+                _response_json = _response.json()
+            except JSONDecodeError:
+                raise ApiError(status_code=_response.status_code, body=_response.text)
+            raise ApiError(status_code=_response.status_code, body=_response_json)
+
+    async def sse(
+        self,
+        *,
+        model_id: str,
+        transcript: str,
+        voice: TtsRequestVoiceSpecifierParams,
+        output_format: OutputFormatParams,
+        language: typing.Optional[SupportedLanguage] = OMIT,
+        duration: typing.Optional[float] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> typing.AsyncIterator[WebSocketResponse]:
+        """
+        Parameters
+        ----------
+        model_id : str
+            The ID of the model to use for the generation. See [Models](/build-with-sonic/models) for available models.
+
+        transcript : str
+
+        voice : TtsRequestVoiceSpecifierParams
+
+        output_format : OutputFormatParams
+
+        language : typing.Optional[SupportedLanguage]
+
+        duration : typing.Optional[float]
+            The maximum duration of the audio in seconds. You do not usually need to specify this.
+            If the duration is not appropriate for the length of the transcript, the output audio may be truncated.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Yields
+        ------
+        typing.AsyncIterator[WebSocketResponse]
+
+        Examples
+        --------
+        import asyncio
+
+        from cartesia import AsyncCartesia
+
+        client = AsyncCartesia(
+            api_key="YOUR_API_KEY",
+        )
+
+
+        async def main() -> None:
+            response = await client.tts.sse(
+                model_id="sonic-english",
+                transcript="Hello, world!",
+                voice={"mode": "id", "id": "694f9389-aac1-45b6-b726-9d9369183238"},
+                language="en",
+                output_format={
+                    "sample_rate": 44100,
+                    "encoding": "pcm_f32le",
+                    "container": "raw",
+                },
+            )
+            async for chunk in response:
+                yield chunk
+
+
+        asyncio.run(main())
+        """
+        async with self._client_wrapper.httpx_client.stream(
+            "tts/sse",
+            method="POST",
+            json={
+                "model_id": model_id,
+                "transcript": transcript,
+                "voice": convert_and_respect_annotation_metadata(
+                    object_=voice, annotation=TtsRequestVoiceSpecifierParams, direction="write"
+                ),
+                "language": language,
+                "output_format": convert_and_respect_annotation_metadata(
+                    object_=output_format, annotation=OutputFormatParams, direction="write"
+                ),
+                "duration": duration,
+            },
+            request_options=request_options,
+            omit=OMIT,
+        ) as _response:
+            try:
+                if 200 <= _response.status_code < 300:
+                    _event_source = httpx_sse.EventSource(_response)
+                    async for _sse in _event_source.aiter_sse():
+                        try:
+                            yield typing.cast(
+                                WebSocketResponse,
+                                parse_obj_as(
+                                    type_=WebSocketResponse,  # type: ignore
+                                    object_=json.loads(_sse.data),
+                                ),
+                            )
+                        except:
+                            pass
+                    return
+                await _response.aread()
+                _response_json = _response.json()
+            except JSONDecodeError:
+                raise ApiError(status_code=_response.status_code, body=_response.text)
+            raise ApiError(status_code=_response.status_code, body=_response_json)

cartesia/tts/requests/__init__.py

@@ -0,0 +1,76 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from .cancel_context_request import CancelContextRequestParams
+from .controls import ControlsParams
+from .generation_request import GenerationRequestParams
+from .mp_3_output_format import Mp3OutputFormatParams
+from .output_format import OutputFormatParams, OutputFormat_Mp3Params, OutputFormat_RawParams, OutputFormat_WavParams
+from .phoneme_timestamps import PhonemeTimestampsParams
+from .raw_output_format import RawOutputFormatParams
+from .speed import SpeedParams
+from .tts_request import TtsRequestParams
+from .tts_request_embedding_specifier import TtsRequestEmbeddingSpecifierParams
+from .tts_request_id_specifier import TtsRequestIdSpecifierParams
+from .tts_request_voice_specifier import TtsRequestVoiceSpecifierParams
+from .wav_output_format import WavOutputFormatParams
+from .web_socket_base_response import WebSocketBaseResponseParams
+from .web_socket_chunk_response import WebSocketChunkResponseParams
+from .web_socket_done_response import WebSocketDoneResponseParams
+from .web_socket_error_response import WebSocketErrorResponseParams
+from .web_socket_flush_done_response import WebSocketFlushDoneResponseParams
+from .web_socket_phoneme_timestamps_response import WebSocketPhonemeTimestampsResponseParams
+from .web_socket_raw_output_format import WebSocketRawOutputFormatParams
+from .web_socket_request import WebSocketRequestParams
+from .web_socket_response import (
+    WebSocketResponseParams,
+    WebSocketResponse_ChunkParams,
+    WebSocketResponse_DoneParams,
+    WebSocketResponse_ErrorParams,
+    WebSocketResponse_FlushDoneParams,
+    WebSocketResponse_PhonemeTimestampsParams,
+    WebSocketResponse_TimestampsParams,
+)
+from .web_socket_stream_options import WebSocketStreamOptionsParams
+from .web_socket_timestamps_response import WebSocketTimestampsResponseParams
+from .web_socket_tts_output import WebSocketTtsOutputParams
+from .web_socket_tts_request import WebSocketTtsRequestParams
+from .word_timestamps import WordTimestampsParams
+
+__all__ = [
+    "CancelContextRequestParams",
+    "ControlsParams",
+    "GenerationRequestParams",
+    "Mp3OutputFormatParams",
+    "OutputFormatParams",
+    "OutputFormat_Mp3Params",
+    "OutputFormat_RawParams",
+    "OutputFormat_WavParams",
+    "PhonemeTimestampsParams",
+    "RawOutputFormatParams",
+    "SpeedParams",
+    "TtsRequestEmbeddingSpecifierParams",
+    "TtsRequestIdSpecifierParams",
+    "TtsRequestParams",
+    "TtsRequestVoiceSpecifierParams",
+    "WavOutputFormatParams",
+    "WebSocketBaseResponseParams",
+    "WebSocketChunkResponseParams",
+    "WebSocketDoneResponseParams",
+    "WebSocketErrorResponseParams",
+    "WebSocketFlushDoneResponseParams",
+    "WebSocketPhonemeTimestampsResponseParams",
+    "WebSocketRawOutputFormatParams",
+    "WebSocketRequestParams",
+    "WebSocketResponseParams",
+    "WebSocketResponse_ChunkParams",
+    "WebSocketResponse_DoneParams",
+    "WebSocketResponse_ErrorParams",
+    "WebSocketResponse_FlushDoneParams",
+    "WebSocketResponse_PhonemeTimestampsParams",
+    "WebSocketResponse_TimestampsParams",
+    "WebSocketStreamOptionsParams",
+    "WebSocketTimestampsResponseParams",
+    "WebSocketTtsOutputParams",
+    "WebSocketTtsRequestParams",
+    "WordTimestampsParams",
+]

cartesia/tts/requests/cancel_context_request.py

@@ -0,0 +1,17 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+from ..types.context_id import ContextId
+import typing
+
+
+class CancelContextRequestParams(typing_extensions.TypedDict):
+    context_id: ContextId
+    """
+    The ID of the context to cancel.
+    """
+
+    cancel: typing.Literal[True]
+    """
+    Whether to cancel the context, so that no more messages are generated for that context.
+    """

cartesia/tts/requests/controls.py

@@ -0,0 +1,11 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+from .speed import SpeedParams
+import typing
+from ..types.emotion import Emotion
+
+
+class ControlsParams(typing_extensions.TypedDict):
+    speed: SpeedParams
+    emotion: typing.Sequence[Emotion]

cartesia/tts/requests/generation_request.py

@@ -0,0 +1,53 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+import typing
+from .tts_request_voice_specifier import TtsRequestVoiceSpecifierParams
+import typing_extensions
+from ..types.supported_language import SupportedLanguage
+from .web_socket_raw_output_format import WebSocketRawOutputFormatParams
+from ..types.context_id import ContextId
+from ...core.serialization import FieldMetadata
+
+
+class GenerationRequestParams(typing_extensions.TypedDict):
+    model_id: str
+    """
+    The ID of the model to use for the generation. See [Models](/build-with-sonic/models) for available models.
+    """
+
+    transcript: typing.Optional[typing.Any]
+    """
+    The transcript to generate speech for. This can be a string or an iterator over strings.
+    """
+
+    voice: TtsRequestVoiceSpecifierParams
+    language: typing_extensions.NotRequired[SupportedLanguage]
+    output_format: WebSocketRawOutputFormatParams
+    duration: typing_extensions.NotRequired[float]
+    """
+    The maximum duration of the audio in seconds. You do not usually need to specify this.
+    If the duration is not appropriate for the length of the transcript, the output audio may be truncated.
+    """
+
+    context_id: typing_extensions.NotRequired[ContextId]
+    continue_: typing_extensions.NotRequired[typing_extensions.Annotated[bool, FieldMetadata(alias="continue")]]
+    """
+    Whether this input may be followed by more inputs.
+    If not specified, this defaults to `false`.
+    """
+
+    flush: typing_extensions.NotRequired[bool]
+    """
+    Whether to flush the context.
+    """
+
+    add_timestamps: typing_extensions.NotRequired[bool]
+    """
+    Whether to return word-level timestamps.
+    """
+
+    add_phoneme_timestamps: typing_extensions.NotRequired[bool]
+    """
+    Whether to return phoneme-level timestamps.
+    """

cartesia/tts/requests/mp_3_output_format.py

@@ -0,0 +1,11 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+
+
+class Mp3OutputFormatParams(typing_extensions.TypedDict):
+    sample_rate: int
+    bit_rate: int
+    """
+    The bit rate of the audio in bits per second. Supported bit rates are 32000, 64000, 96000, 128000, 192000.
+    """

cartesia/tts/requests/output_format.py

@@ -0,0 +1,30 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from __future__ import annotations
+import typing_extensions
+import typing
+from ..types.raw_encoding import RawEncoding
+import typing_extensions
+
+
+class OutputFormat_RawParams(typing_extensions.TypedDict):
+    container: typing.Literal["raw"]
+    encoding: RawEncoding
+    sample_rate: int
+    bit_rate: typing_extensions.NotRequired[int]
+
+
+class OutputFormat_WavParams(typing_extensions.TypedDict):
+    container: typing.Literal["wav"]
+    encoding: RawEncoding
+    sample_rate: int
+    bit_rate: typing_extensions.NotRequired[int]
+
+
+class OutputFormat_Mp3Params(typing_extensions.TypedDict):
+    container: typing.Literal["mp3"]
+    sample_rate: int
+    bit_rate: int
+
+
+OutputFormatParams = typing.Union[OutputFormat_RawParams, OutputFormat_WavParams, OutputFormat_Mp3Params]

cartesia/tts/requests/phoneme_timestamps.py

@@ -0,0 +1,10 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+import typing
+
+
+class PhonemeTimestampsParams(typing_extensions.TypedDict):
+    phonemes: typing.Sequence[str]
+    start: typing.Sequence[float]
+    end: typing.Sequence[float]

cartesia/tts/requests/raw_output_format.py

@@ -0,0 +1,11 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+from ..types.raw_encoding import RawEncoding
+import typing_extensions
+
+
+class RawOutputFormatParams(typing_extensions.TypedDict):
+    encoding: RawEncoding
+    sample_rate: int
+    bit_rate: typing_extensions.NotRequired[int]

cartesia/tts/requests/speed.py

@@ -0,0 +1,7 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+from ..types.numerical_specifier import NumericalSpecifier
+from ..types.natural_specifier import NaturalSpecifier
+
+SpeedParams = typing.Union[NumericalSpecifier, NaturalSpecifier]

cartesia/tts/requests/tts_request.py

@@ -0,0 +1,24 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+from .tts_request_voice_specifier import TtsRequestVoiceSpecifierParams
+import typing_extensions
+from ..types.supported_language import SupportedLanguage
+from .output_format import OutputFormatParams
+
+
+class TtsRequestParams(typing_extensions.TypedDict):
+    model_id: str
+    """
+    The ID of the model to use for the generation. See [Models](/build-with-sonic/models) for available models.
+    """
+
+    transcript: str
+    voice: TtsRequestVoiceSpecifierParams
+    language: typing_extensions.NotRequired[SupportedLanguage]
+    output_format: OutputFormatParams
+    duration: typing_extensions.NotRequired[float]
+    """
+    The maximum duration of the audio in seconds. You do not usually need to specify this.
+    If the duration is not appropriate for the length of the transcript, the output audio may be truncated.
+    """

cartesia/tts/requests/tts_request_embedding_specifier.py

@@ -0,0 +1,16 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing_extensions
+import typing
+from ...embedding.types.embedding import Embedding
+import typing_extensions
+from .controls import ControlsParams
+from ...core.serialization import FieldMetadata
+
+
+class TtsRequestEmbeddingSpecifierParams(typing_extensions.TypedDict):
+    mode: typing.Literal["embedding"]
+    embedding: Embedding
+    experimental_controls: typing_extensions.NotRequired[
+        typing_extensions.Annotated[ControlsParams, FieldMetadata(alias="__experimental_controls")]
+    ]