Typecast API

Create a quick-cloned custom voice.

Calls POST /v1/voices/clone with multipart form data. Use the returned voice_id with text_to_speech, text_to_speech_stream, or text_to_speech_with_timestamps. Delete temporary cloned voices with delete_cloned_voice when they are no longer needed.

Args: name: Display name for the cloned voice. Must be 1-30 characters. audio_file_path: Local WAV or MP3 sample path. Maximum file size is 25 MB. model: Voice cloning model. Default: ssfm-v30. audio_base64: Base64-encoded WAV or MP3 sample for a remote MCP server. audio_filename: Filename with .wav or .mp3 extension for audio_base64.

Returns: Dict returned by the Typecast API plus normalized handoff fields: voice_id, cloned_voice_id, next_step_voice_id, next_step_model.

Delete a quick-cloned custom voice.

Args: voice_id: Cloned voice ID returned by clone_voice. Must start with uc_.

Returns: Dict with success=true and the deleted voice_id.

Get the authenticated user's subscription information.

Calls GET /v1/users/me/subscription and returns the plan tier, credits (used / total), and concurrency limit.

Returns: Dict with this shape: { "plan": "free" | "lite" | "plus" | "custom", "credits": {"plan_credits": int, "used_credits": int}, "limits": {"concurrency_limit": int} }

Get detailed information for a specific voice by ID using V2 API

Args: voice_id: The voice ID (e.g., 'tc_672c5f5ce59fac2a48faeaee')

Returns: Voice information with enhanced metadata including gender, age, use cases, and supported models with emotions.

Get a list of available voices for text-to-speech using V2 API

Args: model: Optional filter for specific TTS models (ssfm-v21 or ssfm-v30). gender: Optional filter for voice gender (male or female). age: Optional filter for voice age group (child, teen, young_adult, middle_aged, senior). use_cases: Optional filter for voice use case (e.g. 'audiobook', 'narration', 'documentary'). Pass a single use case string supported by the V2 voices endpoint.

Returns: List of available voices with enhanced metadata including gender, age, and use cases.

Play the audio file at the specified path

Args: file_path: Path to the audio file to play

Returns: Status message

Recommend voices that match a natural-language text description.

The recommendation API returns only voice_id, voice_name, and score. Call get_voices or get_voice with the returned IDs when you need metadata such as supported models, emotions, gender, age, or use cases before making a TTS request.

Args: query: Text description of the desired style, mood, language, use case, or content context. count: Maximum number of recommendations to return. Must be 1-10.

Returns: Recommended voice candidates sorted by relevance score.

Convert text to speech using the specified voice and parameters

Args: voice_id: ID of the voice to use text: Text to convert to speech model: TTS model to use (ssfm-v21 or ssfm-v30, default: ssfm-v30) emotion_type: For ssfm-v30: 'preset' for explicit emotion or 'smart' for context-aware inference (default: preset) emotion_preset: Emotion preset type. v21: normal/happy/sad/angry. v30: adds whisper/toneup/tonedown (default: normal) emotion_intensity: Intensity of the emotion, between 0.0 and 2.0 (default: 1.0) previous_text: For smart mode - previous context text for emotion inference next_text: For smart mode - next context text for emotion inference volume: Audio volume level, between 0 and 200 (default: 100) audio_pitch: Audio pitch adjustment, between -12 and 12 (default: 0) audio_tempo: Audio playback speed, between 0.5 and 2.0 (default: 1.0) audio_format: Audio format, either 'wav' or 'mp3' (default: wav) target_lufs: Optional absolute loudness normalization target in LUFS (-70.0 ~ 0.0). Mutually exclusive with a custom volume value on this non-streaming endpoint.

Returns: Local mode: path to the saved audio file. Remote mode: dict with audio_url and expires_in_seconds.

Convert text to speech via the streaming endpoint and save the result.

Calls POST /v1/text-to-speech/stream which returns chunked audio data in real time. The chunks are concatenated and saved as a single file.

Note: the streaming endpoint does not accept volume, but supports target_lufs for absolute loudness normalization.

Args: voice_id: ID of the voice to use text: Text to convert to speech model: TTS model (ssfm-v21 or ssfm-v30, default: ssfm-v30) emotion_type: For ssfm-v30: 'preset' or 'smart' (default: preset) emotion_preset: Emotion preset name (default: normal) emotion_intensity: Emotion intensity, 0.0 ~ 2.0 (default: 1.0) previous_text: For smart mode - previous context text next_text: For smart mode - next context text audio_pitch: -12 ~ 12 (default: 0) audio_tempo: 0.5 ~ 2.0 (default: 1.0) audio_format: 'wav' or 'mp3' (default: wav) target_lufs: Optional absolute loudness normalization target in LUFS (-70.0 ~ 0.0) remove_silence_ms: Remaining detected silence in milliseconds (integer 0–1000). Zero removes silence; None disables this processing. Playback may need buffering.

Returns: Local mode: path to the saved audio file. Remote mode: dict with audio_url and expires_in_seconds.

Convert text to speech and return timestamp alignment for caption generation.

Calls POST /v1/text-to-speech/with-timestamps. Saves the audio file and returns the file path together with the raw alignment payload (words and characters arrays as returned by the server).

For non-whitespace languages such as jpn or zho, pass granularity='char' or 'both'. With 'word' on those languages the server collapses the entire sentence into a single word segment.

Args: voice_id: ID of the voice to use text: Text to convert to speech model: TTS model (default: ssfm-v30) granularity: 'word', 'char', or 'both'. None lets the server use its default (word). For jpn/zho prefer 'char' or 'both'. emotion_type, emotion_preset, emotion_intensity, previous_text, next_text, language, volume, audio_pitch, audio_tempo, audio_format: same shape as text_to_speech.

Returns: Dict:

• local mode: 'audio_path' — path to the saved audio file
• remote mode: 'audio_url' and 'expires_in_seconds'
• 'words': list | None — word-level alignment when available
• 'characters': list | None — character-level alignment when available
• 'raw': dict — full server response with the audio bytes stripped