Golpo Python SDK

Latest: v1.0.0

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

Terminal
pip install golpo

Quick Start

Create a Golpo client with your API key:

quickstart.py
from golpo import Golpo

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

Method: Create Video

Stable

create_video uploads files (if local), starts video generation, waits until processing finishes, and returns a GenerationResult with url, script, and video_id.

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 for polling or use with get_frame_animations / edit_video

Parameters

ParameterTypeRequiredDefaultDescription
promptstrTopic or question for the video.
uploadsstr, Path, or iterableOptionalNoneLocal file paths or remote URLs (https://, http://, s3://).
voice_instructionsstrOptionalNoneVoice style instructions, e.g., "calm female".
personality_1strOptionalNonePrimary narrator persona, e.g., "historian".
do_researchboolOptionalFalseIf enabled, Golpo adds web research to your input documents.
video_typestrOptional"long"Type of video to generate: "long" for detailed videos.
include_watermarkboolOptionalTrueWhether to include Golpo watermark in the video.
logostr or PathOptionalNonePath to logo file or URL to include in video.
timingstrOptional"1"Timing parameter for video pacing.
tts_model"accurate" or "fast"Optional"accurate"Choose "accurate" for high quality, "fast" for quicker results.
languagestrOptional"en"Any language string ("en", "English", "Hindi", etc.).
stylestrOptional"solo-female"Video narration style: "solo-male" or "solo-female".
bg_musicstrOptional"engaging"Background music type: "engaging", "none", "jazz", "dramatic", or "lofi".
bg_volumefloatOptional1.4Background music volume (0.0 to 2.0). Only used when bg_music is not "none".
use_colorboolOptionalFalseCreate color videos.
video_instructionsstrOptionalNoneCustom instructions for video generation and visual style.
new_scriptstrOptionalNoneUse this script instead of generating one automatically.
just_return_scriptboolOptionalFalseIf True, only generate and return the script; do not create video.
poll_intervalintOptional2Seconds between status polls while waiting for completion.
max_workersintOptional8Max concurrent workers for local file uploads.
output_volumefloatOptional1.0Final output audio volume.

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}")
print(f"Script: {result.script}")

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}")
print(f"Script: {result.script}")

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}")
print(f"Script: {result.script}")

Using 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}")
print(f"Used script: {result.script}")

Complete example with imports and 10-minute video

Complete
complete_example.py
from 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

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

Parameters

ParameterTypeDescription
video_idstrThe video/job ID returned from create_video.

Returns

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

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: 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

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

ParameterTypeRequiredDescription
video_idstrVideo/job ID from create_video.
frame_idsList[str]Frame indices to edit (e.g. ["0", "2"]).
edit_promptsList[str]One prompt per frame (same length as frame_ids).
video_urlstrURL of the original video (e.g. result.url from create_video).
reference_imagesList[str]OptionalReference image URLs for the edit.
user_idstrOptionalUser ID for the edit job.
poll_interval_msintOptionalMilliseconds between status polls (default 2000).
auto_combineboolOptionalIf True, combine edited frames into a final video with audio (default False).

Returns

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

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: 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

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

ParameterTypeDescription
mp4_urlsList[str]At least one MP4 URL (e.g. from get_frame_animations).
video_urlOptional[str]Optional original video URL to use for audio.
poll_interval_msintPolling interval in ms while the combine job runs (default 2000).

Returns

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

example_combine_videos.py
# 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 TypeCommon CausesHow to Fix
FileNotFoundErrorIncorrect local file pathsVerify file paths
HTTPError (413)File too large for direct uploadUpload using URLs or presigned uploads
HTTPError (422)Invalid field dataConfirm parameter correctness
Select an API version from the sidebar to view detailed REST documentation.

API Only Tier

USAGE-BASED PLAN

Usage-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