Hudsonly AI Python SDK

Official Python SDK for the Hudsonly AI API — Text-to-Speech, Speech-to-Text, Text Embeddings, and Avatar Video Generation.

Installation

pip install hudsonly

Quick Start

from hudsonly import HudsonlyAI

client = HudsonlyAI(api_key="your-api-token")

# Text to Speech
result = client.tts.generate(text="Hello world", voice="af_heart")
print(result.audio_url)

# Speech to Text
result = client.transcription.generate(audio="recording.mp3")
print(result.text)

# Text Embeddings
result = client.embeddings.generate(texts=["Hello", "World"])
print(result.embeddings)

# Avatar Video (auto-polls until complete)
result = client.avatar.generate(
    image="photo.jpg",
    audio="speech.mp3",
    model="sadtalker",
)
print(result.video_url)

Services

Text to Speech

Convert text to natural-sounding speech.

result = client.tts.generate(
    text="Hello world",
    voice="af_heart",    # Voice identifier
    format="mp3",        # "mp3" or "wav"
    speed=1.0,           # 0.5 to 2.0
)
print(result.audio_url)
print(result.duration_seconds)

Speech to Text (Transcription)

Transcribe audio files to text with timestamps.

# From a local file
result = client.transcription.generate(
    audio="recording.mp3",
    model="base",        # "tiny", "base", "small", "medium"
    language="en",       # Optional, auto-detected if omitted
)
print(result.text)

for segment in result.segments:
    print(f"[{segment.start:.1f}s - {segment.end:.1f}s] {segment.text}")

# From a URL
result = client.transcription.generate(
    audio_url="https://example.com/audio.mp3",
)

Text Embeddings

Generate vector embeddings for text.

result = client.embeddings.generate(texts=["Hello", "World"])
print(result.embeddings)   # [[0.1, 0.2, ...], [0.3, 0.4, ...]]
print(result.dimension)    # 1024
print(result.model)        # "bge-m3"

Avatar Video Generation

Generate animated portrait videos. This is an async service — generate() submits the task and polls until complete.

# Auto-poll (recommended)
result = client.avatar.generate(
    image="photo.jpg",
    audio="speech.mp3",
    model="sadtalker",       # "sadtalker" or "liveportrait"
    poll_interval=5,         # Seconds between polls
    timeout=600,             # Max wait time
)
print(result.video_url)

# Manual polling
task = client.avatar.create(image="photo.jpg", audio="speech.mp3")
print(task.id, task.status)  # "pending"

# Poll manually
task = client.tasks.get(task.id)
if task.is_completed:
    print(task.output["video_url"])

LivePortrait (video-driven):

result = client.avatar.generate(
    image="photo.jpg",
    video="driving_video.mp4",
    model="liveportrait",
    flag_stitching=True,
    flag_relative_motion=True,
)

Resources

Tasks

List and retrieve async tasks.

# List tasks
tasks = client.tasks.list(service="avatar", status="completed")
for task in tasks.data:
    print(task.id, task.status)

# Get a specific task
task = client.tasks.get("task-uuid")
print(task.output)

Credits

Check balance and transaction history.

# Get balance
balance = client.credits.balance()
print(balance.balance)

# Transaction history
history = client.credits.history(type="usage", per_page=50)
for txn in history.data:
    print(txn.amount, txn.description)

Other Methods

# List available services
services = client.services()
for svc in services:
    print(svc.slug, svc.name, svc.min_credits)

# Check rate limits
limits = client.rate_limits()
for limit in limits:
    print(f"{limit.service}: {limit.remaining}/{limit.limit}")

Error Handling

from hudsonly import (
    HudsonlyAI,
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
    ValidationError,
    TaskError,
    TaskTimeoutError,
)

client = HudsonlyAI(api_key="your-token")

try:
    result = client.tts.generate(text="Hello")
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError:
    print("Not enough credits")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Validation failed: {e.errors}")
except TaskError as e:
    print(f"Task {e.task_id} failed: {e}")
except TaskTimeoutError:
    print("Task polling timed out")

Context Manager

with HudsonlyAI(api_key="your-token") as client:
    result = client.tts.generate(text="Hello")

Requirements

• Python 3.9+
• httpx (installed automatically)

License

MIT