Python SDK
Official Python client for the Subformer API
The official Python SDK for Subformer provides a simple interface for video dubbing, voice cloning, and text-to-speech.
Installation
pip install subformerQuick Start
from subformer import Subformer
# Initialize the client
client = Subformer(api_key="sk_subformer_...")
# Dub a YouTube video to Spanish
job = client.dub(
source="youtube",
url="https://youtube.com/watch?v=VIDEO_ID",
language="es-ES"
)
# Wait for completion
result = client.wait_for_job(job.id)
print(f"Dubbed video: {result.output['videoUrl']}")Features
- Video Dubbing - Translate videos from YouTube, TikTok, Instagram, Facebook, X, and direct URLs to 70+ languages
- Voice Cloning - Transform audio to match target voices
- Text-to-Speech - Generate natural-sounding speech from text
- Voice Library - Save and manage custom voices
- Async Support - Full async/await support for high-performance applications
Video Dubbing
Dub videos from various platforms:
from subformer import Subformer
client = Subformer(api_key="sk_subformer_...")
# YouTube
job = client.dub(source="youtube", url="https://youtube.com/watch?v=...", language="es-ES")
# TikTok
job = client.dub(source="tiktok", url="https://tiktok.com/@user/video/...", language="fr-FR")
# Instagram
job = client.dub(source="instagram", url="https://instagram.com/reel/...", language="de-DE")
# Direct URL
job = client.dub(source="url", url="https://example.com/video.mp4", language="ja-JP")
# Wait for completion
result = client.wait_for_job(job.id)
print(result.output)Voice Cloning
Clone voices using preset or custom voice samples:
from subformer import Subformer, PresetVoice, UploadedVoice
client = Subformer(api_key="sk_subformer_...")
# Using a preset voice
job = client.clone_voice(
source_audio_url="https://example.com/speech.mp3",
target_voice=PresetVoice(preset_voice_id="morgan-freeman")
)
# Using an uploaded voice sample
job = client.clone_voice(
source_audio_url="https://example.com/speech.mp3",
target_voice=UploadedVoice(target_audio_url="https://example.com/my-voice.mp3")
)
result = client.wait_for_job(job.id)
print(result.output['audioUrl'])Text-to-Speech
Generate speech from text:
from subformer import Subformer, PresetVoice, UploadedVoice
client = Subformer(api_key="sk_subformer_...")
# Using a preset voice
job = client.synthesize_voice(
text="Hello, welcome to Subformer!",
target_voice=PresetVoice(preset_voice_id="professional-narrator")
)
# Using a custom voice
job = client.synthesize_voice(
text="This is my cloned voice speaking.",
target_voice=UploadedVoice(target_audio_url="https://example.com/my-voice.mp3")
)
result = client.wait_for_job(job.id)
print(result.output['audioUrl'])Voice Library
Manage your saved voices:
from subformer import Subformer
client = Subformer(api_key="sk_subformer_...")
# List all voices
voices = client.list_voices()
for voice in voices:
print(f"{voice.name}: {voice.id}")
# Create a new voice
voice = client.create_voice(
name="My Custom Voice",
audio_url="https://example.com/voice-sample.mp3"
)
# Update a voice
client.update_voice(voice.id, name="Updated Voice Name")
# Delete a voice
client.delete_voice(voice.id)Async Usage
For high-performance applications:
import asyncio
from subformer import AsyncSubformer
async def main():
client = AsyncSubformer(api_key="sk_subformer_...")
# Start multiple jobs concurrently
jobs = await asyncio.gather(
client.dub(source="youtube", url="https://youtube.com/watch?v=VIDEO1", language="es-ES"),
client.dub(source="youtube", url="https://youtube.com/watch?v=VIDEO2", language="fr-FR"),
)
# Wait for all jobs
results = await asyncio.gather(*[
client.wait_for_job(job.id) for job in jobs
])
for result in results:
print(result.output['videoUrl'])
asyncio.run(main())Error Handling
from subformer import Subformer, SubformerError, AuthenticationError, RateLimitError
client = Subformer(api_key="sk_subformer_...")
try:
job = client.dub(source="youtube", url="https://youtube.com/watch?v=...", language="es-ES")
result = client.wait_for_job(job.id)
except AuthenticationError:
print("Invalid API key")
except RateLimitError:
print("Rate limit exceeded, please wait")
except SubformerError as e:
print(f"API error: {e}")Configuration
from subformer import Subformer
client = Subformer(
api_key="sk_subformer_...",
base_url="https://api.subformer.com/v1", # Optional: custom base URL
timeout=30.0, # Optional: request timeout in seconds
)