elevenlabs_ttm

A type-safe, async Rust client for the ElevenLabs Text-to-Music API. Compose a song from a prompt or a composition plan with a simple, ergonomic API.

Features

• Type-safe & Async: Built with Rust's type system and async/await support
• Builder Pattern: Intuitive, chainable API for configuring TTM requests
• Model Support: Full support for ElevenLabs models (models::elevenlabs_models::*)
• Customizable: Elevanlabs TTM APIs, custom base URLs, and enterprise support
• Tokio Ready: Works seamlessly with the Tokio runtime

Check-out Also:

This project is part of a milestone to implement all ElevenLabs APIs in Rust.

• Elevenlabs TTS: ElevenLabs Text-to-Speech API. ✅
• Elevenlabs STT: ElevenLabs Speech-to-Text API. ✅
• Elevenlabs TTD: ElevenLabs Text-to-Dialogue API. ✅
• Elevenlabs TTV: ElevenLabs Text-to-Voice API. ✅
• Elevenlabs TTM: ElevenLabs Text-to-Music API. ✅
• Elevenlabs SFX: ElevenLabs Sound Effects API. ✅
• Elevenlabs VC: ElevenLabs Voice Changer API. ✅
• Elevenlabs AUI: ElevenLabs Audio Isolation API. ⏳
• Elevenlabs DUB: ElevenLabs Dubbing API. ⏳

Installation

Add this to your Cargo.toml:

[dependencies]
elevenlabs_ttm = "0.0.3"

Quick Start

use elevenlabs_ttm::{ElevenLabsTTMClient, MusicPlan, TTMPromptPlan};
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ElevenLabsTTMClient::new("your-api-key");

    let prompt = "Generate an energetic house track with tribal percussion and atmospheric pads.";
    let prompt_plan: MusicPlan = MusicPlan::Prompt(TTMPromptPlan::new(prompt.to_string()));
    let music_audio = client.compose_music(prompt_plan).execute().await?;

    std::fs::write("output.mp3", &music_audio)?;
    Ok(())
}

Examples

Basic Usage

use elevenlabs_ttm::{ElevenLabsTTMClient, MusicPlan, TTMPromptPlan};
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key =
        env::var("ELEVENLABS_API_KEY").expect("Please set ELEVENLABS_API_KEY environment variable");

    let client = ElevenLabsTTMClient::new(api_key);

    let prompt = "Generate an energetic house track with tribal percussion and atmospheric pads.";
    let prompt_plan: MusicPlan = MusicPlan::Prompt(TTMPromptPlan::new(prompt.to_string()));

    let music_audio = client.compose_music(prompt_plan).execute().await?;

    std::fs::create_dir_all("outputs")?;
    let audio_id = chrono::Utc::now().timestamp();
    let file_name = format!("outputs/{}.mp3", audio_id);
    std::fs::write(file_name.clone(), &music_audio)?;

    Ok(())
}

Advanced Configuration

use elevenlabs_ttm::{
    ElevenLabsTTMClient, MusicPlan, TTMCompositionPlan, TTMCompositionPlanSection, models,
};
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key =
        env::var("ELEVENLABS_API_KEY").expect("Please set ELEVENLABS_API_KEY environment variable");

    let client = ElevenLabsTTMClient::new(api_key);

    let section_1: TTMCompositionPlanSection = TTMCompositionPlanSection::new(
        "section-1".to_string(),
        vec!["afrobeats".to_string()],
        vec!["trap".to_string()],
        30000,
        vec![
            "Step in the light, we shine tonight".to_string(),
            "Rhythm and fire, we feel so alive".to_string(),
            "Hands in the sky, the stars in our eyes".to_string(),
            "Dancing together, no need to hide".to_string(),
            "Energy rising, the night is our guide".to_string(),
        ],
    );

    let section_2: TTMCompositionPlanSection = TTMCompositionPlanSection::new(
        "section-2".to_string(),
        vec!["guitar".to_string()],
        vec!["jazz".to_string()],
        30000,
        vec![
            "Heartbeat is racing, move to the sound".to_string(),
            "We lift each other, no holding down".to_string(),
            "Voices are singing, freedom is loud".to_string(),
            "We own the moment, we stand so proud".to_string(),
            "Nothing can stop us, we rule the crowd".to_string(),
        ],
    );

    let section_3: TTMCompositionPlanSection = TTMCompositionPlanSection::new(
        "section-3".to_string(),
        vec!["punchy 808s".to_string()],
        vec!["blues".to_string()],
        30000,
        vec![
            "Morning is coming, but we still go".to_string(),
            "Love in the rhythm, it’s all we know".to_string(),
            "Spirit uniting, it starts to show".to_string(),
            "Holding the groove, we never slow".to_string(),
            "Afrobeats fire, forever flow".to_string(),
        ],
    );

    let composition_plan: MusicPlan = MusicPlan::Composition(TTMCompositionPlan::new(
        vec![
            "afrobeats".to_string(),
            "guitar".to_string(),
            "punchy 808s".to_string(),
        ],
        vec!["trap".to_string(), "jazz".to_string(), "blues".to_string()],
        vec![section_1, section_2, section_3],
    ));

    let music_audio = client
        .compose_music(composition_plan)
        .model(models::elevanlabs_models::MUSIC_V1)
        .execute()
        .await?;

    std::fs::create_dir_all("outputs")?;
    let audio_id = chrono::Utc::now().timestamp();
    let file_name = format!("outputs/{}.mp3", audio_id);
    std::fs::write(file_name.clone(), &music_audio)?;

    Ok(())
}

Running Examples

# Set your API key
export ELEVENLABS_API_KEY=your_api_key_here

# Run the basic example
cargo run --example basic_ttm

# Run the advanced example
cargo run --example advanced_ttm

API Overview

Error Handling

The crate uses standard Rust error handling patterns. All async methods return Result types:

match client.compose_music(MusicPlan).execute().await {
    Ok(audio) => println!("Audio file as Vec<u8>: {}", audio.len()),
    Err(e) => eprintln!("TTM request failed: {}", e),
}

Requirements

• Rust 1.70+ (for async/await support)
• Tokio runtime
• Valid ElevenLabs API key

License

Licensed under either of:

• MIT License
• Apache License, Version 2.0

at your option.

Contributing

Contributions are welcome! Please feel free to:

• Open issues for bugs or feature requests
• Submit pull requests with improvements
• Improve documentation or examples
• Add tests or benchmarks

Before contributing, please ensure your code follows Rust conventions and includes appropriate tests.

Support

If you like this project, consider supporting me on Patreon 💖

Changelog

See CHANGELOG.md for a detailed history of changes.

Note: This crate is not officially affiliated with ElevenLabs. Please refer to the ElevenLabs API documentation for the most up-to-date API information.