client.py

# This file was auto-generated by Fern from our API Definition.

import typing

from .. import core
from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.pagination import AsyncPager, SyncPager
from ..core.request_options import RequestOptions
from ..types.get_voice import GetVoice
from ..types.list_voices_response import ListVoicesResponse
from .raw_client import AsyncRawVoicesClient, RawVoicesClient
from .types.create_voices_request_gender import CreateVoicesRequestGender

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class VoicesClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawVoicesClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawVoicesClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawVoicesClient
        """
        return self._raw_client

    def list(
        self,
        *,
        cursor: typing.Optional[str] = None,
        limit: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SyncPager[GetVoice, ListVoicesResponse]:
        """
        Lists the voices available to the caller - the shared voice
        catalog plus the workspace's personal cloned voices. By default
        the full catalogue is returned in one response. Pagination is
        opt-in: pass `limit` (and then `cursor` from the previous
        response) to page through the list while `has_more` is true. Max
        page size is 200.

        Parameters
        ----------
        cursor : typing.Optional[str]
            Opaque pagination cursor from a previous response.

        limit : typing.Optional[int]
            Max items per page (default 50, max 200).

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SyncPager[GetVoice, ListVoicesResponse]
            The voice catalogue (or a page of it when `limit` is set).

        Examples
        --------
        from speechify import Speechify

        client = Speechify(
            "2026-07-07",
            token="YOUR_TOKEN",
        )
        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
        """
        return self._raw_client.list(cursor=cursor, limit=limit, request_options=request_options)

    def create(
        self,
        *,
        name: str,
        gender: CreateVoicesRequestGender,
        sample: core.File,
        consent: str,
        idempotency_key: typing.Optional[str] = None,
        locale: typing.Optional[str] = OMIT,
        avatar: typing.Optional[core.File] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> GetVoice:
        """
        Create a personal (cloned) voice for the user

        Parameters
        ----------
        name : str
            Name of the personal voice

        gender : CreateVoicesRequestGender
            Gender marker for the personal voice
            male GenderMale
            female GenderFemale
            not_specified GenderNotSpecified

        sample : core.File
            See core.File for more documentation

        consent : str
            A **string** representing the user consent information in JSON format
            This should include the fullName and email of the consenting individual.
            For example, `{"fullName": "John Doe", "email": "john@example.com"}`

        idempotency_key : typing.Optional[str]
            A client-generated key (an opaque string, max 255 chars) that makes a
            side-effect POST safe to retry: the server runs the operation exactly
            once and replays the first response (its status and body) for 24 hours.
            Reusing a key with a different request body, or while the first request
            is still in flight, returns `409 idempotency_conflict`. A replayed
            response carries the `Idempotent-Replayed: true` header.

        locale : typing.Optional[str]
            Native language (locale) of the personal voice (e.g. en-US, es-ES, etc.)

        avatar : typing.Optional[core.File]
            See core.File for more documentation

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetVoice
            A created voice

        Examples
        --------
        from speechify import Speechify

        client = Speechify(
            "2026-07-07",
            token="YOUR_TOKEN",
        )
        client.voices.create(
            idempotency_key="a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
            name="name",
            gender="male",
            consent="consent",
        )
        """
        _response = self._raw_client.create(
            name=name,
            gender=gender,
            sample=sample,
            consent=consent,
            idempotency_key=idempotency_key,
            locale=locale,
            avatar=avatar,
            request_options=request_options,
        )
        return _response.data

    def get(self, voice_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> GetVoice:
        """
        Fetch a single voice by id - a shared catalogue voice or one of
        the caller's own personal (cloned) voices. A personal voice that
        belongs to another workspace returns 404, identical to an
        unknown id, so voice inventory is never enumerable across tenants.

        Parameters
        ----------
        voice_id : str
            The ID of the voice to fetch

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetVoice
            The voice.

        Examples
        --------
        from speechify import Speechify

        client = Speechify(
            "2026-07-07",
            token="YOUR_TOKEN",
        )
        client.voices.get(
            voice_id="voice_id",
        )
        """
        _response = self._raw_client.get(voice_id, request_options=request_options)
        return _response.data

    def delete(self, voice_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None:
        """
        Delete a personal (cloned) voice

        Parameters
        ----------
        voice_id : str
            The ID of the voice to delete

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        None

        Examples
        --------
        from speechify import Speechify

        client = Speechify(
            "2026-07-07",
            token="YOUR_TOKEN",
        )
        client.voices.delete(
            voice_id="voice_id",
        )
        """
        _response = self._raw_client.delete(voice_id, request_options=request_options)
        return _response.data

    def download_sample(
        self, voice_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.Iterator[bytes]:
        """
        Download a personal (cloned) voice sample

        Parameters
        ----------
        voice_id : str
            The ID of the voice to download sample for

        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.

        Returns
        -------
        typing.Iterator[bytes]
            Voice sample audio file

        Examples
        --------
        from speechify import Speechify

        client = Speechify(
            "2026-07-07",
            token="YOUR_TOKEN",
        )
        client.voices.download_sample(
            voice_id="voice_id",
        )
        """
        with self._raw_client.download_sample(voice_id, request_options=request_options) as r:
            yield from r.data


class AsyncVoicesClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawVoicesClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawVoicesClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawVoicesClient
        """
        return self._raw_client

    async def list(
        self,
        *,
        cursor: typing.Optional[str] = None,
        limit: typing.Optional[int] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AsyncPager[GetVoice, ListVoicesResponse]:
        """
        Lists the voices available to the caller - the shared voice
        catalog plus the workspace's personal cloned voices. By default
        the full catalogue is returned in one response. Pagination is
        opt-in: pass `limit` (and then `cursor` from the previous
        response) to page through the list while `has_more` is true. Max
        page size is 200.

        Parameters
        ----------
        cursor : typing.Optional[str]
            Opaque pagination cursor from a previous response.

        limit : typing.Optional[int]
            Max items per page (default 50, max 200).

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        AsyncPager[GetVoice, ListVoicesResponse]
            The voice catalogue (or a page of it when `limit` is set).

        Examples
        --------
        import asyncio

        from speechify import AsyncSpeechify

        client = AsyncSpeechify(
            "2026-07-07",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            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())
        """
        return await self._raw_client.list(cursor=cursor, limit=limit, request_options=request_options)

    async def create(
        self,
        *,
        name: str,
        gender: CreateVoicesRequestGender,
        sample: core.File,
        consent: str,
        idempotency_key: typing.Optional[str] = None,
        locale: typing.Optional[str] = OMIT,
        avatar: typing.Optional[core.File] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> GetVoice:
        """
        Create a personal (cloned) voice for the user

        Parameters
        ----------
        name : str
            Name of the personal voice

        gender : CreateVoicesRequestGender
            Gender marker for the personal voice
            male GenderMale
            female GenderFemale
            not_specified GenderNotSpecified

        sample : core.File
            See core.File for more documentation

        consent : str
            A **string** representing the user consent information in JSON format
            This should include the fullName and email of the consenting individual.
            For example, `{"fullName": "John Doe", "email": "john@example.com"}`

        idempotency_key : typing.Optional[str]
            A client-generated key (an opaque string, max 255 chars) that makes a
            side-effect POST safe to retry: the server runs the operation exactly
            once and replays the first response (its status and body) for 24 hours.
            Reusing a key with a different request body, or while the first request
            is still in flight, returns `409 idempotency_conflict`. A replayed
            response carries the `Idempotent-Replayed: true` header.

        locale : typing.Optional[str]
            Native language (locale) of the personal voice (e.g. en-US, es-ES, etc.)

        avatar : typing.Optional[core.File]
            See core.File for more documentation

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetVoice
            A created voice

        Examples
        --------
        import asyncio

        from speechify import AsyncSpeechify

        client = AsyncSpeechify(
            "2026-07-07",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.voices.create(
                idempotency_key="a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
                name="name",
                gender="male",
                consent="consent",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.create(
            name=name,
            gender=gender,
            sample=sample,
            consent=consent,
            idempotency_key=idempotency_key,
            locale=locale,
            avatar=avatar,
            request_options=request_options,
        )
        return _response.data

    async def get(self, voice_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> GetVoice:
        """
        Fetch a single voice by id - a shared catalogue voice or one of
        the caller's own personal (cloned) voices. A personal voice that
        belongs to another workspace returns 404, identical to an
        unknown id, so voice inventory is never enumerable across tenants.

        Parameters
        ----------
        voice_id : str
            The ID of the voice to fetch

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetVoice
            The voice.

        Examples
        --------
        import asyncio

        from speechify import AsyncSpeechify

        client = AsyncSpeechify(
            "2026-07-07",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.voices.get(
                voice_id="voice_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get(voice_id, request_options=request_options)
        return _response.data

    async def delete(self, voice_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None:
        """
        Delete a personal (cloned) voice

        Parameters
        ----------
        voice_id : str
            The ID of the voice to delete

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        None

        Examples
        --------
        import asyncio

        from speechify import AsyncSpeechify

        client = AsyncSpeechify(
            "2026-07-07",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.voices.delete(
                voice_id="voice_id",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.delete(voice_id, request_options=request_options)
        return _response.data

    async def download_sample(
        self, voice_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> typing.AsyncIterator[bytes]:
        """
        Download a personal (cloned) voice sample

        Parameters
        ----------
        voice_id : str
            The ID of the voice to download sample for

        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.

        Returns
        -------
        typing.AsyncIterator[bytes]
            Voice sample audio file

        Examples
        --------
        import asyncio

        from speechify import AsyncSpeechify

        client = AsyncSpeechify(
            "2026-07-07",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            await client.voices.download_sample(
                voice_id="voice_id",
            )


        asyncio.run(main())
        """
        async with self._raw_client.download_sample(voice_id, request_options=request_options) as r:
            async for _chunk in r.data:
                yield _chunk