Jump to content

Connect SuperML | Leeroopedia MCP: Equip your AI agents with best practices, code verification, and debugging knowledge. Powered by Leeroo — building Organizational Superintelligence. Contact us at founders@leeroo.com.

Implementation:Elevenlabs Elevenlabs python StudioClient

From Leeroopedia
Knowledge Sources
Domains Audio, API_Client, Studio, Podcast
Last Updated 2026-02-15 12:00 GMT

Overview

Concrete API client for managing ElevenLabs Studio podcasts and projects provided by the ElevenLabs Python SDK.

Description

The StudioClient wraps the ElevenLabs Studio API endpoints, providing access to podcast creation and a nested projects sub-client for full Studio project lifecycle management. The Studio platform enables long-form audio content creation, including automated podcast generation and audiobook-style project management with chapters, snapshots, and pronunciation dictionaries.

The client provides one direct method and one sub-client property:

  • create_podcast - Creates and auto-converts a podcast project via POST /v1/studio/podcasts. Supports two podcast modes: 'conversation' (two-voice interaction) and 'bulletin' (monologue). Accepts content from text, URLs, or other sources. Provides control over quality presets, duration scaling, language, text normalization, and optional webhook callbacks for conversion status notifications.
  • projects (property) - Lazily-initialized sub-client (ProjectsClient) providing full CRUD operations for Studio projects. This includes listing, creating, retrieving, updating, deleting, and converting projects, as well as managing muted tracks. The projects sub-client further nests sub-clients for chapters, content, snapshots, and pronunciation dictionaries.

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

Usage

Use this client when you need to:

  • Generate podcast audio from text or URL sources with configurable voices and modes.
  • Create and manage long-form audio projects (audiobooks, articles, etc.) via the Studio platform.
  • Manage project lifecycle including creation, conversion to audio, and publishing.
  • Configure quality presets and duration for generated podcast content.
  • Receive webhook notifications about project conversion status.

Code Reference

Source Location

Signature

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

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

    def create_podcast(
        self,
        *,
        model_id: str,
        mode: BodyCreatePodcastV1StudioPodcastsPostMode,
        source: BodyCreatePodcastV1StudioPodcastsPostSource,
        safety_identifier: typing.Optional[str] = None,
        quality_preset: typing.Optional[BodyCreatePodcastV1StudioPodcastsPostQualityPreset] = OMIT,
        duration_scale: typing.Optional[BodyCreatePodcastV1StudioPodcastsPostDurationScale] = OMIT,
        language: typing.Optional[str] = OMIT,
        intro: typing.Optional[str] = OMIT,
        outro: typing.Optional[str] = OMIT,
        instructions_prompt: typing.Optional[str] = OMIT,
        highlights: typing.Optional[typing.Sequence[str]] = OMIT,
        callback_url: typing.Optional[str] = OMIT,
        apply_text_normalization: typing.Optional[BodyCreatePodcastV1StudioPodcastsPostApplyTextNormalization] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> PodcastProjectResponseModel: ...

    @property
    def projects(self) -> ProjectsClient: ...

Import

from elevenlabs import ElevenLabs

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

I/O Contract

create_podcast()

Inputs

Name Type Required Description
model_id str Yes The ID of the model to use for the podcast. Query GET /v1/models to list available models.
mode BodyCreatePodcastV1StudioPodcastsPostMode Yes Podcast type: 'conversation' (two-voice interaction) or 'bulletin' (monologue). Use discriminated union types such as BodyCreatePodcastV1StudioPodcastsPostMode_Conversation.
source BodyCreatePodcastV1StudioPodcastsPostSource Yes Source content for the podcast. Use typed sources such as PodcastTextSource.
safety_identifier Optional[str] No Used for moderation. Workspace must be allowlisted to use this feature. Sent as a custom HTTP header.
quality_preset Optional[...QualityPreset] No Output quality: 'standard' (128kbps), 'high' (192kbps), 'ultra' (192kbps enhanced), or 'ultra_lossless' (705.6kbps lossless).
duration_scale Optional[...DurationScale] No Duration target: 'short' (<3 min), 'default' (3-7 min), or 'long' (>7 min).
language Optional[str] No Two-letter language code (ISO 639-1).
intro Optional[str] No Intro text added to the beginning of the podcast.
outro Optional[str] No Outro text added to the end of the podcast.
instructions_prompt Optional[str] No Additional instructions to adjust the podcast's style and tone.
highlights Optional[Sequence[str]] No Key points or themes summary (10-70 characters each).
callback_url Optional[str] No Webhook URL called when project/chapter conversion completes or fails. Receives JSON with conversion status details.
apply_text_normalization Optional[...ApplyTextNormalization] No Controls text normalization. Modes: 'auto', 'on', 'apply_english', 'off'.
request_options Optional[RequestOptions] No Request-specific configuration.

Output

Name Type Description
return PodcastProjectResponseModel Response model containing the created podcast project details.

projects (Sub-Client)

The projects property provides access to a ProjectsClient with the following methods:

Method Description Returns
list() Returns a list of all Studio projects with metadata. GetProjectsResponse
create(...) Creates a new Studio project (blank, from URL, or from document). AddProjectResponseModel
get(project_id) Returns detailed information about a specific project. ProjectExtendedResponse
update(project_id, ...) Updates a project's name, voices, metadata, and settings. EditProjectResponseModel
delete(project_id) Deletes a Studio project. DeleteProjectResponseModel
convert(project_id) Starts audio conversion of a project and all its chapters. ConvertProjectResponseModel
get_muted_tracks(project_id) Returns chapter IDs that have muted tracks. ProjectMutedTracksResponseModel

The ProjectsClient further provides nested sub-clients via properties:

  • projects.pronunciation_dictionaries - Manage pronunciation dictionaries for a project.
  • projects.content - Manage project content.
  • projects.snapshots - Manage project snapshots.
  • projects.chapters - Manage project chapters.

API Endpoints

Method HTTP Verb Endpoint
create_podcast POST /v1/studio/podcasts
projects.list GET /v1/studio
projects.create POST /v1/studio
projects.get GET /v1/studio/{project_id}
projects.update POST /v1/studio/{project_id}
projects.delete DELETE /v1/studio/{project_id}
projects.convert POST /v1/studio/{project_id}/convert
projects.get_muted_tracks GET /v1/studio/{project_id}/muted-tracks

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.

Callback Webhook Payloads

When a callback_url is provided to create_podcast or projects.create, the service sends JSON payloads on conversion events:

Project Conversion Success

{
  "type": "project_conversion_status",
  "event_timestamp": 1234567890,
  "data": {
    "request_id": "1234567890",
    "project_id": "21m00Tcm4TlvDq8ikWAM",
    "conversion_status": "success",
    "project_snapshot_id": "22m00Tcm4TlvDq8ikMAT",
    "error_details": null
  }
}

Chapter Conversion Failure

{
  "type": "chapter_conversion_status",
  "event_timestamp": 1234567890,
  "data": {
    "request_id": "1234567890",
    "project_id": "21m00Tcm4TlvDq8ikWAM",
    "chapter_id": "22m00Tcm4TlvDq8ikMAT",
    "conversion_status": "error",
    "chapter_snapshot_id": null,
    "error_details": "Error details if conversion failed"
  }
}

Usage Examples

Creating a Conversation Podcast

from elevenlabs import (
    ElevenLabs,
    PodcastConversationModeData,
    PodcastTextSource,
)
from elevenlabs.studio import (
    BodyCreatePodcastV1StudioPodcastsPostMode_Conversation,
)

client = ElevenLabs(api_key="YOUR_API_KEY")
podcast = client.studio.create_podcast(
    safety_identifier="safety-identifier",
    model_id="eleven_multilingual_v2",
    mode=BodyCreatePodcastV1StudioPodcastsPostMode_Conversation(
        conversation=PodcastConversationModeData(
            host_voice_id="aw1NgEzBg83R7vgmiJt6",
            guest_voice_id="aw1NgEzBg83R7vgmiJt7",
        ),
    ),
    source=PodcastTextSource(
        text="This is a test podcast about artificial intelligence.",
    ),
    quality_preset="high",
    duration_scale="default",
)

Listing Studio Projects

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
projects = client.studio.projects.list()
for project in projects.projects:
    print(project.project_id, project.name)

Creating a Studio Project from a Name

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
result = client.studio.projects.create(
    name="My Audiobook Project",
)

Getting and Updating a Project

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# Get detailed project info
project = client.studio.projects.get(
    project_id="21m00Tcm4TlvDq8ikWAM",
)

# Update the project
client.studio.projects.update(
    project_id="21m00Tcm4TlvDq8ikWAM",
    name="Updated Project Name",
    default_title_voice_id="21m00Tcm4TlvDq8ikWAM",
    default_paragraph_voice_id="21m00Tcm4TlvDq8ikWAM",
)

Converting a Project to Audio

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")
client.studio.projects.convert(
    project_id="21m00Tcm4TlvDq8ikWAM",
)

Async Podcast Creation

import asyncio
from elevenlabs import (
    AsyncElevenLabs,
    PodcastConversationModeData,
    PodcastTextSource,
)
from elevenlabs.studio import (
    BodyCreatePodcastV1StudioPodcastsPostMode_Conversation,
)

client = AsyncElevenLabs(api_key="YOUR_API_KEY")

async def main() -> None:
    podcast = await client.studio.create_podcast(
        safety_identifier="safety-identifier",
        model_id="eleven_multilingual_v2",
        mode=BodyCreatePodcastV1StudioPodcastsPostMode_Conversation(
            conversation=PodcastConversationModeData(
                host_voice_id="aw1NgEzBg83R7vgmiJt6",
                guest_voice_id="aw1NgEzBg83R7vgmiJt7",
            ),
        ),
        source=PodcastTextSource(
            text="This is an async test podcast.",
        ),
    )

asyncio.run(main())

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.
Principle
Implementation
Heuristic
Environment
Retrieved from "https://leeroopedia.com/index.php?title=Implementation:Elevenlabs_Elevenlabs_python_StudioClient&oldid=6079"