golpo 0.9.9
Python SDK for Golpo AI-generated explainer videos and podcasts.
License: MIT
Requires Python: >=3.8

# Golpo Python SDK

Python SDK for [Golpo](https://video.golpoai.com) — generate AI-powered explainer videos and podcasts from text and documents.

## Installation

```bash
pip install golpo
```

## Quick start

```python
from golpo import Golpo

client = Golpo(api_key="your-api-key")

# Generate a video
result = client.create_video(prompt="Explain quantum computing in 2 minutes")
print(result.url)       # Video URL
print(result.script)   # Generated script
print(result.video_id) # Use for edit_video, get_frame_animations, etc.
```

---

## Client setup

```python
from golpo import Golpo

client = Golpo(api_key="your-api-key")
```

| Parameter   | Type | Description |
|------------|------|-------------|
| `api_key`  | `str` | Your Golpo API key (required). |

---

## API reference

### 1. `create_podcast` — Generate a podcast

Creates an AI-generated podcast from a prompt and optional documents. The call blocks until the podcast is ready and returns its URL, script, and ID.

**Returns:** `GenerationResult` (`.url`, `.script`, `.video_id`)

**Example**

```python
from golpo import Golpo, GenerationResult

client = Golpo(api_key="your-api-key")

# Prompt only
result: GenerationResult = client.create_podcast(
    prompt="Create a 5-minute podcast about climate change and renewable energy."
)
print(result.url)       # Podcast audio URL
print(result.script)    # Script text
print(result.video_id)  # Job ID (e.g. for tracking)

# With document URLs (no upload)
result = client.create_podcast(
    prompt="Summarize this document and discuss key points.",
    uploads=["https://example.com/document.pdf"],
)

# With local files (uploaded to S3 automatically)
result = client.create_podcast(
    prompt="Turn this into an explainer podcast.",
    uploads=["./my-doc.pdf", Path("./other-doc.pdf")],
    style="solo-female",
    bg_music="lofi",
    poll_interval=5,
)
```

**Parameters**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | `str` | required | Topic or instructions for the podcast. |
| `uploads` | `str` \| `Path` \| iterable | `None` | Document URL(s) or local file path(s). Local files are uploaded in parallel. |
| `add_music` | `bool` | `False` | Add background music. |
| `voice_instructions` | `str` | `None` | Instructions for voice style. |
| `personality_1`, `personality_2` | `str` | `None` | Host personality hints. |
| `do_research` | `bool` | `False` | Whether the AI should research the topic. |
| `tts_model` | `str` | `"accurate"` | TTS model. |
| `language` | `str` | `None` | Language code. |
| `style` | `str` | `"conversational"` | `"conversational"`, `"solo-male"`, or `"solo-female"`. |
| `bg_music` | `str` | `None` | `"jazz"`, `"lofi"`, `"dramatic"`, or `None`. |
| `poll_interval` | `int` | `2` | Seconds between status polls. |
| `max_workers` | `int` | `8` | Max parallel uploads for local files. |
| `output_volume` | `float` | `1.0` | Output volume. |
| `no_voice_chunking` | `bool` | `False` | Disable voice chunking. |

---

### 2. `create_video` — Generate a video

Creates an AI-generated explainer video from a prompt and optional documents. Blocks until the video is ready.

**Returns:** `GenerationResult` (`.url`, `.script`, `.video_id`)

**Example**

```python
from golpo import Golpo, GenerationResult

client = Golpo(api_key="your-api-key")

result: GenerationResult = client.create_video(
    prompt="Create a 2-minute explainer on how photosynthesis works.",
)
print(result.url)       # Video MP4 URL
print(result.script)    # Narration script
print(result.video_id)  # Use with edit_video, get_frame_animations

# With options
result = client.create_video(
    prompt="Product demo for our SaaS platform.",
    uploads=["https://example.com/spec.pdf"],
    style="solo-female",
    bg_music="engaging",
    timing="1.5",           # Minutes
    include_watermark=True,
    use_color=True,
    poll_interval=5,
)
```

**Parameters**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | `str` | required | Topic or instructions for the video. |
| `uploads` | `str` \| `Path` \| iterable | `None` | Document URL(s) or local file path(s). |
| `voice_instructions` | `str` | `None` | Voice style instructions. |
| `personality_1` | `str` | `None` | Personality hint. |
| `do_research` | `bool` | `False` | Enable research. |
| `tts_model` | `str` | `"accurate"` | TTS model. |
| `language` | `str` | `None` | Language code. |
| `style` | `str` | `"solo-female"` | `"solo-male"` or `"solo-female"`. |
| `bg_music` | `str` | `"engaging"` | Background music style. |
| `bg_volume` | `float` | `1.4` | Background music volume. |
| `video_type` | `str` | `"long"` | Video type. |
| `include_watermark` | `bool` | `True` | Include watermark. |
| `new_script` | `str` | `None` | Override script; `timing` can be auto-estimated from it. |
| `just_return_script` | `bool` | `False` | Only generate script, no video. |
| `logo` | `str` \| `Path` | `None` | Logo URL or local path. |
| `timing` | `str` | `"1"` | Duration in minutes (e.g. `"1.5"`); must be ≥ 0.25. |
| `poll_interval` | `int` | `2` | Seconds between status polls. |
| `max_workers` | `int` | `8` | Max parallel uploads. |
| `output_volume` | `float` | `1.0` | Output volume. |
| `video_instructions` | `str` | `None` | Visual/video instructions. |
| `use_color` | `bool` | `False` | Use color in visuals. |

---

### 3. `edit_video` — Edit specific frames

Edits selected frames of an existing video using text prompts, then regenerates the video. Optionally combines all frames into one final video.

**Returns:** `VideoEditResult` (`.video_url`, `.job_id`; also supports `result["video_url"]`, `result.get("job_id")`)

**Example**

```python
from golpo import Golpo, VideoEditResult

client = Golpo(api_key="your-api-key")

# Use video_id from create_video result
result: VideoEditResult = client.edit_video(
    video_id="your-video-id",
    frame_ids=["0", "2", "5"],
    edit_prompts=[
        "Add a chart showing growth",
        "Change background to blue",
        "Add a callout to this section",
    ],
    video_url="https://..../original-video.mp4",
)
print(result.video_url)
print(result.job_id)

# With auto_combine: merge all frames into one video with audio
result = client.edit_video(
    video_id="your-video-id",
    frame_ids=["1"],
    edit_prompts=["Make the diagram larger"],
    video_url="https://..../original-video.mp4",
    auto_combine=True,
    poll_interval_ms=3000,
)
```

**Parameters**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `video_id` | `str` | required | Video/job ID (e.g. from `create_video`). |
| `frame_ids` | `List[str]` | required | Frame indices to edit. |
| `edit_prompts` | `List[str]` | required | One prompt per frame; length must match `frame_ids`. |
| `video_url` | `str` | required | URL of the original video. |
| `reference_images` | `List[str]` | `None` | Optional reference image URLs. |
| `user_id` | `str` | `None` | Optional user ID. |
| `poll_interval_ms` | `int` | `2000` | Polling interval in milliseconds. |
| `auto_combine` | `bool` | `False` | If `True`, combine all frames into one video with audio. |

---

### 4. `combine_videos` — Combine multiple videos

Combines several MP4 URLs into a single video. Useful for merging frame-level animations (e.g. after editing) with optional audio from an original video.

**Returns:** `CombinedVideoResult` (`.url`)

**Example**

```python
from golpo import Golpo, CombinedVideoResult

client = Golpo(api_key="your-api-key")

result: CombinedVideoResult = client.combine_videos(
    mp4_urls=[
        "https://..../frame-0.mp4",
        "https://..../frame-1.mp4",
        "https://..../frame-2.mp4",
    ],
    video_url="https://..../original-with-audio.mp4",  # Optional: use for audio
    poll_interval_ms=2000,
)
print(result.url)  # Combined video URL
```

**Parameters**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `mp4_urls` | `List[str]` | required | At least one MP4 URL. |
| `video_url` | `str` | `None` | Optional source video URL for audio. |
| `poll_interval_ms` | `int` | `2000` | Polling interval in milliseconds. |

---

### 5. `get_frame_animations` — Get frame animation URLs

Returns a mapping of frame index → animation URL for a video. Use this to inspect frame-level outputs or to pass URLs into `combine_videos`.

**Returns:** `Dict[str, str]` (frame index → animation URL)

**Example**

```python
from golpo import Golpo

client = Golpo(api_key="your-api-key")

animations = client.get_frame_animations(video_id="your-video-id")
# e.g. {"0": "https://.../frame-0.mp4", "1": "https://.../frame-1.mp4", ...}

for frame_id, url in animations.items():
    print(f"Frame {frame_id}: {url}")

# Use with combine_videos
urls = list(animations.values())
combined = client.combine_videos(mp4_urls=urls, video_url=original_video_url)
```

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `video_id` | `str` | Video/job ID (e.g. from `create_video`). |

---

## Result types

Import from `golpo`:

```python
from golpo import GenerationResult, VideoEditResult, CombinedVideoResult
```

| Type | Attributes | Used by |
|------|------------|--------|
| `GenerationResult` | `url`, `script`, `video_id` | `create_podcast`, `create_video` |
| `VideoEditResult` | `video_url`, `job_id` (and `["video_url"]`, `.get("job_id")`) | `edit_video` |
| `CombinedVideoResult` | `url` | `combine_videos` |

---

## Uploads (local files vs URLs)

- **URLs** (e.g. `https://...` or `s3://...`): Sent as-is in the `upload_urls` form field.
- **Local paths** (`str` or `pathlib.Path`): Uploaded to S3 via `/upload-url`, then the resulting URLs are sent. Uploads run in parallel (controlled by `max_workers`).

You can mix URLs and paths in a single list:

```python
client.create_video(
    prompt="...",
    uploads=[
        "https://example.com/doc.pdf",
        "./local-file.pdf",
        Path("~/Documents/other.pdf"),
    ],
)
```

---

## Errors

The SDK may raise:

- `ValueError` — Invalid arguments (e.g. empty prompt, mismatched `frame_ids`/`edit_prompts`, missing `video_url`).
- `FileNotFoundError` — A local path in `uploads` does not exist.
- `TimeoutError` — Edit/combine job did not complete within the allowed time.
- `requests.HTTPError` — API returned an error status (e.g. 4xx/5xx).

Handle these in your code as needed (retries, logging, user message).

---

## Links

- **Homepage:** [https://video.golpoai.com](https://video.golpoai.com)
- **Python:** Requires 3.8+