Metadata-Version: 2.4
Name: whiteframes
Version: 0.1.1
Summary: Python SDK for Whiteframes AI — create AI-powered videos programmatically
License-Expression: MIT
Project-URL: Homepage, https://whiteframes.ai
Project-URL: Documentation, https://whiteframes.ai/docs
Project-URL: Repository, https://github.com/yourname/whiteframes-sdk
Keywords: ai,video,whiteboard,text-to-video,whiteframes
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0

# Whiteframes AI Python SDK

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

## Installation

```bash
pip install whiteframes
```

## Quick Start

```python
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](https://whiteframes.ai) → Settings → API Keys.

---

## API Reference

### `create_video()` — Create a video (blocking)

```python
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)

```python
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

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

### `list_videos()` — List all your videos

```python
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

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

### `synthesize_speech()` — Text to speech

```python
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

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

### `create_api_key()` — Create a new API key

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

### `revoke_api_key()` — Revoke an API key

```python
client.revoke_api_key("key_a1b2c3d4")
```

---

## Videocast (Multi-speaker)

```python
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

```python
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

```python
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.
```
