Skip to content

reference.md

Latest commit

 

History

History
729 lines (510 loc) · 12.5 KB

reference.md

File metadata and controls

729 lines (510 loc) · 12.5 KB
Raw

Reference

audio

client.audio.speech(...) -> GetSpeechResponse

📝 Description

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. Set output_format for explicit sample-rate/bitrate control (e.g. pcm_16000 or ulaw_8000 for telephony).

🔌 Usage

from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

client = Speechify(
    token="<token>",
    environment=SpeechifyEnvironment.DEFAULT,
)

client.audio.speech(
    audio_format="mp3",
    input="Hello! This is the Speechify text-to-speech API.",
    model="simba-english",
    voice_id="george",
)

⚙️ 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.2 is the streaming-native model with lower TTFB and richer expressivity, and the recommended Simba 3 model. simba-3.0 is the earlier Simba 3.0 model, still available. simba-3.0 and simba-3.2 are currently English only; multilingual coming soon, and non-English voices return 400 until it ships.

options: typing.Optional[GetSpeechOptionsRequest]

output_format: typing.Optional[AudioOutputFormat] — The output audio format as a codec_sampleRate_bitrate string. Takes precedence over audio_format when set.

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

client.audio.stream(...) -> typing.Iterator[bytes]

📝 Description

Synthesize speech and stream the audio back as it is generated, for low-latency playback. Set output_format in the body for explicit codec/sample-rate/bitrate control (e.g. pcm_16000 or ulaw_8000 for telephony), or fall back to the Accept header for the 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.

🔌 Usage

from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

client = Speechify(
    token="<token>",
    environment=SpeechifyEnvironment.DEFAULT,
)

client.audio.stream(
    input="input",
    voice_id="voice_id",
)

⚙️ 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

accept: typing.Optional[StreamAudioRequestAccept]

Selects the audio container/codec for the streamed response when output_format is not set in the request body. 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). For explicit sample-rate/bitrate control (e.g. pcm_16000, ulaw_8000), set output_format in the body instead; it takes precedence over this header.

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.2 is the streaming-native model with lower TTFB and richer expressivity, and the recommended Simba 3 model. simba-3.0 is the earlier Simba 3.0 model, still available. simba-3.0 and simba-3.2 are currently English only; multilingual coming soon, and non-English voices return 400 until it ships.

options: typing.Optional[GetStreamOptionsRequest]

output_format: typing.Optional[AudioStreamOutputFormat] — The output audio format as a codec_sampleRate_bitrate string. Takes precedence over the Accept header when set, so you can request formats the Accept enum does not cover (e.g. pcm_16000, ulaw_8000). wav_* formats are not supported on streaming - use POST /v1/audio/speech for wav.

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

voices

client.voices.list(...) -> ListVoicesResponse

📝 Description

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.

🔌 Usage

from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

client = Speechify(
    token="<token>",
    environment=SpeechifyEnvironment.DEFAULT,
)

client.voices.list()

⚙️ 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.

client.voices.create(...) -> GetVoice

📝 Description

Create a personal (cloned) voice for the user

🔌 Usage

from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

client = Speechify(
    token="<token>",
    environment=SpeechifyEnvironment.DEFAULT,
)

client.voices.create(
    idempotency_key="a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    sample="example_sample",
    avatar="example_avatar",
    name="name",
    gender="male",
    consent="consent",
)

⚙️ 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 — Audio sample file

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] — Avatar image file

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

client.voices.get(...) -> GetVoice

📝 Description

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.

🔌 Usage

from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

client = Speechify(
    token="<token>",
    environment=SpeechifyEnvironment.DEFAULT,
)

client.voices.get(
    voice_id="voice_id",
)

⚙️ Parameters

voice_id: str — The ID of the voice to fetch

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

client.voices.delete(...)

📝 Description

Delete a personal (cloned) voice

🔌 Usage

from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

client = Speechify(
    token="<token>",
    environment=SpeechifyEnvironment.DEFAULT,
)

client.voices.delete(
    voice_id="voice_id",
)

⚙️ Parameters

voice_id: str — The ID of the voice to delete

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

client.voices.download_sample(...) -> typing.Iterator[bytes]

📝 Description

Download a personal (cloned) voice sample

🔌 Usage

from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

client = Speechify(
    token="<token>",
    environment=SpeechifyEnvironment.DEFAULT,
)

client.voices.download_sample(
    voice_id="voice_id",
)

⚙️ Parameters

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

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