Golpo Python SDK
The Golpo Python SDK helps you create whiteboard animation explainer videos from text prompts and documents. Features include uploading any document, choosing timing, voice instructions, background music, speaker personalities and more.
Installation
pip install golpoQuick Start
Create a Golpo client with your API key:
from golpo import Golpo
golpo_client = Golpo(api_key="your-api-key")Method: Create Video
Stablecreate_video uploads files (if local), starts video generation, waits until processing finishes, and returns a GenerationResult with url, script, and video_id.
Method Signature
result = golpo_client.create_video(
prompt: str,
uploads: Optional[Union[str, Path, Iterable[Union[str, Path]]]] = None,
*,
voice_instructions: Optional[str] = None,
personality_1: Optional[str] = None,
do_research: bool = False,
tts_model: str = "accurate",
language: Optional[str] = None,
style: Optional[str] = "solo-female",
bg_music: Optional[str] = "engaging",
bg_volume: float = 1.4,
video_type: Optional[str] = "long",
include_watermark: bool = True,
new_script: Optional[str] = None,
just_return_script: bool = False,
logo: Optional[Union[str, Path]] = None,
timing: str = "1",
poll_interval: int = 2,
max_workers: int = 8,
output_volume: float = 1.0,
video_instructions: Optional[str] = None,
use_color: bool = False,
) -> GenerationResult # .url, .script, .video_idReturns
GenerationResult with:
url(str): Direct HTTPS URL to your final video (MP4)script(str): The generated script text used for the videovideo_id(str): Job ID for polling or use withget_frame_animations/edit_video
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| prompt | str | ✓ | — | Topic or question for the video. |
| uploads | str, Path, or iterable | Optional | None | Local file paths or remote URLs (https://, http://, s3://). |
| voice_instructions | str | Optional | None | Voice style instructions, e.g., "calm female". |
| personality_1 | str | Optional | None | Primary narrator persona, e.g., "historian". |
| do_research | bool | Optional | False | If enabled, Golpo adds web research to your input documents. |
| video_type | str | Optional | "long" | Type of video to generate: "long" for detailed videos. |
| include_watermark | bool | Optional | True | Whether to include Golpo watermark in the video. |
| logo | str or Path | Optional | None | Path to logo file or URL to include in video. |
| timing | str | Optional | "1" | Timing parameter for video pacing. |
| tts_model | "accurate" or "fast" | Optional | "accurate" | Choose "accurate" for high quality, "fast" for quicker results. |
| language | str | Optional | "en" | Any language string ("en", "English", "Hindi", etc.). |
| style | str | Optional | "solo-female" | Video narration style: "solo-male" or "solo-female". |
| bg_music | str | Optional | "engaging" | Background music type: "engaging", "none", "jazz", "dramatic", or "lofi". |
| bg_volume | float | Optional | 1.4 | Background music volume (0.0 to 2.0). Only used when bg_music is not "none". |
| use_color | bool | Optional | False | Create color videos. |
| video_instructions | str | Optional | None | Custom instructions for video generation and visual style. |
| new_script | str | Optional | None | Use this script instead of generating one automatically. |
| just_return_script | bool | Optional | False | If True, only generate and return the script; do not create video. |
| poll_interval | int | Optional | 2 | Seconds between status polls while waiting for completion. |
| max_workers | int | Optional | 8 | Max concurrent workers for local file uploads. |
| output_volume | float | Optional | 1.0 | Final output audio volume. |
Usage Examples
Simple example (prompt-only)
Basicresult = golpo_client.create_video(prompt="Explain quantum computing simply")
print(f"Video URL: {result.url}")
print(f"Script: {result.script}")
print(f"Video ID: {result.video_id}")Video from local files
Advancedresult = golpo_client.create_video(
prompt="Summarize these privacy documents",
uploads=["~/Documents/privacy_policy.pdf"],
voice_instructions="calm professional female",
personality_1="privacy expert",
bg_music="engaging",
include_watermark=False
)
print(f"Video URL: {result.url}")
print(f"Script: {result.script}")Video from remote URLs
Advancedresult = golpo_client.create_video(
prompt="Analyze these articles",
uploads=[
"https://example.com/article1.pdf",
"https://example.com/article2.pdf"
],
do_research=True,
personality_1="historian",
style="solo-male",
video_type="long"
)
print(f"Video URL: {result.url}")
print(f"Script: {result.script}")Custom branding with logo
Advancedresult = golpo_client.create_video(
prompt="Combine these documents into an educational video",
uploads=[
"~/local.pdf",
"https://example.com/remote.pdf"
],
logo="~/company_logo.png",
include_watermark=False,
bg_music="dramatic",
bg_volume=1.2
)
print(f"Video URL: {result.url}")
print(f"Script: {result.script}")Using custom script
Customcustom_script = """
Welcome to our presentation on artificial intelligence.
Today we'll explore the fascinating world of machine learning.
First, let's understand what AI actually means...
"""
result = golpo_client.create_video(
prompt="Create a video about AI",
new_script=custom_script,
style="solo-female",
bg_music="engaging",
include_watermark=False
)
print(f"Video URL: {result.url}")
print(f"Used script: {result.script}")Complete example with imports and 10-minute video
Completefrom golpo import Golpo
from pathlib import Path
# Initialize the Golpo client with your API key
golpo_client = Golpo(api_key="your-api-key-here")
# Create a comprehensive 10-minute video with local files
result = golpo_client.create_video(
prompt="Create a comprehensive analysis of these business documents",
uploads=[
"~/Documents/business_plan.pdf",
"~/Documents/financial_report.xlsx",
"~/Documents/market_research.docx"
],
timing="10",
use_color=True,
style="solo-female",
bg_music="engaging",
bg_volume=1.3,
include_watermark=False,
video_type="long"
)
print(f"✅ Video generation completed!")
print(f"🎬 Video URL: {result.url}")
print(f"📝 Script preview: {result.script[:200]}...")
print(f"🎯 Full script length: {len(result.script)} characters")Method: Get Frame Animations
get_frame_animations(video_id) returns a dictionary mapping frame indices to animation URLs for a generated video. Use this after create_video to get per-frame MP4 URLs for editing or combining.
Method Signature
frame_animations: Dict[str, str] = golpo_client.get_frame_animations(video_id: str)Parameters
| Parameter | Type | Description |
|---|---|---|
| video_id | str | The video/job ID returned from create_video. |
Returns
Dict[str, str] — frame IDs (e.g. "0", "1") mapped to MP4 animation URLs.
result = golpo_client.create_video(prompt="Explain AI in 2 minutes")
animations = golpo_client.get_frame_animations(result.video_id)
for frame_id, url in sorted(animations.items(), key=lambda x: int(x[0])):
print(f"Frame {frame_id}: {url}")Method: Edit Video
edit_video edits specific frames of a video using text prompts, then optionally combines the edited frames into a final video. Use the video_id and url from create_video.
Method Signature
result = golpo_client.edit_video(
video_id: str,
frame_ids: List[str],
edit_prompts: List[str],
video_url: str,
*,
reference_images: Optional[List[str]] = None,
user_id: Optional[str] = None,
poll_interval_ms: int = 2000,
auto_combine: bool = False
) -> VideoEditResult # .video_url, .job_idParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| video_id | str | ✓ | Video/job ID from create_video. |
| frame_ids | List[str] | ✓ | Frame indices to edit (e.g. ["0", "2"]). |
| edit_prompts | List[str] | ✓ | One prompt per frame (same length as frame_ids). |
| video_url | str | ✓ | URL of the original video (e.g. result.url from create_video). |
| reference_images | List[str] | Optional | Reference image URLs for the edit. |
| user_id | str | Optional | User ID for the edit job. |
| poll_interval_ms | int | Optional | Milliseconds between status polls (default 2000). |
| auto_combine | bool | Optional | If True, combine edited frames into a final video with audio (default False). |
Returns
VideoEditResult with video_url (str) and job_id (str).
video_result = golpo_client.create_video(prompt="Product demo in 3 scenes")
edit_result = golpo_client.edit_video(
video_id=video_result.video_id,
frame_ids=["1"],
edit_prompts=["Replace the background with a beach sunset"],
video_url=video_result.url,
auto_combine=True
)
print(f"Edited video URL: {edit_result.video_url}")Method: Combine Video
combine_videos merges multiple MP4 URLs into a single video. Typically used with frame animation URLs from get_frame_animations or after editing frames.
Method Signature
result = golpo_client.combine_videos(
mp4_urls: List[str],
*,
video_url: Optional[str] = None,
poll_interval_ms: int = 2000
) -> CombinedVideoResult # .urlParameters
| Parameter | Type | Description |
|---|---|---|
| mp4_urls | List[str] | At least one MP4 URL (e.g. from get_frame_animations). |
| video_url | Optional[str] | Optional original video URL to use for audio. |
| poll_interval_ms | int | Polling interval in ms while the combine job runs (default 2000). |
Returns
CombinedVideoResult with url (str) — the URL of the combined video.
# video_id and original_video_url from a previous create_video result
animations = golpo_client.get_frame_animations(video_id)
mp4_urls = [animations[k] for k in sorted(animations.keys(), key=int)]
combined = golpo_client.combine_videos(mp4_urls, video_url=original_video_url)
print(f"Combined video: {combined.url}")Error Handling
| Error Type | Common Causes | How to Fix |
|---|---|---|
| FileNotFoundError | Incorrect local file paths | Verify file paths |
| HTTPError (413) | File too large for direct upload | Upload using URLs or presigned uploads |
| HTTPError (422) | Invalid field data | Confirm parameter correctness |
API Only Tier
USAGE-BASED PLANUsage-based pricing with volume discounts
This plan is for using Golpo within your program/application. You'll NOT be able to use the Golpo platform to generate videos. This plan is usage-based plan with a minimum cost of $200 to enter. This plan is perfect for developers and businesses who need programmatic access to video generation. Pay only for what you use with volume-based pricing that gets better as you scale.
Pricing Rates
Credit Conversion
$1 = 1 Credit
Video Generation
1 min video = 2 Credits