client.py

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

from __future__ import annotations

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
from .types.list_voices_request_gender import ListVoicesRequestGender
from .types.list_voices_request_type import ListVoicesRequestType

if typing.TYPE_CHECKING:
    from .consent_challenges.client import AsyncConsentChallengesClient, ConsentChallengesClient
# 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)
        self._client_wrapper = client_wrapper
        self._consent_challenges: typing.Optional[ConsentChallengesClient] = None

    @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,
        type: typing.Optional[ListVoicesRequestType] = None,
        locale: typing.Optional[str] = None,
        gender: typing.Optional[ListVoicesRequestGender] = None,
        model: typing.Optional[str] = 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 cloned voices, whichever member or
        service-account key created them. 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. Narrow the list with the `type` and `locale`
        filters (applied before pagination, so pages stay full).

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

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

        type : typing.Optional[ListVoicesRequestType]
            Filter by voice type: `personal` (the workspace's cloned voices)
            or `shared` (the public catalogue). Omit to return both.

        locale : typing.Optional[str]
            Filter to voices whose locale matches this BCP-47 language range,
            prefix-matched: `en` matches `en-US` and `en-GB`; `en-US` matches
            only `en-US`. Case-insensitive. Omit to return all locales.

        gender : typing.Optional[ListVoicesRequestGender]
            Filter by voice gender. Omit to return all genders.

        model : typing.Optional[str]
            Filter to voices that support this model (as listed in each voice's
            `models[]`), e.g. `simba-3.2`. Omit to return voices for all models.

        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-09-13",
            token="YOUR_TOKEN",
        )
        response = client.voices.list(
            locale="en",
            model="simba-3.2",
        )
        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,
            type=type,
            locale=locale,
            gender=gender,
            model=model,
            request_options=request_options,
        )

    def create(
        self,
        *,
        name: str,
        gender: CreateVoicesRequestGender,
        sample: core.File,
        consent_challenge_id: str,
        consent_recording: core.File,
        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 cloned voice for the workspace from a 10-30 second audio sample, with verified consent from the speaker.

        Cloning requires proof that the speaker agreed to it. Create a consent challenge with `POST /v1/voices/consent-challenges`, show the returned `phrase` to the speaker, record them reading it aloud, and send that recording here as `consent_recording` together with the challenge's `consent_challenge_id`. Speechify transcribes the recording, checks it against the phrase it issued, checks that its speaker is the speaker in your `sample`, and keeps it as the consent record for the voice. The person consenting therefore has to be the person being cloned. A challenge is single use and short-lived, so record and submit in one sitting.

        The clone belongs to the workspace rather than the member who created it, and access follows the caller's workspace role and API-key scopes exactly as for any other voice: voices scopes to list it, audio scopes to synthesize with it, and the content-management permission plus a write scope on the key to delete it. Cloned voices are usable self-serve on `simba-3.0`, `simba-english` and `simba-multilingual`. `simba-3.2` also serves cloned voices, currently as a limited release enabled per workspace; contact Speechify to have it enabled for yours.

        Callers pinned before `Speechify-Version: 2026-09-13` use the previous flow instead: no challenge, and a `consent` form field carrying the speaker's name and email as a JSON string. That flow is deprecated and will be removed after a sunset window announced in the changelog.

        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_challenge_id : str
            The `id` of the consent challenge this create consumes, from
            `POST /v1/voices/consent-challenges`. Single use: once a
            create has consumed it, whether or not that create
            succeeded, it cannot be used again.

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

        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-09-13",
            token="YOUR_TOKEN",
        )
        client.voices.create(
            idempotency_key="a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
            name="name",
            gender="male",
            consent_challenge_id="consent_challenge_id",
        )
        """
        _response = self._raw_client.create(
            name=name,
            gender=gender,
            sample=sample,
            consent_challenge_id=consent_challenge_id,
            consent_recording=consent_recording,
            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 workspace's cloned voices. A cloned 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-09-13",
            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 one of the workspace's cloned voices. Requires the
        `content.manage` permission (owner, admin, or member); a
        service-account key is authorized by its scopes instead.

        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-09-13",
            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-09-13",
            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

    @property
    def consent_challenges(self):
        if self._consent_challenges is None:
            from .consent_challenges.client import ConsentChallengesClient  # noqa: E402

            self._consent_challenges = ConsentChallengesClient(client_wrapper=self._client_wrapper)
        return self._consent_challenges


class AsyncVoicesClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawVoicesClient(client_wrapper=client_wrapper)
        self._client_wrapper = client_wrapper
        self._consent_challenges: typing.Optional[AsyncConsentChallengesClient] = None

    @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,
        type: typing.Optional[ListVoicesRequestType] = None,
        locale: typing.Optional[str] = None,
        gender: typing.Optional[ListVoicesRequestGender] = None,
        model: typing.Optional[str] = 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 cloned voices, whichever member or
        service-account key created them. 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. Narrow the list with the `type` and `locale`
        filters (applied before pagination, so pages stay full).

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

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

        type : typing.Optional[ListVoicesRequestType]
            Filter by voice type: `personal` (the workspace's cloned voices)
            or `shared` (the public catalogue). Omit to return both.

        locale : typing.Optional[str]
            Filter to voices whose locale matches this BCP-47 language range,
            prefix-matched: `en` matches `en-US` and `en-GB`; `en-US` matches
            only `en-US`. Case-insensitive. Omit to return all locales.

        gender : typing.Optional[ListVoicesRequestGender]
            Filter by voice gender. Omit to return all genders.

        model : typing.Optional[str]
            Filter to voices that support this model (as listed in each voice's
            `models[]`), e.g. `simba-3.2`. Omit to return voices for all models.

        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-09-13",
            token="YOUR_TOKEN",
        )


        async def main() -> None:
            response = await client.voices.list(
                locale="en",
                model="simba-3.2",
            )
            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,
            type=type,
            locale=locale,
            gender=gender,
            model=model,
            request_options=request_options,
        )

    async def create(
        self,
        *,
        name: str,
        gender: CreateVoicesRequestGender,
        sample: core.File,
        consent_challenge_id: str,
        consent_recording: core.File,
        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 cloned voice for the workspace from a 10-30 second audio sample, with verified consent from the speaker.

        Cloning requires proof that the speaker agreed to it. Create a consent challenge with `POST /v1/voices/consent-challenges`, show the returned `phrase` to the speaker, record them reading it aloud, and send that recording here as `consent_recording` together with the challenge's `consent_challenge_id`. Speechify transcribes the recording, checks it against the phrase it issued, checks that its speaker is the speaker in your `sample`, and keeps it as the consent record for the voice. The person consenting therefore has to be the person being cloned. A challenge is single use and short-lived, so record and submit in one sitting.

        The clone belongs to the workspace rather than the member who created it, and access follows the caller's workspace role and API-key scopes exactly as for any other voice: voices scopes to list it, audio scopes to synthesize with it, and the content-management permission plus a write scope on the key to delete it. Cloned voices are usable self-serve on `simba-3.0`, `simba-english` and `simba-multilingual`. `simba-3.2` also serves cloned voices, currently as a limited release enabled per workspace; contact Speechify to have it enabled for yours.

        Callers pinned before `Speechify-Version: 2026-09-13` use the previous flow instead: no challenge, and a `consent` form field carrying the speaker's name and email as a JSON string. That flow is deprecated and will be removed after a sunset window announced in the changelog.

        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_challenge_id : str
            The `id` of the consent challenge this create consumes, from
            `POST /v1/voices/consent-challenges`. Single use: once a
            create has consumed it, whether or not that create
            succeeded, it cannot be used again.

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

        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-09-13",
            token="YOUR_TOKEN",
        )


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


        asyncio.run(main())
        """
        _response = await self._raw_client.create(
            name=name,
            gender=gender,
            sample=sample,
            consent_challenge_id=consent_challenge_id,
            consent_recording=consent_recording,
            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 workspace's cloned voices. A cloned 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-09-13",
            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 one of the workspace's cloned voices. Requires the
        `content.manage` permission (owner, admin, or member); a
        service-account key is authorized by its scopes instead.

        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-09-13",
            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-09-13",
            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

    @property
    def consent_challenges(self):
        if self._consent_challenges is None:
            from .consent_challenges.client import AsyncConsentChallengesClient  # noqa: E402

            self._consent_challenges = AsyncConsentChallengesClient(client_wrapper=self._client_wrapper)
        return self._consent_challenges