whiteframes 0.1.1

Python SDK for Whiteframes AI — create AI-powered videos programmatically

Whiteframes AI Python SDK

Create AI-powered videos programmatically — whiteboard explainers, social shorts, news broadcasts, podcasts, and more.

Installation

pip install whiteframes

Quick Start

from whiteframes import WhiteframesAI

client = WhiteframesAI(api_key="wfai_your_key_here")

# Create a video — blocks until ready (~2 minutes)
video = client.create_video("Explain how neural networks work")

print(video.title)           # "How Neural Networks Work"
print(video.scene_count)     # 4
print(video.scenes[0].narration)

Get your API key at whiteframes.ai → Settings → API Keys.

---

API Reference

create_video() — Create a video (blocking)

video = client.create_video(
    prompt="Explain how neural networks work",
    voice="Stephen",        # default
    quality="standard",     # default — or "premium"
    scenes=4,               # default — or 8, 12
    video_type="whiteboard" # default — see Video Types below
)

Returns a Video object when ready.

create_video_async() — Create a video (non-blocking)

job = client.create_video_async(prompt="Explain blockchain")

# Poll manually
job.refresh()
print(job.status, job.progress)  # "generating", 45

# Or block with a progress callback
def on_progress(progress, message):
    print(f"[{progress}%] {message}")

video = job.wait(on_progress=on_progress)

get_video() — Get a video by ID

video = client.get_video("my-project-id")
print(video.title)
for scene in video.scenes:
    print(scene.narration)

list_videos() — List all your videos

result = client.list_videos()
for video in result["videos"]:
    print(video.title, video.scene_count, "scenes")

# Paginate
result2 = client.list_videos(cursor=result["next_cursor"])

delete_video() — Delete a video

client.delete_video("my-project-id")

synthesize_speech() — Text to speech

audio_bytes = client.synthesize_speech(
    "Welcome to Whiteframes AI.",
    voice="Amy"
)
with open("output.mp3", "wb") as f:
    f.write(audio_bytes)

list_api_keys() — List your API keys

keys = client.list_api_keys()
for key in keys:
    print(key["name"], key["totalCalls"], "calls")

create_api_key() — Create a new API key

result = client.create_api_key("My Production App")
print(result["key"])  # Save this — shown once only!

revoke_api_key() — Revoke an API key

client.revoke_api_key("key_a1b2c3d4")

---

Videocast (Multi-speaker)

video = client.create_video(
    prompt="Discuss the future of AI",
    video_type="videocast",
    scenes=8,
    speaker_voices={
        "speaker_1": "Stephen",
        "speaker_2": "Ruth",
        "speaker_3": "Brian",
    },
)

---

Supported Voices

voiceId	Language	Gender
Stephen	en-US	Male
Matthew	en-US	Male
Ruth	en-US	Female
Joanna	en-US	Female
Amy	en-GB	Female
Brian	en-GB	Male
Olivia	en-AU	Female

---

Supported Video Types

videoType	Description
whiteboard	Hand-drawn style, great for education
saas-demo	Clean UI mockups, feature walkthroughs
infographic	Bold flat design with data visualizations
corporate	Professional slides with clean layouts
architecture	Technical system diagrams with service icons
educational	Engaging visuals for math, coding, concepts
social-short	Vertical 9:16 format for Shorts, TikTok, Reels
pitch	Compelling slides for investors
onboarding	Step-by-step product walkthroughs
storytelling	Character-driven animated story scenes
news	Professional news-style reporting
videocast	Multiple hosts discuss a topic in turns

---

Error Handling

from whiteframes import WhiteframesAI, InsufficientCreditsError, ContentRejectedError, WhiteframesError

try:
    video = client.create_video(prompt="...")
except InsufficientCreditsError:
    print("Not enough credits")
except ContentRejectedError:
    print("Content was rejected by moderation")
except WhiteframesError as e:
    print(f"API error {e.status_code}: {e}")

---

Video Object

video.id            # project ID
video.title         # generated title
video.status        # "ready"
video.video_type    # e.g. "educational"
video.voice_id      # e.g. "Stephen"
video.scene_count   # number of scenes
video.created_at    # timestamp
video.scenes        # list of Scene objects

# Scene object
scene.id            # scene number
scene.narration     # spoken text
scene.duration      # seconds
scene.svg_key       # S3 key for the SVG visual
scene.audio_key     # S3 key for the MP3 audio
scene.keywords      # list of keywords
scene.speaker_id    # for videocast: "speaker_1", "speaker_2", etc.