golpo 0.9.9

Python SDK for Golpo AI-generated explainer videos and podcasts.

Golpo Python SDK

Python SDK for Golpo — generate AI-powered explainer videos and podcasts from text and documents.

Installation

pip install golpo

Quick start

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

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

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

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

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

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

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:

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:

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
• Python: Requires 3.8+