Struct TypecastClient 

pub struct TypecastClient { /* private fields */ }

The main Typecast API client

Implementations

impl TypecastClient

pub fn new(config: ClientConfig) -> Result<Self>

Create a new TypecastClient with the given configuration

pub fn from_env() -> Result<Self>

Create a new TypecastClient from environment variables

Reads TYPECAST_API_KEY and optionally TYPECAST_API_HOST

pub fn with_api_key(api_key: impl Into<String>) -> Result<Self>

Create a new TypecastClient with just an API key

pub fn base_url(&self) -> &str

Get the base URL

pub fn api_key_masked(&self) -> String

Get the API key (masked)

pub fn compose_speech(&self) -> SpeechComposer<'_>

Create a builder for composed speech with multiple speech segments and pauses.

pub async fn text_to_speech(&self, request: &TTSRequest) -> Result<TTSResponse>

Convert text to speech

Arguments

• request - The TTS request containing text, voice_id, model, and optional settings

Returns

Returns a TTSResponse containing the audio data, duration, and format

Example

use typecast_rust::{TypecastClient, TTSRequest, TTSModel, ClientConfig};

let client = TypecastClient::from_env()?;
let request = TTSRequest::new(
    "tc_60e5426de8b95f1d3000d7b5",
    "Hello, world!",
    TTSModel::SsfmV30,
);
let response = client.text_to_speech(&request).await?;
println!("Audio duration: {} seconds", response.duration);

pub async fn generate_to_file( &self, path: impl AsRef<Path>, request: GenerateToFileRequest, ) -> Result<TTSResponse>

Convert text to speech and write the audio bytes to a file.

If request.output.audio_format is omitted, the format is inferred from a .mp3 or .wav file extension.

pub async fn text_to_speech_stream( &self, request: &TTSRequestStream, ) -> Result<AudioByteStream>

Convert text to speech as a streaming response

Returns a stream of audio byte chunks. For wav output the first chunk contains the WAV header followed by PCM samples; for mp3 output each chunk is independently decodable.

Arguments

• request - The streaming TTS request

Returns

A pinned boxed Stream yielding Result<Bytes> chunks.

Example

use futures_util::StreamExt;
use typecast_rust::{TypecastClient, TTSRequestStream, TTSModel};

let client = TypecastClient::from_env()?;
let request = TTSRequestStream::new(
    "tc_60e5426de8b95f1d3000d7b5",
    "Hello, world!",
    TTSModel::SsfmV30,
);
let mut stream = client.text_to_speech_stream(&request).await?;
while let Some(chunk) = stream.next().await {
    let bytes = chunk?;
    // write bytes to file or audio sink
    let _ = bytes;
}

pub async fn get_voices_v2( &self, filter: Option<VoicesV2Filter>, ) -> Result<Vec<VoiceV2>>

Get voices with enhanced metadata (V2 API)

Arguments

• filter - Optional filter for voices (model, gender, age, use_cases)

Returns

Returns a list of VoiceV2 with enhanced metadata

Example

use typecast_rust::{TypecastClient, VoicesV2Filter, TTSModel, Gender, ClientConfig};

let client = TypecastClient::from_env()?;

// Get all voices
let voices = client.get_voices_v2(None).await?;

// Get filtered voices
let filter = VoicesV2Filter::new()
    .model(TTSModel::SsfmV30)
    .gender(Gender::Female);
let filtered_voices = client.get_voices_v2(Some(filter)).await?;

pub async fn get_voice_v2(&self, voice_id: &str) -> Result<VoiceV2>

Get a specific voice by ID with enhanced metadata (V2 API)

Arguments

• voice_id - The voice ID (e.g., ‘tc_60e5426de8b95f1d3000d7b5’)

Returns

Returns a VoiceV2 with enhanced metadata

Example

use typecast_rust::{TypecastClient, ClientConfig};

let client = TypecastClient::from_env()?;
let voice = client.get_voice_v2("tc_60e5426de8b95f1d3000d7b5").await?;
println!("Voice: {} ({})", voice.voice_name, voice.voice_id);

pub async fn recommend_voices( &self, query: &str, count: Option<u8>, ) -> Result<Vec<RecommendedVoice>>

Recommend voices from a text description.

Results only contain voice_id, voice_name, and score. Use get_voice_v2 or get_voices_v2 when you need detailed metadata for the returned voice IDs.

pub async fn text_to_speech_with_timestamps( &self, request: &TTSRequestWithTimestamps, granularity: Option<&str>, ) -> Result<TTSWithTimestampsResponse>

Convert text to speech with word- and/or character-level timestamps.

Arguments

• request - The TTS request with timestamps parameters.
• granularity - Optional granularity: None (both), "word", or "char".

Returns

A crate::timestamps::TTSWithTimestampsResponse containing the Base64-encoded audio and alignment segment arrays. Use the response’s .to_srt() / .to_vtt() methods to generate subtitle files.

Example

use typecast_rust::{TypecastClient, TTSModel};
use typecast_rust::timestamps::TTSRequestWithTimestamps;

let client = TypecastClient::from_env()?;
let request = TTSRequestWithTimestamps::new(
    "tc_60e5426de8b95f1d3000d7b5",
    "Hello, world!",
    TTSModel::SsfmV30,
);
let response = client.text_to_speech_with_timestamps(&request, None).await?;
let srt = response.to_srt()?;
println!("{}", srt);

pub async fn get_my_subscription(&self) -> Result<SubscriptionResponse>

Get the authenticated user’s subscription

Returns

Returns a SubscriptionResponse containing the user’s plan, credits, and usage limits.

Example

use typecast_rust::TypecastClient;

let client = TypecastClient::from_env()?;
let subscription = client.get_my_subscription().await?;
println!("Plan: {:?}", subscription.plan);
println!(
    "Credits: {}/{}",
    subscription.credits.used_credits, subscription.credits.plan_credits
);

pub async fn clone_voice( &self, audio: Vec<u8>, filename: &str, name: &str, model: &str, ) -> Result<CustomVoice>

Clone a voice from an audio recording.

Uploads the audio file as multipart/form-data to POST /v1/voices/clone and returns a CustomVoice representing the newly created voice.

Arguments

• audio - Raw audio bytes (WAV or MP3). Must not exceed 25 MB.
• filename - File name used in the multipart part (e.g. "sample.wav"). The extension determines the MIME type sent to the API.
• name - Display name for the custom voice (1–30 characters).
• model - TTS model to use for cloning (e.g. "ssfm-v30").

Errors

Returns TypecastError::ValidationError if name is outside 1–30 characters or if audio exceeds the 25 MB limit before any network call is made.

Example

use typecast_rust::TypecastClient;

let client = TypecastClient::from_env()?;
let audio = std::fs::read("sample.wav").unwrap();
let voice = client.clone_voice(audio, "sample.wav", "My Voice", "ssfm-v30").await?;
println!("Cloned voice ID: {}", voice.voice_id);

pub async fn delete_voice(&self, voice_id: &str) -> Result<()>

Delete a custom (cloned) voice by its ID.

Sends DELETE /v1/voices/{voice_id}. A 204 No Content response is treated as success; any other non-2xx status is mapped to a TypecastError.

Arguments

• voice_id - The voice ID returned by TypecastClient::clone_voice.

Example

use typecast_rust::TypecastClient;

let client = TypecastClient::from_env()?;
client.delete_voice("cv_abc123").await?;
println!("Voice deleted.");

Trait Implementations

impl Clone for TypecastClient

fn clone(&self) -> TypecastClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TypecastClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.