Daisys API clients¶

These objects should not be instantiated directly, but accessed through the DaisysAPI top-level factory object.

The synchronous client makes requests using synchronous, blocking calls. The asynchronous client uses an asyncio event loop. You should choose whichever implementation is most convenient for your application.

class daisys.v1.speak.sync_client.DaisysSyncSpeakClientV1(auth_url: str, product_url: str, email: str, password: str, access_token: str, refresh_token: str)¶

Wrapper for Daisys v1 API endpoints, synchronous version.

close()¶: To be called when object is destroyed, to ensure any open HTTP connections are cleanly closed. This is done automatically if the client was created through a context manager.

delete_take(take_id: str, raise_on_error: bool = True) → bool¶

Delete a take. The take will no longer appear in return values from get_takes.

Parameters:

take_id – the id of a take to delete.
raise_on_error – If True (default) a DaisysTakeDeletionException error will be raised if the take was not found. (That is, if the function would have returned False.)

Returns:

True if the take was deleted successfully, otherwise False.

Return type:

bool

Note that HTTP exceptions may be thrown for errors other than a take not being found.

delete_voice(voice_id: str, raise_on_error: bool = True) → bool¶

Delete a voice. The voice will no longer appear in return values from get_voices.

Parameters:

voice_id – the id of a voice to delete.
raise_on_error – If True (default) a DaisysVoiceDeletionException error will be raised if the voice was not found. (That is, if the function would have returned False.)

Returns:

True if the voice was deleted successfully, otherwise False.

Return type:

bool

Note that HTTP exceptions may be thrown for errors other than a voice not being found.

Generate a “take”, an audio file containing an utterance of the given text by the given voice.

Parameters:

voice_id – The id of the voice to be used for generating audio. The voice is attached to a specific model.
text – The text that the voice should say.
override_language – Normally a language classifier is used to detect the language of the speech; this allows for multilingual sentences. However, if the language should be enforced, it should be provided here. Currently accepted values are “nl-NL” and “en-GB”.
style – A list of styles to enable when speaking. Note that most styles are mutually exclusive, so a list of 1 value should be provided. Accepted styles can be retrieved from the associated voice’s VoiceInfo.styles or the model’s TTSModel.styles field. Note that not all models support styles, thus this can be left empty if specific styles are not desired.
prosody – The characteristics of the desired speech not determined by the voice or style. Here you can provide a SimpleProsody or most models also accept the more detailed AffectProsody.
status_webhook – An optional URL to be called using POST whenever the take’s status changes, with TakeResponse in the body content.
done_webhook – An optional URL to be called exactly once using POST when the take is READY, ERROR, or TIMEOUT, with TakeResponse in the body content.
wait – if True, wait for take to be ready before returning.
raise_on_error – If True (default) a DaisysTakeGeenerateException error will be raised. If this behavior is not desired, set to False.
timeout – Time limit to wait, in seconds. Note that if timeout is specified, some results may not have a “done” status (ready or error).

Returns:

Information about the take being generated, including status.

Return type:

TakeResponse

generate_takes(request: list[TakeGenerate], wait: bool = True, raise_on_error: bool = True, timeout: float | None = None) → list[TakeResponse]¶

Generate several “takes”, each corresponding to an audio file containing an utterance of the given text by the given voice.

Parameters:

request – a list of list[TakeGenerate] objects describing multiple take generation requests.
wait – if True, wait for all takes to be ready before returning.
raise_on_error – If True (default) a DaisysTakeGeenerateException error will be raised. If this behavior is not desired, set to False.
timeout – Time limit to wait, in seconds. Note that if timeout is specified, some results may not have a “done” status (ready or error).

Returns:

a list of TakeResponse objects containing information on the generation status of each result.

Return type:

list[TakeResponse]

generate_voice(name: str, model: str, gender: VoiceGender, description: str | None = None, default_style: list[str] | None = None, default_prosody: SimpleProsody | AffectProsody | SignalProsody | None = None, example_take: TakeGenerateWithoutVoice | None = None, done_webhook: str | None = None, wait: bool = True, raise_on_error: bool = True, timeout: float | None = None) → VoiceInfo¶

Generate a random, novel voice for a given model with desired properties.

Parameters:

name – A name to give the voice, may be any string, and does not need to be unique.
model – The name of the model for this voice.
gender – The gender of this voice.
description – The description of this voice.
default_style – An optional list of styles to associate with this voice by default. It can be overriden by a take that uses this voice. Note that most styles are mutually exclusive, and not all models support styles.
default_prosody – An optional default prosody to associate with this voice. It can be overridden by a take that uses this voice.
example_take – Information on the take to generate as an example of this voice.
done_webhook – An optional URL to call exactly once using POST when the voice is available, with VoiceInfo in the body content.
wait – True to wait for the result, or False to continue without waiting.
raise_on_error – If True (default) a DaisysVoiceGenerateException error will be raised if an error status is detected in one of the takes. If this behavior is not desired, set to False.
timeout – Time limit to wait, in seconds. Note that if timeout is specified, some results may not have a “done” status (ready or error).

Returns:

Information about the generated voice.

Return type:

VoiceInfo

get_model(model_name: str) → TTSModel¶

Get information about a model.

Parameters:: model_name – The name of the model, which is a unique identifier.
Returns:: Information about the model.
Return type:: TTSModel

get_models() → list[TTSModel]¶

Get information about all available models.

Returns:: Information about each model.
Return type:: list[TTSModel]

get_take(take_id: str) → TakeResponse¶

Get information about a specific take.

Parameters:: take_id – Unique identifier for a take.
Returns:: Information about the requested take.
Return type:: TakeResponse

get_take_audio(take_id: str, file: str | None = None, format: str = 'wav') → bytes¶

Get audio associated with a take.

Parameters:

take_id – A take_id to retrieve the audio for.
file – Optionally, the filename of a file to write, or a file stream to write to.
format – A supported format, must be one of ‘wav’, ‘mp3’, ‘flac’, ‘m4a’. Note: only ‘wav’ may be retrieved without waiting for ‘ready’ status.

Returns:

The content of the audio file associated with the requested take.

Return type:

bytes

get_take_audio_url(take_id: str, format: str = 'wav') → str¶

Get the signed URL for audio associated with a take. May be used to provide the URL to a download or streaming client that does not have the API access token.

Parameters:

take_id – A take_id to retrieve the audio URL for.
format – A supported format, msut be one of ‘wav’, ‘mp3’, ‘flac’, ‘m4a’. Note: only ‘wav’ may be retrieved without waiting for ‘ready’ status.

Returns:

The URL that can be used to download the content of the: audio associated with the requested take.

Return type:

str

Get a list of takes, optionally filtered.

Parameters:

take_ids – A list of specific takes to retrieve.
length – Maximum number of voices to return. Default: unlimited.
page – Return page “page” of length “length”. Default: 1.
older – Find voices older than or equal to this timestamp (milliseconds).
newer – Find voices newer than or equal to this timestamp (milliseconds).

Returns:

Information about each take found. Empty list if none found.

Return type:

list[TakeResponse]

get_voice(voice_id: str) → VoiceInfo¶

Get information about a voice.

Parameters:: voice_id – The unique identififer for a voice.
Returns:: Information about the voice.
Return type:: VoiceInfo

get_voices(length: int | None = None, page: int | None = None, older: int | None = None, newer: int | None = None) → list[VoiceInfo]¶

Get a list of voices, optionally filtered.

Parameters:

length – Maximum number of voices to return. Default: unlimited.
page – Return page “page” of length “length”. Default: 1.
older – Find voices older than or equal to this timestamp (milliseconds).
newer – Find voices newer than or equal to this timestamp (milliseconds).

Returns:

Information about each voice found.

Return type:

list[VoiceInfo]

login(email: str | None = None, password: str | None = None) → bool¶

If successful, nothing is returned. An access token is stored in the client for use in future requests. May raise:

DaisysCredentialsError: if insufficient credentials are provided.

httpx.HTTPStatusError(401): if credentials do not successfully authenticate.

Parameters:

email – User name for the Daisys API credentials.
password – Password for the Daisys API credentials.

login_refresh() → bool | None¶

Refresh access and refresh tokens for API authorization. This function does not normally need to be called explicitly, since the authorization credentials shall be renewed automatically when needed, however it is provided in case there is a need to do so explicitly by the user.

httpx.HTTPStatusError(401): if credentials do not successfully authenticate.

Returns:

True if successful, False if unsuccessful, and None if no refresh: token was available.

Return type:

Optional[bool]

logout(refresh_token: str | None = None) → bool¶

Log out of the Daisys API. Revokes the refresh token and and forgets the access and refresh tokens.

httpx.HTTPStatusError(401): if credentials do not successfully authenticate.

Note that further requests may auto-login again.

Returns:: True if logout was successful, False if no tokens were provided to revoke.
Return type:: bool

stream_take_audio(take_id: str)¶

Stream the audio by providing an iterator over chunks of bytes.

Parameters:: take_id – A take_id to retrieve the audio URL for.
Returns:: use “for” to read chunks of bytes for this take.
Return type:: iterator

Update a voice.

Parameters:

voice_id – the id of a voice to update.
name – A name to give the voice, may be any string, and does not need to be unique.
gender – The gender of this voice.
description – The description of this voice.
default_style – An optional list of styles to associate with this voice by default. It can be overriden by a take that uses this voice. Note that most styles are mutually exclusive, and not all models support styles.
default_prosody – An optional default prosody to associate with this voice. It can be overridden by a take that uses this voice.
raise_on_error – If True (default) a DaisysVoiceUpdateException error will be raised if the voice was not found. (That is, if the function would have returned False.)

Returns:

True if the voice was updated successfully, otherwise False.

Return type:

bool

Note that HTTP exceptions may be thrown for errors other than a voice not being found.

version() → Version¶

Get the version information for the API in use.

Returns:: An object containing version information.
Return type:: Version

Wait for a take or list of takes to be ready.

Parameters:

take_ids – Either a single take_id, or a list of take_id to wait for at the same time. In the latter case, the function will return when all take_id are done.
sleep_seconds – The number of seconds to wait while polling the take status.
callback – A synchronous function to call whenever the status of one of the takes changes. The argument it receives corresponds to a list of all takes requested. (A single take will also be embedded in a list.)
async_callback – An asynchronous function to call whenever the status of one of the takes changes. The argument it receives corresponds to a list of all takes requested.
raise_on_error – If True (default) a DaisysTakeGeenerateException error will be raised if an error status is detected in one of the takes. If this behavior is not desired, set to False.
timeout – Time limit to wait, in seconds. Note that if timeout is specified, some results may not have a “done” status (ready or error).

wait_for_voices(voice_ids: str | list[str], sleep_seconds: float = 0.5, raise_on_error: bool = True, timeout: float | None = None) → VoiceInfo | list[VoiceInfo]¶

Wait for a voice or list of voices to be ready.

Parameters:

voice_ids – Either a single voice_id, or a list of voice_id to wait for at the same time. In the latter case, the function will return when all voice_id are done.
sleep_seconds – The number of seconds to wait while polling the voice status.
raise_on_error – If True (default) a DaisysVoiceGeenerateException error will be raised if an error status is detected in one of the voices. If this behavior is not desired, set to False.
timeout – Time limit to wait, in seconds. Note that if timeout is specified, some results may not have a “done” status (ready or error).

websocket(model: str | None = None, voice_id: str | None = None) → DaisysSyncSpeakWebsocketV1¶

Get an interface to the websocket that manages the connection, allows making voice generate and take generate reqeusts, and handles streaming the resulting audio.

This provided interface is intended to be used in a with clause.

Parameters:

model – a websocket connection requires specifying a model or voice
voice_id – if model is not provided, voice_id must be provided

Returns:

DaisysSyncSpeakWebsocketV1

websocket_url(model: str | None = None, voice_id: str | None = None, raise_on_error: bool = True) → str¶

Get a URL for connecting a websocket. Must specify model or voice_id in order to indicate the principle model to be used on this connection.

Parameters:

model – the model for which we want to retrieve a websocket URL.
voice_id – the id of a voice for which we want to retrieve a websocket URL.
raise_on_error – If True (default) an error will be raised if the voice was not found or the URL could not be retrieved.

Returns:

The URL to connect a websocket to.

Return type:

str

class daisys.v1.speak.async_client.DaisysAsyncSpeakClientV1(auth_url: str, product_url: str, email: str, password: str, access_token: str, refresh_token: str)¶

Wrapper for Daisys v1 API endpoints, asynchronous version.

async close()¶: To be called when object is destroyed, to ensure any open HTTP connections are cleanly closed. This is done automatically if the client was created through a context manager.

async delete_take(take_id: str, raise_on_error: bool = True) → bool¶

Delete a take. The take will no longer appear in return values from get_takes.

Parameters:

take_id – the id of a take to delete.
raise_on_error – If True (default) a DaisysTakeDeletionException error will be raised if the take was not found. (That is, if the function would have returned False.)

Returns:

True if the take was deleted successfully, otherwise False.

Return type:

bool

Note that HTTP exceptions may be thrown for errors other than a take not being found.

async delete_voice(voice_id: str, raise_on_error: bool = True) → bool¶

Delete a voice. The voice will no longer appear in return values from get_voices.

Parameters:

voice_id – the id of a voice to delete.
raise_on_error – If True (default) a DaisysVoiceDeletionException error will be raised if the voice was not found. (That is, if the function would have returned False.)

Returns:

True if the voice was deleted successfully, otherwise False.

Return type:

bool

Note that HTTP exceptions may be thrown for errors other than a voice not being found.

Generate a “take”, an audio file containing an utterance of the given text by the given voice.

Parameters:

voice_id – The id of the voice to be used for generating audio. The voice is attached to a specific model.
text – The text that the voice should say.
override_language – Normally a language classifier is used to detect the language of the speech; this allows for multilingual sentences. However, if the language should be enforced, it should be provided here. Currently accepted values are “nl-NL” and “en-GB”.
style – A list of styles to enable when speaking. Note that most styles are mutually exclusive, so a list of 1 value should be provided. Accepted styles can be retrieved from the associated voice’s VoiceInfo.styles or the model’s TTSModel.styles field. Note that not all models support styles, thus this can be left empty if specific styles are not desired.
prosody – The characteristics of the desired speech not determined by the voice or style. Here you can provide a SimpleProsody or most models also accept the more detailed AffectProsody.
status_webhook – An optional URL to be called using POST whenever the take’s status changes, with TakeResponse in the body content.
done_webhook – An optional URL to be called exactly once using POST when the take is READY, ERROR, or TIMEOUT, with TakeResponse in the body content.
wait – if True, wait for take to be ready before returning.
raise_on_error – If True (default) a DaisysTakeGeenerateException error will be raised. If this behavior is not desired, set to False.
timeout – Time limit to wait, in seconds. Note that if timeout is specified, some results may not have a “done” status (ready or error).

Returns:

Information about the take being generated, including status.

Return type:

TakeResponse

async generate_takes(request: list[TakeGenerate], wait: bool = True, raise_on_error: bool = True, timeout: float | None = None) → list[TakeResponse]¶

Generate several “takes”, each corresponding to an audio file containing an utterance of the given text by the given voice.

Parameters:

request – a list of list[TakeGenerate] objects describing multiple take generation requests.
wait – if True, wait for all takes to be ready before returning.
raise_on_error – If True (default) a DaisysTakeGeenerateException error will be raised. If this behavior is not desired, set to False.
timeout – Time limit to wait, in seconds. Note that if timeout is specified, some results may not have a “done” status (ready or error).

Returns:

a list of TakeResponse objects containing information on the generation status of each result.

Return type:

list[TakeResponse]

Generate a random, novel voice for a given model with desired properties.

Parameters:

name – A name to give the voice, may be any string, and does not need to be unique.
model – The name of the model for this voice.
gender – The gender of this voice.
description – The description of this voice.
default_style – An optional list of styles to associate with this voice by default. It can be overriden by a take that uses this voice. Note that most styles are mutually exclusive, and not all models support styles.
default_prosody – An optional default prosody to associate with this voice. It can be overridden by a take that uses this voice.
example_take – Information on the take to generate as an example of this voice.
done_webhook – An optional URL to call exactly once using POST when the voice is available, with VoiceInfo in the body content.
wait – True to wait for the result, or False to continue without waiting.
raise_on_error – If True (default) a DaisysVoiceGenerateException error will be raised if an error status is detected in one of the takes. If this behavior is not desired, set to False.
timeout – Time limit to wait, in seconds. Note that if timeout is specified, some results may not have a “done” status (ready or error).

Returns:

Information about the generated voice.

Return type:

VoiceInfo

async get_model(model_name: str) → TTSModel¶

Get information about a model.

Parameters:: model_name – The name of the model, which is a unique identifier.
Returns:: Information about the model.
Return type:: TTSModel

async get_models() → list[TTSModel]¶

Get information about all available models.

Returns:: Information about each model.
Return type:: list[TTSModel]

async get_take(take_id: str) → TakeResponse¶

Get information about a specific take.

Parameters:: take_id – Unique identifier for a take.
Returns:: Information about the requested take.
Return type:: TakeResponse

async get_take_audio(take_id: str, file: str | None = None, format: str = 'wav') → bytes¶

Get audio associated with a take.

Parameters:

take_id – A take_id to retrieve the audio for.
file – Optionally, the filename of a file to write, or a file stream to write to.
format – A supported format, must be one of ‘wav’, ‘mp3’, ‘flac’, ‘m4a’. Note: only ‘wav’ may be retrieved without waiting for ‘ready’ status.

Returns:

The content of the audio file associated with the requested take.

Return type:

bytes

async get_take_audio_url(take_id: str, format: str = 'wav') → str¶

Get the signed URL for audio associated with a take. May be used to provide the URL to a download or streaming client that does not have the API access token.

Parameters:

take_id – A take_id to retrieve the audio URL for.
format – A supported format, msut be one of ‘wav’, ‘mp3’, ‘flac’, ‘m4a’. Note: only ‘wav’ may be retrieved without waiting for ‘ready’ status.

Returns:

The URL that can be used to download the content of the: audio associated with the requested take.

Return type:

str

Get a list of takes, optionally filtered.

Parameters:

take_ids – A list of specific takes to retrieve.
length – Maximum number of voices to return. Default: unlimited.
page – Return page “page” of length “length”. Default: 1.
older – Find voices older than or equal to this timestamp (milliseconds).
newer – Find voices newer than or equal to this timestamp (milliseconds).

Returns:

Information about each take found. Empty list if none found.

Return type:

list[TakeResponse]

async get_voice(voice_id: str) → VoiceInfo¶

Get information about a voice.

Parameters:: voice_id – The unique identififer for a voice.
Returns:: Information about the voice.
Return type:: VoiceInfo

async get_voices(length: int | None = None, page: int | None = None, older: int | None = None, newer: int | None = None) → list[VoiceInfo]¶

Get a list of voices, optionally filtered.

Parameters:

length – Maximum number of voices to return. Default: unlimited.
page – Return page “page” of length “length”. Default: 1.
older – Find voices older than or equal to this timestamp (milliseconds).
newer – Find voices newer than or equal to this timestamp (milliseconds).

Returns:

Information about each voice found.

Return type:

list[VoiceInfo]

async login(email: str | None = None, password: str | None = None) → bool¶

If successful, nothing is returned. An access token is stored in the client for use in future requests. May raise:

DaisysCredentialsError: if insufficient credentials are provided.

httpx.HTTPCStatusError(401): if credentials do not successfully authenticate.

Parameters:

email – User name for the Daisys API credentials.
password – Password for the Daisys API credentials.

async login_refresh() → bool | None¶

httpx.HTTPStatusError(401): if credentials do not successfully authenticate.

Returns:

True if successful, False if unsuccessful, and None if no refresh: token was available.

Return type:

Optional[bool]

async logout(refresh_token: str | None = None) → bool¶

Log out of the Daisys API. Revokes the refresh token and and forgets the access and refresh tokens.

httpx.HTTPStatusError(401): if credentials do not successfully authenticate.

Note that further requests may auto-login again.

Returns:: True if logout was successful, False if no tokens were provided to revoke.
Return type:: bool

stream_take_audio(take_id: str)¶

Stream the audio by providing an iterator over chunks of bytes.

Parameters:: take_id – A take_id to retrieve the audio URL for.
Returns:: use “for” to read chunks of bytes for this take.
Return type:: iterator

Update a voice. The voice will no longer appear in return values from get_voices.

Parameters:

voice_id – the id of a voice to update.
name – A name to give the voice, may be any string, and does not need to be unique.
gender – The gender of this voice.
description – The description of this voice.
default_style – An optional list of styles to associate with this voice by default. It can be overriden by a take that uses this voice. Note that most styles are mutually exclusive, and not all models support styles.
default_prosody – An optional default prosody to associate with this voice. It can be overridden by a take that uses this voice.
raise_on_error – If True (default) a DaisysVoiceUpdateException error will be raised if the voice was not found. (That is, if the function would have returned False.)

Returns:

True if the voice was updated successfully, otherwise False.

Return type:

bool

Note that HTTP exceptions may be thrown for errors other than a voice not being found.

async version() → Version¶

Get the version information for the API in use.

Returns:: An object containing version information.
Return type:: Version

async wait_for_takes(take_ids: str | list[str], sleep_seconds=0.5, callback: Callable[[TakeResponse | list[TakeResponse]], None] | None = None, async_callback: Callable[[TakeResponse | list[TakeResponse]], Awaitable[None]] | None = None, raise_on_error: bool = True, timeout: float | None = None) → TakeResponse | list[TakeResponse]¶

Wait for a take or list of takes to be ready.

Parameters:

take_ids – Either a single take_id, or a list of take_id to wait for at the same time. In the latter case, the function will return when all take_id are done.
sleep_seconds – The number of seconds to wait while polling the take status.
callback – A synchronous function to call whenever the status of one of the takes changes. The argument it receives corresponds to a list of all takes requested. (A single take will also be embedded in a list.)
async_callback – An asynchronous function to call whenever the status of one of the takes changes. The argument it receives corresponds to a list of all takes requested.
raise_on_error – If True (default) a DaisysTakeGeenerateException error will be raised if an error status is detected in one of the takes. If this behavior is not desired, set to False.
timeout – Time limit to wait, in seconds. Note that if timeout is specified, some results may not have a “done” status (ready or error).

async wait_for_voices(voice_ids: str | list[str], sleep_seconds: float = 0.5, raise_on_error: bool = True, timeout: float | None = None) → VoiceInfo | list[VoiceInfo]¶

Wait for a voice or list of voices to be ready.

Parameters:

voice_ids – Either a single voice_id, or a list of voice_id to wait for at the same time. In the latter case, the function will return when all voice_id are done.
sleep_seconds – The number of seconds to wait while polling the voice status.
raise_on_error – If True (default) a DaisysVoiceGeenerateException error will be raised if an error status is detected in one of the voices. If this behavior is not desired, set to False.
timeout – Time limit to wait, in seconds. Note that if timeout is specified, some results may not have a “done” status (ready or error).

websocket(model: str | None = None, voice_id: str | None = None) → DaisysAsyncSpeakWebsocketV1¶

Get an interface to the websocket that manages the connection, allows making voice generate and take generate reqeusts, and handles streaming the resulting audio.

This provided interface is intended to be used in an async with clause.

Parameters:

model – a websocket connection requires specifying a model or voice
voice_id – if model is not provided, voice_id must be provided

Returns:

DaisysAsyncSpeakWebsocketV1

async websocket_url(model: str | None = None, voice_id: str | None = None, raise_on_error: bool = True) → str¶

Get a URL for connecting a websocket. Must specify model or voice_id in order to indicate the principle model to be used on this connection.

Parameters:

model – the model for which we want to retrieve a websocket URL.
voice_id – the id of a voice for which we want to retrieve a websocket URL.
raise_on_error – If True (default) an error will be raised if the voice was not found or the URL could not be retrieved.

Returns:

The URL to connect a websocket to.

Return type:

str