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

This method uploads files (if local), starts video generation, waits until processing finishes, and returns a direct video URL and script.

Method Signature

method_signature.py
golpo_client.create_video(
    prompt: str,
    uploads: Optional[Union[str, Path, Iterable[Union[str, Path]]]] = None,
    *,
    voice_instructions: Optional[str] = None,
    video_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,
    use_color: bool = False,
    logo: Optional[str] = None,
    logo_placement: Optional[str] = "tl",
    timing: str = "1",
    new_script: Optional[str] = None,
) -> Tuple[str, str]

Returns

A tuple containing:

  • Video URL (str): Direct HTTPS URL to your final video (MP4)
  • Script (str): The generated script text used for the 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.
logostrOptionalNonePath to logo file or URL to include in video.
logo_placementstrOptional"tl"Controls where the logo is placed on the video when logo is provided and include_watermark is true. Valid values: "tl" (top-left, default), "tr" (top-right), "bl" (bottom-left), "br" (bottom-right). Logo is positioned with a 20-pixel margin from edges.
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_scriptstrOptionalNoneUpload your own custom script instead of generating one automatically.

Logo Placement Details

The logo_placement parameter controls where the logo is positioned on the video when both logo is provided and include_watermark is true.

Valid Values:

  • "tl" - Top-left corner (default)
  • "tr" - Top-right corner
  • "bl" - Bottom-left corner
  • "br" - Bottom-right corner

Visual Layout:

┌─────────────────────┐
│ [LOGO]              │  ← "tl" (top-left)
│                     │
│              [LOGO] │  ← "tr" (top-right)
│                     │
│                     │
│ [LOGO]              │  ← "bl" (bottom-left)
│              [LOGO] │  ← "br" (bottom-right)
└─────────────────────┘

Behavior:

  • Defaults to "tl" if not provided or if an invalid value is given
  • Logo is positioned with a 20-pixel margin from the video edges
  • Position is calculated relative to the video dimensions
  • Requires logo to be provided (URL or path to logo image)
  • Only takes effect when include_watermark is true
  • Logo image should be in PNG or JPEG format (transparency supported)
  • If logo loading fails, the video continues without the logo (warning logged)

Example:

{ "prompt": "Your video content", "logo": "https://example.com/logo.png", "logo_placement": "tr", "include_watermark": true }

Usage Examples

Simple example (prompt-only)

Basic
simple_example.py
video_url, script = golpo_client.create_video(prompt="Explain quantum computing simply")
print(f"Video URL: {video_url}")
print(f"Script: {script}")

Video from local files

Advanced
local_files.py
video_url, script = 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: {video_url}")
print(f"Script: {script}")

Video from remote URLs

Advanced
remote_urls.py
video_url, script = 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: {video_url}")
print(f"Script: {script}")

Custom branding with logo

Advanced
custom_branding.py
video_url, script = golpo_client.create_video(
    prompt="Combine these documents into an educational video",
    uploads=[
        "~/local.pdf",
        "https://example.com/remote.pdf"
    ],
    logo="~/company_logo.png",
    logo_placement="tr",
    include_watermark=False,
    bg_music="dramatic",
    bg_volume=1.2
)
print(f"Video URL: {video_url}")
print(f"Script: {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...
"""

video_url, script = 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: {video_url}")
print(f"Used script: {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
video_url, script = 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: {video_url}")
print(f"📝 Script preview: {script[:200]}...")
print(f"🎯 Full script length: {len(script)} characters")

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