cartesia 2.0.0b2__py3-none-any.whl → 2.0.0b7__py3-none-any.whl

cartesia/voices/client.py

@@ -2,26 +2,30 @@
 
 import typing
 from ..core.client_wrapper import SyncClientWrapper
+from .types.gender_presentation import GenderPresentation
+from .types.voice_expand_options import VoiceExpandOptions
 from ..core.request_options import RequestOptions
+from ..core.pagination import SyncPager
 from .types.voice import Voice
+from .types.get_voices_response import GetVoicesResponse
 from ..core.pydantic_utilities import parse_obj_as
 from json.decoder import JSONDecodeError
 from ..core.api_error import ApiError
-from .. import core
+from ..embedding.types.embedding import Embedding
 from ..tts.types.supported_language import SupportedLanguage
-from .types.clone_mode import CloneMode
-from .types.voice_metadata import VoiceMetadata
 from .types.voice_id import VoiceId
 from ..core.jsonable_encoder import jsonable_encoder
-from ..embedding.types.embedding import Embedding
 from .types.localize_target_language import LocalizeTargetLanguage
 from .types.gender import Gender
 from .requests.localize_dialect import LocalizeDialectParams
 from .types.embedding_response import EmbeddingResponse
 from ..core.serialization import convert_and_respect_annotation_metadata
 from .requests.mix_voice_specifier import MixVoiceSpecifierParams
-from .types.base_voice_id import BaseVoiceId
+from .. import core
+from .types.clone_mode import CloneMode
+from .types.voice_metadata import VoiceMetadata
 from ..core.client_wrapper import AsyncClientWrapper
+from ..core.pagination import AsyncPager
 
 # this is used as the default value for optional parameters
 OMIT = typing.cast(typing.Any, ...)
@@ -31,16 +35,54 @@ class VoicesClient:
     def __init__(self, *, client_wrapper: SyncClientWrapper):
         self._client_wrapper = client_wrapper
 
-    def list(self, *, request_options: typing.Optional[RequestOptions] = None) -> typing.List[Voice]:
+    def list(
+        self,
+        *,
+        limit: typing.Optional[int] = None,
+        starting_after: typing.Optional[str] = None,
+        ending_before: typing.Optional[str] = None,
+        is_owner: typing.Optional[bool] = None,
+        is_starred: typing.Optional[bool] = None,
+        gender: typing.Optional[GenderPresentation] = None,
+        expand: typing.Optional[typing.Sequence[VoiceExpandOptions]] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> SyncPager[Voice]:
         """
         Parameters
         ----------
+        limit : typing.Optional[int]
+            The number of Voices to return per page, ranging between 1 and 100.
+
+        starting_after : typing.Optional[str]
+            A cursor to use in pagination. `starting_after` is a Voice ID that defines your
+            place in the list. For example, if you make a /voices request and receive 100
+            objects, ending with `voice_abc123`, your subsequent call can include
+            `starting_after=voice_abc123` to fetch the next page of the list.
+
+        ending_before : typing.Optional[str]
+            A cursor to use in pagination. `ending_before` is a Voice ID that defines your
+            place in the list. For example, if you make a /voices request and receive 100
+            objects, starting with `voice_abc123`, your subsequent call can include
+            `ending_before=voice_abc123` to fetch the previous page of the list.
+
+        is_owner : typing.Optional[bool]
+            Whether to only return voices owned by the current user.
+
+        is_starred : typing.Optional[bool]
+            Whether to only return starred voices.
+
+        gender : typing.Optional[GenderPresentation]
+            The gender presentation of the voices to return.
+
+        expand : typing.Optional[typing.Sequence[VoiceExpandOptions]]
+            Additional fields to include in the response.
+
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.List[Voice]
+        SyncPager[Voice]
 
         Examples
         --------
@@ -49,81 +91,83 @@ class VoicesClient:
         client = Cartesia(
             api_key="YOUR_API_KEY",
         )
-        client.voices.list()
+        response = client.voices.list()
+        for item in response:
+            yield item
+        # alternatively, you can paginate page-by-page
+        for page in response.iter_pages():
+            yield page
         """
         _response = self._client_wrapper.httpx_client.request(
             "voices/",
             method="GET",
+            params={
+                "limit": limit,
+                "starting_after": starting_after,
+                "ending_before": ending_before,
+                "is_owner": is_owner,
+                "is_starred": is_starred,
+                "gender": gender,
+                "expand[]": expand,
+            },
             request_options=request_options,
         )
         try:
             if 200 <= _response.status_code < 300:
-                return typing.cast(
-                    typing.List[Voice],
+                _parsed_response = typing.cast(
+                    GetVoicesResponse,
                     parse_obj_as(
-                        type_=typing.List[Voice],  # type: ignore
+                        type_=GetVoicesResponse,  # type: ignore
                         object_=_response.json(),
                     ),
                 )
+                _parsed_next = _parsed_response.next_page
+                _has_next = _parsed_next is not None and _parsed_next != ""
+                _get_next = lambda: self.list(
+                    limit=limit,
+                    starting_after=_parsed_next,
+                    ending_before=ending_before,
+                    is_owner=is_owner,
+                    is_starred=is_starred,
+                    gender=gender,
+                    expand=expand,
+                    request_options=request_options,
+                )
+                _items = _parsed_response.data
+                return SyncPager(has_next=_has_next, items=_items, get_next=_get_next)
             _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 clone(
+    def create(
         self,
         *,
-        clip: core.File,
         name: str,
-        language: SupportedLanguage,
-        mode: CloneMode,
-        enhance: bool,
-        description: typing.Optional[str] = OMIT,
-        transcript: typing.Optional[str] = OMIT,
+        description: str,
+        embedding: Embedding,
+        language: typing.Optional[SupportedLanguage] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> VoiceMetadata:
+    ) -> Voice:
         """
-        Clone a voice from an audio clip. This endpoint has two modes, stability and similarity.
-
-        Similarity mode clones are more similar to the source clip, but may reproduce background noise. For these, use an audio clip about 5 seconds long.
-
-        Stability mode clones are more stable, but may not sound as similar to the source clip. For these, use an audio clip 10-20 seconds long.
-
         Parameters
         ----------
-        clip : core.File
-            See core.File for more documentation
-
         name : str
             The name of the voice.
 
+        description : str
+            The description of the voice.
 
-        language : SupportedLanguage
-            The language of the voice.
-
-
-        mode : CloneMode
-            Tradeoff between similarity and stability. Similarity clones sound more like the source clip, but may reproduce background noise. Stability clones always sound like a studio recording, but may not sound as similar to the source clip.
-
-
-        enhance : bool
-            Whether to enhance the clip to improve its quality before cloning. Useful if the clip has background noise.
-
-
-        description : typing.Optional[str]
-            A description for the voice.
-
-
-        transcript : typing.Optional[str]
-            Optional transcript of the words spoken in the audio clip. Only used for similarity mode.
+        embedding : Embedding
 
+        language : typing.Optional[SupportedLanguage]
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        VoiceMetadata
+        Voice
 
         Examples
         --------
@@ -132,27 +176,20 @@ class VoicesClient:
         client = Cartesia(
             api_key="YOUR_API_KEY",
         )
-        client.voices.clone(
-            name="A high-stability cloned voice",
-            description="Copied from Cartesia docs",
-            mode="stability",
-            language="en",
-            enhance=True,
+        client.voices.create(
+            name="name",
+            description="description",
+            embedding=[1.1, 1.1],
         )
         """
         _response = self._client_wrapper.httpx_client.request(
-            "voices/clone",
+            "voices/",
             method="POST",
-            data={
+            json={
                 "name": name,
                 "description": description,
+                "embedding": embedding,
                 "language": language,
-                "mode": mode,
-                "enhance": enhance,
-                "transcript": transcript,
-            },
-            files={
-                "clip": clip,
             },
             request_options=request_options,
             omit=OMIT,
@@ -160,9 +197,9 @@ class VoicesClient:
         try:
             if 200 <= _response.status_code < 300:
                 return typing.cast(
-                    VoiceMetadata,
+                    Voice,
                     parse_obj_as(
-                        type_=VoiceMetadata,  # type: ignore
+                        type_=Voice,  # type: ignore
                         object_=_response.json(),
                     ),
                 )
@@ -431,39 +468,58 @@ class VoicesClient:
             raise ApiError(status_code=_response.status_code, body=_response.text)
         raise ApiError(status_code=_response.status_code, body=_response_json)
 
-    def create(
+    def clone(
         self,
         *,
+        clip: core.File,
         name: str,
-        description: str,
-        embedding: Embedding,
-        language: typing.Optional[SupportedLanguage] = OMIT,
-        base_voice_id: typing.Optional[BaseVoiceId] = OMIT,
+        language: SupportedLanguage,
+        mode: CloneMode,
+        enhance: bool,
+        description: typing.Optional[str] = OMIT,
+        transcript: typing.Optional[str] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> Voice:
+    ) -> VoiceMetadata:
         """
-        Create voice from raw features. If you'd like to clone a voice from an audio file, please use Clone Voice instead.
+        Clone a voice from an audio clip. This endpoint has two modes, stability and similarity.
+        Similarity mode clones are more similar to the source clip, but may reproduce background noise. For these, use an audio clip about 5 seconds long.
+        Stability mode clones are more stable, but may not sound as similar to the source clip. For these, use an audio clip 10-20 seconds long.
 
         Parameters
         ----------
+        clip : core.File
+            See core.File for more documentation
+
         name : str
             The name of the voice.
 
-        description : str
-            The description of the voice.
 
-        embedding : Embedding
+        language : SupportedLanguage
+            The language of the voice.
 
-        language : typing.Optional[SupportedLanguage]
 
-        base_voice_id : typing.Optional[BaseVoiceId]
+        mode : CloneMode
+            Tradeoff between similarity and stability. Similarity clones sound more like the source clip, but may reproduce background noise. Stability clones always sound like a studio recording, but may not sound as similar to the source clip.
+
+
+        enhance : bool
+            Whether to enhance the clip to improve its quality before cloning. Useful if the clip has background noise.
+
+
+        description : typing.Optional[str]
+            A description for the voice.
+
+
+        transcript : typing.Optional[str]
+            Optional transcript of the words spoken in the audio clip. Only used for similarity mode.
+
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        Voice
+        VoiceMetadata
 
         Examples
         --------
@@ -472,23 +528,27 @@ class VoicesClient:
         client = Cartesia(
             api_key="YOUR_API_KEY",
         )
-        client.voices.create(
-            name="My Custom Voice",
-            description="A custom voice created through the API",
-            embedding=[],
+        client.voices.clone(
+            name="A high-stability cloned voice",
+            description="Copied from Cartesia docs",
+            mode="stability",
             language="en",
-            base_voice_id="123e4567-e89b-12d3-a456-426614174000",
+            enhance=True,
         )
         """
         _response = self._client_wrapper.httpx_client.request(
-            "voices/",
+            "voices/clone",
             method="POST",
-            json={
+            data={
                 "name": name,
                 "description": description,
-                "embedding": embedding,
                 "language": language,
-                "base_voice_id": base_voice_id,
+                "mode": mode,
+                "enhance": enhance,
+                "transcript": transcript,
+            },
+            files={
+                "clip": clip,
             },
             request_options=request_options,
             omit=OMIT,
@@ -496,9 +556,9 @@ class VoicesClient:
         try:
             if 200 <= _response.status_code < 300:
                 return typing.cast(
-                    Voice,
+                    VoiceMetadata,
                     parse_obj_as(
-                        type_=Voice,  # type: ignore
+                        type_=VoiceMetadata,  # type: ignore
                         object_=_response.json(),
                     ),
                 )
@@ -512,16 +572,54 @@ class AsyncVoicesClient:
     def __init__(self, *, client_wrapper: AsyncClientWrapper):
         self._client_wrapper = client_wrapper
 
-    async def list(self, *, request_options: typing.Optional[RequestOptions] = None) -> typing.List[Voice]:
+    async def list(
+        self,
+        *,
+        limit: typing.Optional[int] = None,
+        starting_after: typing.Optional[str] = None,
+        ending_before: typing.Optional[str] = None,
+        is_owner: typing.Optional[bool] = None,
+        is_starred: typing.Optional[bool] = None,
+        gender: typing.Optional[GenderPresentation] = None,
+        expand: typing.Optional[typing.Sequence[VoiceExpandOptions]] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncPager[Voice]:
         """
         Parameters
         ----------
+        limit : typing.Optional[int]
+            The number of Voices to return per page, ranging between 1 and 100.
+
+        starting_after : typing.Optional[str]
+            A cursor to use in pagination. `starting_after` is a Voice ID that defines your
+            place in the list. For example, if you make a /voices request and receive 100
+            objects, ending with `voice_abc123`, your subsequent call can include
+            `starting_after=voice_abc123` to fetch the next page of the list.
+
+        ending_before : typing.Optional[str]
+            A cursor to use in pagination. `ending_before` is a Voice ID that defines your
+            place in the list. For example, if you make a /voices request and receive 100
+            objects, starting with `voice_abc123`, your subsequent call can include
+            `ending_before=voice_abc123` to fetch the previous page of the list.
+
+        is_owner : typing.Optional[bool]
+            Whether to only return voices owned by the current user.
+
+        is_starred : typing.Optional[bool]
+            Whether to only return starred voices.
+
+        gender : typing.Optional[GenderPresentation]
+            The gender presentation of the voices to return.
+
+        expand : typing.Optional[typing.Sequence[VoiceExpandOptions]]
+            Additional fields to include in the response.
+
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        typing.List[Voice]
+        AsyncPager[Voice]
 
         Examples
         --------
@@ -535,7 +633,12 @@ class AsyncVoicesClient:
 
 
         async def main() -> None:
-            await client.voices.list()
+            response = await client.voices.list()
+            async for item in response:
+                yield item
+            # alternatively, you can paginate page-by-page
+            async for page in response.iter_pages():
+                yield page
 
 
         asyncio.run(main())
@@ -543,76 +646,73 @@ class AsyncVoicesClient:
         _response = await self._client_wrapper.httpx_client.request(
             "voices/",
             method="GET",
+            params={
+                "limit": limit,
+                "starting_after": starting_after,
+                "ending_before": ending_before,
+                "is_owner": is_owner,
+                "is_starred": is_starred,
+                "gender": gender,
+                "expand[]": expand,
+            },
             request_options=request_options,
         )
         try:
             if 200 <= _response.status_code < 300:
-                return typing.cast(
-                    typing.List[Voice],
+                _parsed_response = typing.cast(
+                    GetVoicesResponse,
                     parse_obj_as(
-                        type_=typing.List[Voice],  # type: ignore
+                        type_=GetVoicesResponse,  # type: ignore
                         object_=_response.json(),
                     ),
                 )
+                _parsed_next = _parsed_response.next_page
+                _has_next = _parsed_next is not None and _parsed_next != ""
+                _get_next = lambda: self.list(
+                    limit=limit,
+                    starting_after=_parsed_next,
+                    ending_before=ending_before,
+                    is_owner=is_owner,
+                    is_starred=is_starred,
+                    gender=gender,
+                    expand=expand,
+                    request_options=request_options,
+                )
+                _items = _parsed_response.data
+                return AsyncPager(has_next=_has_next, items=_items, get_next=_get_next)
             _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 clone(
+    async def create(
         self,
         *,
-        clip: core.File,
         name: str,
-        language: SupportedLanguage,
-        mode: CloneMode,
-        enhance: bool,
-        description: typing.Optional[str] = OMIT,
-        transcript: typing.Optional[str] = OMIT,
+        description: str,
+        embedding: Embedding,
+        language: typing.Optional[SupportedLanguage] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> VoiceMetadata:
+    ) -> Voice:
         """
-        Clone a voice from an audio clip. This endpoint has two modes, stability and similarity.
-
-        Similarity mode clones are more similar to the source clip, but may reproduce background noise. For these, use an audio clip about 5 seconds long.
-
-        Stability mode clones are more stable, but may not sound as similar to the source clip. For these, use an audio clip 10-20 seconds long.
-
         Parameters
         ----------
-        clip : core.File
-            See core.File for more documentation
-
         name : str
             The name of the voice.
 
+        description : str
+            The description of the voice.
 
-        language : SupportedLanguage
-            The language of the voice.
-
-
-        mode : CloneMode
-            Tradeoff between similarity and stability. Similarity clones sound more like the source clip, but may reproduce background noise. Stability clones always sound like a studio recording, but may not sound as similar to the source clip.
-
-
-        enhance : bool
-            Whether to enhance the clip to improve its quality before cloning. Useful if the clip has background noise.
-
-
-        description : typing.Optional[str]
-            A description for the voice.
-
-
-        transcript : typing.Optional[str]
-            Optional transcript of the words spoken in the audio clip. Only used for similarity mode.
+        embedding : Embedding
 
+        language : typing.Optional[SupportedLanguage]
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        VoiceMetadata
+        Voice
 
         Examples
         --------
@@ -626,30 +726,23 @@ class AsyncVoicesClient:
 
 
         async def main() -> None:
-            await client.voices.clone(
-                name="A high-stability cloned voice",
-                description="Copied from Cartesia docs",
-                mode="stability",
-                language="en",
-                enhance=True,
+            await client.voices.create(
+                name="name",
+                description="description",
+                embedding=[1.1, 1.1],
             )
 
 
         asyncio.run(main())
         """
         _response = await self._client_wrapper.httpx_client.request(
-            "voices/clone",
+            "voices/",
             method="POST",
-            data={
+            json={
                 "name": name,
                 "description": description,
+                "embedding": embedding,
                 "language": language,
-                "mode": mode,
-                "enhance": enhance,
-                "transcript": transcript,
-            },
-            files={
-                "clip": clip,
             },
             request_options=request_options,
             omit=OMIT,
@@ -657,9 +750,9 @@ class AsyncVoicesClient:
         try:
             if 200 <= _response.status_code < 300:
                 return typing.cast(
-                    VoiceMetadata,
+                    Voice,
                     parse_obj_as(
-                        type_=VoiceMetadata,  # type: ignore
+                        type_=Voice,  # type: ignore
                         object_=_response.json(),
                     ),
                 )
@@ -968,39 +1061,58 @@ class AsyncVoicesClient:
             raise ApiError(status_code=_response.status_code, body=_response.text)
         raise ApiError(status_code=_response.status_code, body=_response_json)
 
-    async def create(
+    async def clone(
         self,
         *,
+        clip: core.File,
         name: str,
-        description: str,
-        embedding: Embedding,
-        language: typing.Optional[SupportedLanguage] = OMIT,
-        base_voice_id: typing.Optional[BaseVoiceId] = OMIT,
+        language: SupportedLanguage,
+        mode: CloneMode,
+        enhance: bool,
+        description: typing.Optional[str] = OMIT,
+        transcript: typing.Optional[str] = OMIT,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> Voice:
+    ) -> VoiceMetadata:
         """
-        Create voice from raw features. If you'd like to clone a voice from an audio file, please use Clone Voice instead.
+        Clone a voice from an audio clip. This endpoint has two modes, stability and similarity.
+        Similarity mode clones are more similar to the source clip, but may reproduce background noise. For these, use an audio clip about 5 seconds long.
+        Stability mode clones are more stable, but may not sound as similar to the source clip. For these, use an audio clip 10-20 seconds long.
 
         Parameters
         ----------
+        clip : core.File
+            See core.File for more documentation
+
         name : str
             The name of the voice.
 
-        description : str
-            The description of the voice.
 
-        embedding : Embedding
+        language : SupportedLanguage
+            The language of the voice.
 
-        language : typing.Optional[SupportedLanguage]
 
-        base_voice_id : typing.Optional[BaseVoiceId]
+        mode : CloneMode
+            Tradeoff between similarity and stability. Similarity clones sound more like the source clip, but may reproduce background noise. Stability clones always sound like a studio recording, but may not sound as similar to the source clip.
+
+
+        enhance : bool
+            Whether to enhance the clip to improve its quality before cloning. Useful if the clip has background noise.
+
+
+        description : typing.Optional[str]
+            A description for the voice.
+
+
+        transcript : typing.Optional[str]
+            Optional transcript of the words spoken in the audio clip. Only used for similarity mode.
+
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
         Returns
         -------
-        Voice
+        VoiceMetadata
 
         Examples
         --------
@@ -1014,26 +1126,30 @@ class AsyncVoicesClient:
 
 
         async def main() -> None:
-            await client.voices.create(
-                name="My Custom Voice",
-                description="A custom voice created through the API",
-                embedding=[],
+            await client.voices.clone(
+                name="A high-stability cloned voice",
+                description="Copied from Cartesia docs",
+                mode="stability",
                 language="en",
-                base_voice_id="123e4567-e89b-12d3-a456-426614174000",
+                enhance=True,
             )
 
 
         asyncio.run(main())
         """
         _response = await self._client_wrapper.httpx_client.request(
-            "voices/",
+            "voices/clone",
             method="POST",
-            json={
+            data={
                 "name": name,
                 "description": description,
-                "embedding": embedding,
                 "language": language,
-                "base_voice_id": base_voice_id,
+                "mode": mode,
+                "enhance": enhance,
+                "transcript": transcript,
+            },
+            files={
+                "clip": clip,
             },
             request_options=request_options,
             omit=OMIT,
@@ -1041,9 +1157,9 @@ class AsyncVoicesClient:
         try:
             if 200 <= _response.status_code < 300:
                 return typing.cast(
-                    Voice,
+                    VoiceMetadata,
                     parse_obj_as(
-                        type_=Voice,  # type: ignore
+                        type_=VoiceMetadata,  # type: ignore
                         object_=_response.json(),
                     ),
                 )