Metadata-Version: 2.4
Name: agent-media
Version: 0.2.1
Summary: Python SDK for agent-media — generate AI UGC videos with talking heads, B-roll, and subtitles programmatically.
Project-URL: Homepage, https://agent-media.ai
Project-URL: Documentation, https://agent-media.ai/docs/api-reference
Project-URL: Repository, https://github.com/yuvalsuede/agent-media
Project-URL: Changelog, https://agent-media.ai/docs/api-changelog
Project-URL: Bug Tracker, https://github.com/yuvalsuede/agent-media/issues
License-Expression: Apache-2.0
Keywords: agent-media,ai,ai-video,api-client,b-roll,developer-tools,product-ugc,product-video,sdk,subtitles,talking-head,text-to-video,ugc,video-generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25
Description-Content-Type: text/markdown

# agent-media

Python SDK for [agent-media](https://agent-media.ai) — UGC video generation for developers.

Generate AI videos with realistic talking heads, B-roll, voiceover, animated subtitles, and music. One function call, finished video.

[![PyPI version](https://img.shields.io/pypi/v/agent-media)](https://pypi.org/project/agent-media/)
[![Python](https://img.shields.io/pypi/pyversions/agent-media)](https://pypi.org/project/agent-media/)
[![license](https://img.shields.io/pypi/l/agent-media)](https://github.com/yuvalsuede/agent-media/blob/main/LICENSE)

## Install

```bash
pip install agent-media
```

## Quick Start

```python
from agent_media import AgentMedia

client = AgentMedia(api_key="ma_YOUR_KEY")

# Generate a video — blocks until complete, returns the URL
video = client.create_video(
    script="Have you tried building UGC content at scale? This API makes it trivial.",
    actor_slug="sofia",
    tone="energetic",
    style="hormozi",
    target_duration=10,
)
print(video["video_url"])
# → https://...mp4
```

## Async

```python
from agent_media.client import AsyncAgentMedia

async with AsyncAgentMedia(api_key="ma_YOUR_KEY") as client:
    video = await client.create_video(
        script="Your script here...",
        actor_slug="sofia",
        tone="confident",
    )
    print(video["video_url"])
```

## API Reference

### `AgentMedia(api_key, base_url?, timeout?)`

| Parameter | Type | Required | Default |
|---|---|---|---|
| `api_key` | str | Yes | — |
| `base_url` | str | No | Production API |
| `timeout` | float | No | 60.0 |

### `client.create_video(**params)`

Generate a video and wait for completion. Returns `{ job_id, video_url, credits_deducted, duration }`.

```python
video = client.create_video(
    script="Your script (50-3000 chars)",
    actor_slug="sofia",           # use list_actors() to browse
    tone="energetic",             # energetic | calm | confident | dramatic
    music="chill",                # chill | energetic | corporate | dramatic | upbeat
    style="hormozi",              # 17 subtitle styles
    target_duration=10,           # 5 | 10 | 15 seconds
    aspect_ratio="9:16",          # 9:16 | 16:9 | 1:1
    allow_broll=True,             # include AI-generated B-roll
    template="product-review",    # optional template
    webhook_url="https://...",    # optional async callback
    timeout_seconds=600,          # max wait time (default 10 min)
)
```

### `client.submit_video(**params)`

Submit without waiting. Returns `{ job_id, status, credits_deducted }`.

### `client.submit_subtitle(**params)`

Add subtitles to an existing video.

```python
job = client.submit_subtitle(
    video_url="https://example.com/video.mp4",
    style="bold",
)
```

### `client.submit_product_review(**params)`

Generate a product review video from a URL.

```python
job = client.submit_product_review(
    product_url="https://example.com/product",
    angle="enthusiastic",
    actor_slug="sofia",
)
```

### `client.create_product_acting(**params)`

Generate Product Acting UGC from a product image and actor.

```python
video = client.create_product_acting(
    product_image_url="https://cdn.example.com/perfume.png",
    actor_slug="sofia",
    product_name="Rose Noir",
    product_description="Premium rose perfume with a warm vanilla dry-down.",
    template="product-in-hand",
    acting_style="honest-review",
    duration=5,
    subtitle_style="hormozi",
)
print(video["video_url"])
```

Use `submit_product_acting(...)` if you want to submit without waiting and poll with `get_video_status()`.

### `client.list_actors(limit?, offset?)`

Browse available AI actors.

```python
result = client.list_actors(limit=20)
for actor in result["actors"]:
    print(f"{actor['slug']} — {actor['name']} ({actor['gender']}, {actor['nationality']})")
```

### `client.get_video_status(job_id)`

Check job progress.

```python
status = client.get_video_status("job_abc123")
if status["status"] == "completed":
    print(status["video_url"])
```

## Error Handling

```python
from agent_media import AgentMedia, AgentMediaError

try:
    video = client.create_video(script="...")
except AgentMediaError as e:
    print(f"{e.code}: {e} (HTTP {e.status})")
```

## Webhooks

Skip polling — pass `webhook_url` and agent-media will POST to it when the job completes or fails.

```python
job = client.submit_video(
    script="...",
    actor_slug="sofia",
    webhook_url="https://example.com/webhooks/agent-media?secret=MY_TOKEN",
)
```

**Payload on success:**

```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "video_url": "https://pub-xxx.r2.dev/videos/550e8400.mp4"
}
```

**Payload on failure:**

```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error_message": "Script exceeded maximum duration for selected actor."
}
```

**Rules:**
- Must be `https://` (plain HTTP is rejected)
- Publicly reachable
- Max 2048 characters
- Retries on non-2xx: 3 attempts with exponential backoff (1 s, 4 s, 16 s)
- Query strings are preserved — append `?secret=MY_TOKEN` to verify authenticity

## Batch Generation

```python
from concurrent.futures import ThreadPoolExecutor

scripts = ["Script 1...", "Script 2...", "Script 3..."]

with ThreadPoolExecutor(max_workers=3) as pool:
    videos = list(pool.map(
        lambda s: client.create_video(script=s, actor_slug="sofia"),
        scripts,
    ))

for v in videos:
    print(v["video_url"])
```

## Related Packages

| Package | Registry | Description |
|---|---|---|
| [`@agentmedia/sdk`](https://www.npmjs.com/package/@agentmedia/sdk) | npm | TypeScript SDK |
| [`@agentmedia/mcp-server`](https://www.npmjs.com/package/@agentmedia/mcp-server) | npm | MCP server for Claude Code, Cursor, Windsurf |
| [`agent-media-cli`](https://www.npmjs.com/package/agent-media-cli) | npm | CLI tool |
| [`@agentmedia/schema`](https://www.npmjs.com/package/@agentmedia/schema) | npm | Shared schema, types, Zod validation |

## Links

- [Interactive API Docs](https://agent-media.ai/docs/api-reference)
- [OpenAPI Spec](https://agent-media.ai/openapi.json)
- [Website](https://agent-media.ai)
- [GitHub](https://github.com/yuvalsuede/agent-media)

## License

Apache-2.0
