client.py

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

import typing

from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.request_options import RequestOptions
from ..types.get_speech_options_request import GetSpeechOptionsRequest
from ..types.get_speech_response import GetSpeechResponse
from ..types.get_stream_options_request import GetStreamOptionsRequest
from .raw_client import AsyncRawAudioClient, RawAudioClient
from .types.get_speech_request_audio_format import GetSpeechRequestAudioFormat
from .types.get_speech_request_model import GetSpeechRequestModel
from .types.get_stream_request_model import GetStreamRequestModel
from .types.stream_audio_request_accept import StreamAudioRequestAccept

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


class AudioClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawAudioClient(client_wrapper=client_wrapper)

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

        Returns
        -------
        RawAudioClient
        """
        return self._raw_client

    def speech(
        self,
        *,
        input: str,
        voice_id: str,
        audio_format: typing.Optional[GetSpeechRequestAudioFormat] = OMIT,
        language: typing.Optional[str] = OMIT,
        model: typing.Optional[GetSpeechRequestModel] = OMIT,
        options: typing.Optional[GetSpeechOptionsRequest] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> GetSpeechResponse:
        """
        Synthesize speech audio from text or SSML. Returns the complete audio
        file plus billing and speech-mark metadata in a single JSON response.
        For low-latency playback or long-form text, use POST /v1/audio/stream.

        Parameters
        ----------
        input : str
            Plain text or SSML to be synthesized to speech.
            Refer to https://docs.speechify.ai/docs/api-limits for the input size limits.
            Emotion, Pitch and Speed Rate are configured in the ssml input, please refer to the ssml documentation for more information: https://docs.speechify.ai/docs/ssml#prosody

        voice_id : str
            Id of the voice to be used for synthesizing speech. Refer to /v1/voices endpoint for available voices

        audio_format : typing.Optional[GetSpeechRequestAudioFormat]
            The format for the output audio. Note, that the current default is "wav", but there's no guarantee it will not change in the future. We recommend always passing the specific param you expect.

        language : typing.Optional[str]
            Language of the input. Follow the format of an ISO 639-1 language code and an ISO 3166-1 region code, separated by a hyphen, e.g. en-US.
            Please refer to the list of the supported languages and recommendations regarding this parameter: https://docs.speechify.ai/docs/language-support.

        model : typing.Optional[GetSpeechRequestModel]
            Model used for audio synthesis. `simba-english` is optimized for English, `simba-multilingual` for non-English or mixed input. `simba-3.0` is the streaming-native model with lower TTFB and richer expressivity. Currently English only; multilingual coming soon. Non-English voices return 400 until multilingual support ships.

        options : typing.Optional[GetSpeechOptionsRequest]

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

        Returns
        -------
        GetSpeechResponse
            Synthesized speech audio for the requested input.

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

        client = Speechify(
            api_key="YOUR_API_KEY",
        )
        client.audio.speech(
            audio_format="mp3",
            input="Hello! This is the Speechify text-to-speech API.",
            model="simba-english",
            voice_id="george",
        )
        """
        _response = self._raw_client.speech(
            input=input,
            voice_id=voice_id,
            audio_format=audio_format,
            language=language,
            model=model,
            options=options,
            request_options=request_options,
        )
        return _response.data

    def stream(
        self,
        *,
        accept: StreamAudioRequestAccept,
        input: str,
        voice_id: str,
        language: typing.Optional[str] = OMIT,
        model: typing.Optional[GetStreamRequestModel] = OMIT,
        options: typing.Optional[GetStreamOptionsRequest] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> typing.Iterator[bytes]:
        """
        Synthesize speech and stream the audio back as it is generated, for
        low-latency playback. The Accept header selects the audio container;
        the response is raw audio bytes (HTTP chunked). For Base64-encoded
        audio with speech-mark metadata in a single JSON response, use
        POST /v1/audio/speech.

        Parameters
        ----------
        accept : StreamAudioRequestAccept
            Selects the audio container/codec for the streamed response. The
            response Content-Type echoes this value, except `audio/pcm` returns
            `audio/L16` with rate and channels parameters (raw 16-bit linear
            PCM, 24 kHz mono, little-endian).

        input : str
            Plain text or SSML to be synthesized to speech.
            Refer to https://docs.speechify.ai/docs/api-limits for the input size limits.
            Emotion, Pitch and Speed Rate are configured in the ssml input, please refer to the ssml documentation for more information: https://docs.speechify.ai/docs/ssml#prosody

        voice_id : str
            Id of the voice to be used for synthesizing speech. Refer to /v1/voices endpoint for available voices

        language : typing.Optional[str]
            Language of the input. Follow the format of an ISO 639-1 language code and an ISO 3166-1 region code, separated by a hyphen, e.g. en-US.
            Please refer to the list of the supported languages and recommendations regarding this parameter: https://docs.speechify.ai/docs/language-support.

        model : typing.Optional[GetStreamRequestModel]
            Model used for audio synthesis. `simba-english` is optimized for English, `simba-multilingual` for non-English or mixed input. `simba-3.0` is the streaming-native model with lower TTFB and richer expressivity. Currently English only; multilingual coming soon. Non-English voices return 400 until multilingual support ships.

        options : typing.Optional[GetStreamOptionsRequest]

        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]
            Chunked audio stream for the requested input.

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

        client = Speechify(
            api_key="YOUR_API_KEY",
        )
        client.audio.stream(
            accept="audio/mpeg",
            input="input",
            voice_id="voice_id",
        )
        """
        with self._raw_client.stream(
            accept=accept,
            input=input,
            voice_id=voice_id,
            language=language,
            model=model,
            options=options,
            request_options=request_options,
        ) as r:
            yield from r.data


class AsyncAudioClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawAudioClient(client_wrapper=client_wrapper)

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

        Returns
        -------
        AsyncRawAudioClient
        """
        return self._raw_client

    async def speech(
        self,
        *,
        input: str,
        voice_id: str,
        audio_format: typing.Optional[GetSpeechRequestAudioFormat] = OMIT,
        language: typing.Optional[str] = OMIT,
        model: typing.Optional[GetSpeechRequestModel] = OMIT,
        options: typing.Optional[GetSpeechOptionsRequest] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> GetSpeechResponse:
        """
        Synthesize speech audio from text or SSML. Returns the complete audio
        file plus billing and speech-mark metadata in a single JSON response.
        For low-latency playback or long-form text, use POST /v1/audio/stream.

        Parameters
        ----------
        input : str
            Plain text or SSML to be synthesized to speech.
            Refer to https://docs.speechify.ai/docs/api-limits for the input size limits.
            Emotion, Pitch and Speed Rate are configured in the ssml input, please refer to the ssml documentation for more information: https://docs.speechify.ai/docs/ssml#prosody

        voice_id : str
            Id of the voice to be used for synthesizing speech. Refer to /v1/voices endpoint for available voices

        audio_format : typing.Optional[GetSpeechRequestAudioFormat]
            The format for the output audio. Note, that the current default is "wav", but there's no guarantee it will not change in the future. We recommend always passing the specific param you expect.

        language : typing.Optional[str]
            Language of the input. Follow the format of an ISO 639-1 language code and an ISO 3166-1 region code, separated by a hyphen, e.g. en-US.
            Please refer to the list of the supported languages and recommendations regarding this parameter: https://docs.speechify.ai/docs/language-support.

        model : typing.Optional[GetSpeechRequestModel]
            Model used for audio synthesis. `simba-english` is optimized for English, `simba-multilingual` for non-English or mixed input. `simba-3.0` is the streaming-native model with lower TTFB and richer expressivity. Currently English only; multilingual coming soon. Non-English voices return 400 until multilingual support ships.

        options : typing.Optional[GetSpeechOptionsRequest]

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

        Returns
        -------
        GetSpeechResponse
            Synthesized speech audio for the requested input.

        Examples
        --------
        import asyncio

        from speechify import AsyncSpeechify

        client = AsyncSpeechify(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.audio.speech(
                audio_format="mp3",
                input="Hello! This is the Speechify text-to-speech API.",
                model="simba-english",
                voice_id="george",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.speech(
            input=input,
            voice_id=voice_id,
            audio_format=audio_format,
            language=language,
            model=model,
            options=options,
            request_options=request_options,
        )
        return _response.data

    async def stream(
        self,
        *,
        accept: StreamAudioRequestAccept,
        input: str,
        voice_id: str,
        language: typing.Optional[str] = OMIT,
        model: typing.Optional[GetStreamRequestModel] = OMIT,
        options: typing.Optional[GetStreamOptionsRequest] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> typing.AsyncIterator[bytes]:
        """
        Synthesize speech and stream the audio back as it is generated, for
        low-latency playback. The Accept header selects the audio container;
        the response is raw audio bytes (HTTP chunked). For Base64-encoded
        audio with speech-mark metadata in a single JSON response, use
        POST /v1/audio/speech.

        Parameters
        ----------
        accept : StreamAudioRequestAccept
            Selects the audio container/codec for the streamed response. The
            response Content-Type echoes this value, except `audio/pcm` returns
            `audio/L16` with rate and channels parameters (raw 16-bit linear
            PCM, 24 kHz mono, little-endian).

        input : str
            Plain text or SSML to be synthesized to speech.
            Refer to https://docs.speechify.ai/docs/api-limits for the input size limits.
            Emotion, Pitch and Speed Rate are configured in the ssml input, please refer to the ssml documentation for more information: https://docs.speechify.ai/docs/ssml#prosody

        voice_id : str
            Id of the voice to be used for synthesizing speech. Refer to /v1/voices endpoint for available voices

        language : typing.Optional[str]
            Language of the input. Follow the format of an ISO 639-1 language code and an ISO 3166-1 region code, separated by a hyphen, e.g. en-US.
            Please refer to the list of the supported languages and recommendations regarding this parameter: https://docs.speechify.ai/docs/language-support.

        model : typing.Optional[GetStreamRequestModel]
            Model used for audio synthesis. `simba-english` is optimized for English, `simba-multilingual` for non-English or mixed input. `simba-3.0` is the streaming-native model with lower TTFB and richer expressivity. Currently English only; multilingual coming soon. Non-English voices return 400 until multilingual support ships.

        options : typing.Optional[GetStreamOptionsRequest]

        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]
            Chunked audio stream for the requested input.

        Examples
        --------
        import asyncio

        from speechify import AsyncSpeechify

        client = AsyncSpeechify(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.audio.stream(
                accept="audio/mpeg",
                input="input",
                voice_id="voice_id",
            )


        asyncio.run(main())
        """
        async with self._raw_client.stream(
            accept=accept,
            input=input,
            voice_id=voice_id,
            language=language,
            model=model,
            options=options,
            request_options=request_options,
        ) as r:
            async for _chunk in r.data:
                yield _chunk