Implementation:Elevenlabs Elevenlabs python AudioNativeClient

Knowledge Sources	Elevenlabs_Elevenlabs_python
Domains	Audio, API_Client, Embeddable_Player
Last Updated	2026-02-15 12:00 GMT

Overview

Concrete API client for managing Audio Native embeddable player projects provided by the ElevenLabs Python SDK.

Description

The AudioNativeClient wraps the ElevenLabs Audio Native API endpoints, enabling programmatic creation and management of embeddable audio player projects. Audio Native allows content publishers to embed a text-to-speech player widget on their websites that converts written articles or content into spoken audio. The client provides three core operations:

• create - Creates an Audio Native enabled project via POST /v1/audio-native. This initializes a new embeddable player project, optionally starts conversion of the content to audio, and returns the project ID along with an embeddable HTML snippet for integration into web pages.
• get_settings - Retrieves player settings for a specific project via GET /v1/audio-native/{project_id}/settings. Returns configuration details such as voice, model, colors, and other player customizations.
• update - Updates the content for an existing Audio Native project via POST /v1/audio-native/{project_id}/content. Allows uploading a new file and optionally triggering auto-conversion and auto-publishing.

Both synchronous (AudioNativeClient) and asynchronous (AsyncAudioNativeClient) variants are provided. The raw HTTP response can be accessed via the with_raw_response property.

Usage

Use this client when you need to:

• Create embeddable audio players for website content (articles, blog posts, documentation).
• Customize the appearance and voice of an Audio Native player.
• Retrieve current player settings for an existing project.
• Update the content of an existing Audio Native project with new text or files.

Code Reference

Source Location

• Repository: Elevenlabs_Elevenlabs_python
• File (high-level): src/elevenlabs/audio_native/client.py
• File (raw): src/elevenlabs/audio_native/raw_client.py
• Lines: 18-223 (AudioNativeClient), 226-455 (AsyncAudioNativeClient)

Signature

class AudioNativeClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper): ...

    @property
    def with_raw_response(self) -> RawAudioNativeClient: ...

    def create(
        self,
        *,
        name: str,
        image: typing.Optional[str] = OMIT,
        author: typing.Optional[str] = OMIT,
        title: typing.Optional[str] = OMIT,
        small: typing.Optional[bool] = OMIT,
        text_color: typing.Optional[str] = OMIT,
        background_color: typing.Optional[str] = OMIT,
        sessionization: typing.Optional[int] = OMIT,
        voice_id: typing.Optional[str] = OMIT,
        model_id: typing.Optional[str] = OMIT,
        file: typing.Optional[core.File] = OMIT,
        auto_convert: typing.Optional[bool] = OMIT,
        apply_text_normalization: typing.Optional[AudioNativeCreateRequestApplyTextNormalization] = OMIT,
        pronunciation_dictionary_locators: typing.Optional[typing.List[str]] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AudioNativeCreateProjectResponseModel: ...

    def get_settings(
        self,
        project_id: str,
        *,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> GetAudioNativeProjectSettingsResponseModel: ...

    def update(
        self,
        project_id: str,
        *,
        file: typing.Optional[core.File] = OMIT,
        auto_convert: typing.Optional[bool] = OMIT,
        auto_publish: typing.Optional[bool] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AudioNativeEditContentResponseModel: ...

Import

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
# Access via client.audio_native

I/O Contract

create()

Inputs

Name	Type	Required	Description
name	str	Yes	Project name.
image	Optional[str]	No	(Deprecated) Image URL used in the player. Falls back to Player settings default.
author	Optional[str]	No	Author displayed in the player and inserted at the start of the uploaded article. Falls back to Player settings default.
title	Optional[str]	No	Title displayed in the player and inserted at the top of the uploaded article. Falls back to Player settings default.
small	Optional[bool]	No	(Deprecated) Whether to use the small player variant. Falls back to Player settings default.
text_color	Optional[str]	No	Text color used in the player. Falls back to Player settings default.
background_color	Optional[str]	No	Background color used in the player. Falls back to Player settings default.
sessionization	Optional[int]	No	(Deprecated) Minutes to persist the session across page reloads. Falls back to Player settings default.
voice_id	Optional[str]	No	Voice ID used to voice the content. Falls back to Player settings default.
model_id	Optional[str]	No	TTS Model ID used in the player. Falls back to Player settings default.
file	Optional[core.File]	No	File to upload as content for the project.
auto_convert	Optional[bool]	No	Whether to auto-convert the project to audio.
apply_text_normalization	Optional[AudioNativeCreateRequestApplyTextNormalization]	No	Controls text normalization. Modes: 'auto', 'on', 'apply_english', 'off'.
pronunciation_dictionary_locators	Optional[List[str]]	No	JSON-encoded pronunciation dictionary locators to apply to the text.
request_options	Optional[RequestOptions]	No	Request-specific configuration.

Output

Name	Type	Description
return	AudioNativeCreateProjectResponseModel	Contains the project ID and embeddable HTML snippet for the created Audio Native project.

get_settings()

Inputs

Name	Type	Required	Description
project_id	str	Yes	The ID of the Studio project.
request_options	Optional[RequestOptions]	No	Request-specific configuration.

Output

Name	Type	Description
return	GetAudioNativeProjectSettingsResponseModel	The player settings for the specified project.

update()

Inputs

Name	Type	Required	Description
project_id	str	Yes	The ID of the project to update.
file	Optional[core.File]	No	New file content to upload.
auto_convert	Optional[bool]	No	Whether to auto-convert the project to audio after update.
auto_publish	Optional[bool]	No	Whether to auto-publish the new project snapshot after conversion.
request_options	Optional[RequestOptions]	No	Request-specific configuration.

Output

Name	Type	Description
return	AudioNativeEditContentResponseModel	Response confirming the content update for the Audio Native project.

API Endpoints

Method	HTTP Verb	Endpoint
create	POST	/v1/audio-native
get_settings	GET	/v1/audio-native/{project_id}/settings
update	POST	/v1/audio-native/{project_id}/content

Error Handling

All methods may raise:

• UnprocessableEntityError (HTTP 422) - When the request body fails validation. The error body is typed as HttpValidationError.
• ApiError - For any other non-2xx HTTP status codes.

Usage Examples

Creating an Audio Native Project

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
response = client.audio_native.create(
    name="My Blog Post",
    title="Introduction to AI",
    author="Jane Doe",
    voice_id="21m00Tcm4TlvDq8ikWAM",
    auto_convert=True,
)
# response.project_id - the created project ID
# response.html - embeddable HTML snippet

Retrieving Project Settings

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
settings = client.audio_native.get_settings(
    project_id="21m00Tcm4TlvDq8ikWAM",
)

Updating Project Content

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
result = client.audio_native.update(
    project_id="21m00Tcm4TlvDq8ikWAM",
    auto_convert=True,
    auto_publish=True,
)

Async Usage

import asyncio
from elevenlabs import AsyncElevenLabs

client = AsyncElevenLabs(api_key="YOUR_API_KEY")

async def main() -> None:
    response = await client.audio_native.create(name="My Async Project")

asyncio.run(main())

Related Pages

• Environment:Elevenlabs_Elevenlabs_python_Python_Httpx