SpeechifyAI Python SDK

https://github.com/speechify-ai/sdk-python
Admin
The SpeechifyAI Python SDK provides convenient access to SpeechifyAI text-to-speech and voice...
Tokens:7,273
Snippets:97
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install project dependencies

Source: https://github.com/speechify-ai/sdk-python/blob/main/CONTRIBUTING.md

Use Poetry to install all required project dependencies.

```bash
poetry install
```

--------------------------------

### Install Speechify SDK

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Install the library using pip.

```sh
pip install speechify-api
```

--------------------------------

### client.voices.consent_challenges.create

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Starts the consent check for a voice clone. Returns a phrase for the speaker to read and an ID for verification.

```APIDOC
## client.voices.consent_challenges.create

### Description
Starts the consent check for a voice clone. Returns a `phrase` for the speaker to read aloud and an `id` that identifies this challenge. This challenge is single-use and expires, so it should be created only when the speaker is ready to record.

### Parameters
- **full_name** (str) - Required - Full name of the person consenting to have their voice cloned. Max 120 bytes.
- **idempotency_key** (str) - Optional - A client-generated key to make the request safe to retry.
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Usage Example
```python
from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

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

client.voices.consent_challenges.create(
    idempotency_key="a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    full_name="Jane Doe",
)
```
```

--------------------------------

### Build the project

Source: https://github.com/speechify-ai/sdk-python/blob/main/CONTRIBUTING.md

Build the project using Poetry.

```bash
poetry build
```

--------------------------------

### Initialize and Use Async Client

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Demonstrates non-blocking API calls using the AsyncSpeechify client.

```python
import asyncio

from speechify import AsyncSpeechify

client = AsyncSpeechify(
    token="<token>",
)


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


asyncio.run(main())
```

--------------------------------

### Initialize and Use Speechify Client

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Instantiate the client with an API token and perform a text-to-speech request.

```python
from speechify import Speechify

client = Speechify(
    token="<token>",
)

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

--------------------------------

### Verify User-Agent and SDK Version headers

Source: https://github.com/speechify-ai/sdk-python/blob/main/AGENTS.md

Check the header definitions in the client wrapper to ensure they match the expected format for the stamp step.

```python
"User-Agent": "speechify-api/<semver>",
"X-Fern-SDK-Version": "<semver>",
```

--------------------------------

### Search for header patterns in client wrapper

Source: https://github.com/speechify-ai/sdk-python/blob/main/AGENTS.md

Use grep to locate the specific header keys within the client wrapper file to verify their presence and structure.

```bash
grep -nE '"(User-Agent|X-Fern-SDK-Version)":' src/speechify/core/client_wrapper.py
```

--------------------------------

### client.voices.download_sample

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Downloads a sample audio file for a specific personal (cloned) voice.

```APIDOC
## client.voices.download_sample

### Description
Download a personal (cloned) voice sample.

### Parameters
- **voice_id** (str) - Required - The ID of the voice to download sample for
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.
```

--------------------------------

### Stream audio with timestamps in Python

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Initializes the Speechify client and streams audio with word-level speech marks using the simba-3.2 model.

```python
from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

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

client.audio.stream_with_timestamps(
    input="Streaming long-form audio with the Speechify API.",
    model="simba-3.2",
    voice_id="geffen_32",
)
```

--------------------------------

### Run the test suite

Source: https://github.com/speechify-ai/sdk-python/blob/main/CONTRIBUTING.md

Execute the project's test suite using pytest via Poetry.

```bash
poetry run pytest
```

--------------------------------

### Lint and format code

Source: https://github.com/speechify-ai/sdk-python/blob/main/CONTRIBUTING.md

Check code style and apply formatting using ruff.

```bash
poetry run ruff check .
poetry run ruff format .
```

--------------------------------

### client.voices.create

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Creates a cloned voice for the workspace from an audio sample, requiring a consent challenge recording.

```APIDOC
## client.voices.create

### Description
Creates a cloned voice for the workspace from a 10-30 second audio sample, with verified consent from the speaker. Requires a consent challenge ID and a recording of the speaker reading the challenge phrase.

### Parameters
- **name** (str) - Required - Name of the personal voice
- **gender** (CreateVoicesRequestGender) - Required - Gender marker (male, female, not_specified)
- **sample** (core.File) - Required - Audio sample of the voice to clone (10-30 seconds)
- **consent_challenge_id** (str) - Required - The ID of the consent challenge from POST /v1/voices/consent-challenges
- **consent_recording** (core.File) - Required - Recording of the speaker reading the challenge phrase
- **idempotency_key** (str) - Optional - Client-generated key for safe retries
- **locale** (str) - Optional - Native language of the voice
- **avatar** (core.File) - Optional - Avatar image file
- **request_options** (RequestOptions) - Optional - Request-specific configuration
```

--------------------------------

### Audit version literals

Source: https://github.com/speechify-ai/sdk-python/blob/main/AGENTS.md

Use this command to quickly verify the current version strings across the primary configuration and source files.

```bash
grep -rnE '[0-9]+\.[0-9]+\.[0-9]+' \
  pyproject.toml src/speechify/core/client_wrapper.py .fern/metadata.json
```

--------------------------------

### Create a voice consent challenge

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Initializes the Speechify client and triggers a consent challenge for a specific speaker. Ensure the speaker is ready to record immediately after receiving the challenge phrase.

```python
from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

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

client.voices.consent_challenges.create(
    idempotency_key="a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    full_name="Jane Doe",
)
```

--------------------------------

### List resources with pagination

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Use the client to list resources, which returns a pager object for iterating through results.

```python
from speechify import Speechify

client = Speechify(
    token="<token>",
)

client.voices.list(
    locale="en",
    model="simba-3.2",
)
```

--------------------------------

### client.models.list()

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Retrieves the list of available text-to-speech models for synthesis. This includes information on default models, supported routes, and compatible voices.

```APIDOC
## client.models.list()

### Description
List the text-to-speech models available for synthesis. The response includes the default model, supported routes, and accepted voices.

### Parameters
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.
```

--------------------------------

### Configure Speechify Environment

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Sets the API environment using the Speechify client constructor.

```python
from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

client = Speechify(
    environment=SpeechifyEnvironment.DEFAULT,
)
```

--------------------------------

### List available text-to-speech models

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Retrieves the full catalog of available text-to-speech models. Use the returned model IDs for synthesis requests.

```python
from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

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

client.models.list()
```

--------------------------------

### Download a voice sample

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Retrieves a personal cloned voice sample as an iterator of bytes.

```python
from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

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

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

--------------------------------

### Customize the HTTP client

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Override the default httpx client to support custom proxies or transports.

```python
import httpx
from speechify import Speechify

client = Speechify(
    ...,
    httpx_client=httpx.Client(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)
```

--------------------------------

### Run type checking

Source: https://github.com/speechify-ai/sdk-python/blob/main/CONTRIBUTING.md

Perform static type checking on the project using mypy.

```bash
poetry run mypy .
```

--------------------------------

### Retrieve Voice Details

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Fetches information for a specific voice by its ID. Returns 404 if the voice is unknown or belongs to a different workspace.

```python
from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

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

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

--------------------------------

### Create a Cloned Voice

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Creates a new voice clone using an audio sample and a verified consent recording. Requires a valid consent challenge ID obtained from the consent challenge endpoint.

```python
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",
    consent_recording="example_consent_recording",
    name="name",
    gender="male",
    consent_challenge_id="consent_challenge_id",
)
```

--------------------------------

### client.voices.list()

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Lists the voices available to the caller, including the shared catalog and workspace-specific cloned voices, with support for filtering and pagination.

```APIDOC
## client.voices.list()

### Description
Lists the voices available to the caller. Supports pagination via cursor and limit, and filtering by type, locale, gender, and model.

### Parameters
- **cursor** (typing.Optional[str]) - Optional - Opaque pagination cursor from a previous response.
- **limit** (typing.Optional[int]) - Optional - Max items per page (default 50, max 200).
- **type** (typing.Optional[ListVoicesRequestType]) - Optional - Filter by voice type: 'personal' or 'shared'.
- **locale** (typing.Optional[str]) - Optional - Filter by BCP-47 language range.
- **gender** (typing.Optional[ListVoicesRequestGender]) - Optional - Filter by voice gender.
- **model** (typing.Optional[str]) - Optional - Filter to voices that support a specific model.
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.
```

--------------------------------

### Configure request timeouts

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Set timeouts at the client level or override them for specific method calls.

```python
from speechify import Speechify

client = Speechify(..., timeout=20.0)

# Override timeout for a specific method
client.audio.speech(..., request_options={
    "timeout_in_seconds": 1
})
```

--------------------------------

### client.audio.stream

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Synthesize speech and stream the audio back as it is generated, for low-latency playback.

```APIDOC
## client.audio.stream(...)

### Description
Synthesize speech and stream the audio back as it is generated, for low-latency playback. Set `output_format` for explicit codec/sample-rate/bitrate control, or fall back to the Accept header for the container; the response is raw audio bytes (HTTP chunked).
```

--------------------------------

### Synthesize speech with client.audio.speech

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Synthesizes text or SSML into audio. Use this for complete audio files with metadata, or use the stream method for low-latency requirements.

```python
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-3.2",
    voice_id="geffen_32",
)
```

--------------------------------

### Stream audio with client.audio.stream

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Streams audio bytes as they are generated for low-latency playback. Returns raw audio bytes via HTTP chunked transfer.

```python
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",
)
```

--------------------------------

### client.voices.get

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Fetches a single voice by ID, including shared catalogue voices or workspace-specific cloned voices.

```APIDOC
## client.voices.get

### Description
Fetch a single voice by ID. Returns 404 if the voice is unknown or belongs to another workspace.

### Parameters
- **voice_id** (str) - Required - The unique identifier of the voice to retrieve
```

--------------------------------

### client.audio.stream_with_timestamps

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Synthesize speech and stream it back together with word-level speech marks for text highlighting and synchronization. The response is a Server-Sent Events stream containing Base64-encoded audio chunks and speech marks.

```APIDOC
## client.audio.stream_with_timestamps

### Description
Synthesize speech and stream it back together with word-level speech marks, for text highlighting, captions and audio-text synchronization while the audio is still arriving. The response is a Server-Sent Events stream.

### Parameters
- **request** (GetStreamRequest) - Required - The request configuration object.
- **accept** (StreamWithTimestampsAudioRequestAccept) - Optional - Selects the audio container/codec carried inside the events when output_format is not set in the request body.
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Usage Example
```python
from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

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

client.audio.stream_with_timestamps(
    input="Streaming long-form audio with the Speechify API.",
    model="simba-3.2",
    voice_id="geffen_32",
)
```
```

--------------------------------

### Stream Audio Responses

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Uses the stream_with_timestamps method to receive audio as a generator.

```python
from speechify import Speechify

client = Speechify(
    token="<token>",
)

client.audio.stream_with_timestamps(
    input="Streaming long-form audio with the Speechify API.",
    model="simba-3.2",
    voice_id="geffen_32",
)
```

--------------------------------

### client.audio.speech

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Synthesize speech audio from text or SSML. Returns the complete audio file plus billing and speech-mark metadata in a single JSON response.

```APIDOC
## client.audio.speech(...)

### 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.

### Parameters
- **input** (str) - Required - Plain text or SSML to be synthesized to speech.
- **voice_id** (str) - Required - Id of the voice to be used for synthesizing speech.
- **audio_format** (GetSpeechRequestAudioFormat) - Optional - The format for the output audio.
- **language** (str) - Optional - Language of the input (ISO 639-1 and ISO 3166-1).
- **model** (GetSpeechRequestModel) - Optional - Model used for audio synthesis.
- **options** (GetSpeechOptionsRequest) - Optional - Additional options.
- **output_format** (AudioOutputFormat) - Optional - The output audio format as a codec_sampleRate_bitrate string.
- **request_options** (RequestOptions) - Optional - Request-specific configuration.
```

--------------------------------

### List available voices

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Retrieves a list of available voices, supporting filters for locale, model, and voice type. Pagination is available via limit and cursor parameters.

```python
from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

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

client.voices.list(
    locale="en",
    model="simba-3.2",
)
```

--------------------------------

### client.audio.with_raw_response.speech

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Accesses the raw HTTP response for the speech generation endpoint, including headers and status codes.

```APIDOC
## client.audio.with_raw_response.speech

### Description
Provides access to the raw response object for the speech generation request, allowing inspection of headers and status codes.

### Usage Example
```python
response = client.audio.with_raw_response.speech(...)
print(response.headers)
print(response.status_code)
print(response.data)
```
```

--------------------------------

### Access raw response data

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Access headers, status codes, and raw data using the with_raw_response property.

```python
from speechify import Speechify

client = Speechify(...)
response = client.audio.with_raw_response.speech(...)
print(response.headers)  # access the response headers
print(response.status_code)  # access the response status code
print(response.data)  # access the underlying object
```

--------------------------------

### Configure request retries

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Override the default retry limit for specific requests using the request_options parameter.

```python
client.audio.speech(..., request_options={
    "max_retries": 1
})
```

--------------------------------

### client.voices.list

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Retrieves a list of available voices. This method supports pagination and returns a Pager object that can be iterated.

```APIDOC
## client.voices.list

### Description
Retrieves a list of voices based on the provided locale and model filters. The result is a paginated response.

### Parameters
- **locale** (string) - Optional - The locale code (e.g., "en").
- **model** (string) - Optional - The model identifier (e.g., "simba-3.2").

### Usage Example
```python
from speechify import Speechify

client = Speechify(token="<token>")

pager = client.voices.list(locale="en", model="simba-3.2")
for page in pager.iter_pages():
    for item in page:
        print(item)
```
```

--------------------------------

### client.voices.delete

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Deletes a cloned voice from the workspace. Requires appropriate permissions or authorized service-account scopes.

```APIDOC
## client.voices.delete

### Description
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) - Required - The ID of the voice to delete
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.
```

--------------------------------

### Iterate through paginated responses

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Iterate through pages and access the typed response per page using the pager object.

```python
# You can also iterate through pages and access the typed response per page
pager = client.voices.list(...)
for page in pager.iter_pages():
    print(page.response)  # access the typed response for each page
    for item in page:
        print(item)
```

--------------------------------

### Delete a cloned voice

Source: https://github.com/speechify-ai/sdk-python/blob/main/reference.md

Removes a workspace's cloned voice. Requires content.manage permissions or appropriate service-account scopes.

```python
from speechify import Speechify
from speechify.environment import SpeechifyEnvironment

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

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

--------------------------------

### Handle API Exceptions

Source: https://github.com/speechify-ai/sdk-python/blob/main/README.md

Catches ApiError exceptions to access status codes and response bodies when requests fail.

```python
from speechify.core.api_error import ApiError

try:
    client.audio.speech(...)
except ApiError as e:
    print(e.status_code)
    print(e.body)
```
Tokens:
Raw