v0.9.9 — LatestPython 3.8+

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.

Terminal

pip install golpo

quickstart.py

from golpo import Golpo

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

Method Signature

method_signature.py

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_id

Returns

GenerationResult with:

url(str)Direct HTTPS URL to your final video (MP4)
script(str)The generated script text used for the video
video_id(str)Job ID — use with get_frame_animations or edit_video

Parameters

Parameter	Type	Default	Required	Description
prompt	str	—	Required	Topic or question for the video.
uploads	str, Path, or iterable	None	Optional	Local file paths or remote URLs (https://, http://, s3://).
voice_instructions	str	None	Optional	Voice style instructions, e.g. "calm female".
personality_1	str	None	Optional	Primary narrator persona, e.g. "historian".
do_research	bool	False	Optional	Enable web research to supplement input documents.
tts_model	"accurate" \| "fast"	"accurate"	Optional	Choose "accurate" for high quality, "fast" for quicker results.
language	str	"en"	Optional	Any language string ("en", "English", "Hindi", etc.).
style	str	"solo-female"	Optional	"solo-male" or "solo-female".
bg_music	str	"engaging"	Optional	"engaging", "none", "jazz", "dramatic", or "lofi".
bg_volume	float	1.4	Optional	Background music volume (0.0–2.0). Used when bg_music is not "none".
output_volume	float	1.0	Optional	Final output audio volume.
video_type	str	"long"	Optional	Controls video aspect ratio. "short" for vertical/portrait (9:16, 1024×1536 px), "long" for horizontal/landscape (16:9, 1536×1024 px).
include_watermark	bool	True	Optional	Include Golpo watermark in the video.
logo	str or Path	None	Optional	Path to logo file or URL to include in the video.
timing	str	"1"	Optional	Timing parameter for video pacing.
new_script	str	None	Optional	Use this script instead of generating one automatically.
just_return_script	bool	False	Optional	If True, only generate and return the script; do not create video.
use_color	bool	False	Optional	Create color videos.
video_instructions	str	None	Optional	Custom instructions for video generation and visual style.
poll_interval	int	2	Optional	Seconds between status polls while waiting for completion.
max_workers	int	8	Optional	Max concurrent workers for local file uploads.

Usage Examples

Simple example (prompt only)

Basic

simple_example.py

result = 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

Advanced

local_files.py

result = 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}")

Video from remote URLs

Advanced

remote_urls.py

result = 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}")

Custom branding with logo

Advanced

custom_branding.py

result = 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}")

Using a custom script

Custom

custom_script.py

custom_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}")

Complete 10-minute video

Complete

complete_example.py

from golpo import Golpo

golpo_client = Golpo(api_key="your-api-key-here")

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 URL:       {result.url}")
print(f"Script preview:  {result.script[:200]}...")

Method Signature

get_frame_animations.py

frame_animations: Dict[str, str] = golpo_client.get_frame_animations(video_id: str)

Parameters

Parameter	Type	Default	Required	Description
video_id	str	—	Required	The video/job ID returned from `create_video`.

Returns

Dict[str, str] — frame IDs (e.g. "0", "1") mapped to MP4 animation URLs.

Example

example_get_frame_animations.py

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 Signature

edit_video.py

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_id

Parameters

Parameter	Type	Default	Required	Description
video_id	str	—	Required	Video/job ID from `create_video`.
frame_ids	List[str]	—	Required	Frame indices to edit (e.g. `["0", "2"]`).
edit_prompts	List[str]	—	Required	One prompt per frame (same length as frame_ids).
video_url	str	—	Required	URL of the original video (`result.url` from create_video).
reference_images	List[str]	None	Optional	Reference image URLs for the edit.
user_id	str	None	Optional	User ID for the edit job.
poll_interval_ms	int	2000	Optional	Milliseconds between status polls.
auto_combine	bool	False	Optional	If True, combine edited frames into a final video with audio.

Returns

VideoEditResult with video_url (str) and job_id (str).

Example

example_edit_video.py

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 Signature

combine_videos.py

result = golpo_client.combine_videos(
    mp4_urls:         List[str],
    *,
    video_url:        Optional[str] = None,
    poll_interval_ms: int = 2000,
) -> CombinedVideoResult  # .url

Parameters

Parameter	Type	Default	Required	Description
mp4_urls	List[str]	—	Required	At least one MP4 URL (e.g. from `get_frame_animations`).
video_url	Optional[str]	None	Optional	Optional original video URL to use for audio.
poll_interval_ms	int	2000	Optional	Polling interval in ms while the combine job runs.

Returns

CombinedVideoResult — url (str), the URL of the combined video.

Example

example_combine_videos.py

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}")

Parameter	Type	Default	Required	Description
FileNotFoundError	—	—	Optional	Cause: Incorrect local file paths. Fix: Verify file paths.
HTTPError (413)	—	—	Optional	Cause: File too large for direct upload. Fix: Upload via URLs or presigned uploads.
HTTPError (422)	—	—	Optional	Cause: Invalid field data. Fix: Confirm parameter correctness.

Golpo Python SDK

Installation

Quick Start

create_video

Method Signature

Returns

Parameters

Usage Examples

get_frame_animations

Method Signature

Parameters

Returns

Example

edit_video

Method Signature

Parameters

Returns

Example

combine_videos

Method Signature

Parameters

Returns

Example

Error Handling