v1.0.2 — LatestPython 3.8+

The Golpo Python SDK helps you create whiteboard animation explainer videos and podcasts from text prompts and documents. Features include uploading any document, choosing timing, voice instructions, background music, and more.

What's new in v1.0.2

user_audio_in_video now accepts List[int] — use integers (e.g., [1, 3]) to specify which user videos get AI-generated narration. Do not use List[bool].

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,
    language:           Optional[str] = None,
    style:              Optional[str] = "solo-female-3",
    bg_music:           Optional[str] = "engaging",
    video_type:         Optional[str] = "long",
    include_watermark:  bool = False,
    new_script:         Optional[str] = None,
    just_return_script: bool = False,
    logo:               Optional[Union[str, Path]] = None,
    logo_placement:     Optional[str] = None,
    timing:             Union[str, float] = "1",
    poll_interval:      int = 2,
    video_instructions: Optional[str] = None,
    use_color:          bool = True,
    # ── New in v1.0.0 ──
    use_lineart_2_style:      Optional[str] = None,
    audio_clip:               Optional[Union[str, Path]] = None,
    is_public:                Optional[bool] = None,
    use_as_is:                Optional[Union[str, List[bool]]] = None,
    skip_animation:           Optional[Union[str, List[bool]]] = None,
    user_images:              Optional[Union[str, Path, List[Union[str, Path]]]] = None,
    user_images_descriptions: Optional[Union[str, List[str]]] = None,
    user_videos:              Optional[Union[str, Path, List[Union[str, Path]]]] = None,
    user_videos_description:  Optional[Union[str, List[str]]] = None,
    user_audio_in_video:      Optional[Union[str, List[int]]] = None,
    use_2_style:              bool = False,
    image_style:              Optional[str] = None,
    input_images:             Optional[Union[str, Path, List[Union[str, Path]]]] = None,
    pen_style:                Optional[str] = None,
    show_pencil_cursor:       bool = False,
    pacing:                   str = "normal",
    display_language:         Optional[str] = None,
) -> 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". Describes how the voice should sound — accent, tone, pace. Example: "Speak in a warm British accent with a calm, professorial tone."
language	str	None	Optional	Any language string ("en", "English", "Hindi", etc.). 44+ languages supported.
style	str	"solo-female-3"	Optional	"solo-female-3", "solo-female-4", "solo-male-3", or "solo-male-4". See the Style & Voices reference section for full voice descriptions.
bg_music	str	"engaging"	Optional	"engaging", "jazz", "lofi", "dramatic", "whimsical", "hyper", "inspirational", or "documentary".
video_type	str	"long"	Optional	"short" for vertical/portrait, "long" for horizontal/landscape.
include_watermark	bool	False	Optional	Include Golpo watermark in the video.
logo	str or Path	None	Optional	Path to logo file or URL. Automatically enables watermark.
logo_placement	str	None	Optional	Position of the logo on the video.
timing	str or float	"1"	Optional	Video duration in minutes (0.25–10). Auto-calculated when new_script is provided. Supported values: 0.25, 0.5, 1, 2, 4, 8, 10. Values 8 and 10 are in Beta.
new_script	str	None	Optional	Use this script instead of generating one. Auto-estimates timing from word count.
just_return_script	bool	False	Optional	If True, only generate and return the script; do not create video.
use_color	bool	True	Optional	Create color videos instead of black-and-white.
video_instructions	str	None	Optional	Custom instructions for video generation and visual style. Describes how the video should look — visuals, style, and scene direction. Example: "Use clean corporate visuals with data charts."
poll_interval	int	2	Optional	Seconds between status polls while waiting for completion.

New Parameters in v1.0.0 NEW

Parameter	Type	Default	Required	Description
use_lineart_2_style	str	None	Optional	Golpo Sketch style: "false" (classic), "true" (improved), or "advanced" (formal). NOTE:Do not combine with use_2_style (Golpo Canvas). Use one or the other.
audio_clip	str or Path	None	Optional	Audio or video file path or URL. The audio will be extracted and included in the video generation. Local files are auto-uploaded to S3. Accepts both audio (MP3, WAV) and video (MP4) files.
is_public	bool	None	Optional	Set video visibility to public or private.
use_as_is	str or List[bool]	None	Optional	Per-frame flags to use generated images as-is without animation. Pass as JSON array string or Python list. One boolean per frame. Example: [True, False, True] — frames 0 and 2 will use images as-is.
skip_animation	str or List[bool]	None	Optional	Per-frame flags to skip the drawing animation. Pass as JSON array string or Python list. One boolean per frame. Example: [False, True, False] — frame 1 will skip animation.
user_images	str, Path, or List	None	Optional	User-provided images (file paths or URLs). Local files are auto-uploaded to S3.
user_images_descriptions	str or List[str]	None	Optional	Descriptions for each user image. Strongly recommended for best visual results. NOTE:Provide one description per image for best results. Descriptions help the AI understand and position images correctly.
user_videos	str, Path, or List	None	Optional	User-provided video clips (file paths or URLs). Local files are auto-uploaded to S3.
user_videos_description	str or List[str]	None	Optional	Descriptions for each user video. NOTE:Provide one description per video for best results.
user_audio_in_video	str or List[int]	None	Optional	List of video numbers that should use AI-generated narration audio instead of their original audio (e.g., [1, 3] means videos 1 and 3 get AI narration; unlisted user videos keep their original audio). NOTE:Only applies when user_videos is provided. If omitted or empty, all user videos retain their original audio.
use_2_style	bool	False	Optional	Enable Golpo Canvas visual style. NOTE:Do not combine with use_lineart_2_style (Golpo Sketch). Use one or the other.
image_style	str	None	Optional	Golpo Canvas image style: "chalkboard_white", "neon", "whiteboard", "modern_minimal", "playful", "technical", "editorial", or "marker". NOTE:Only available when Golpo Canvas is enabled (use_2_style=True).
input_images	str, Path, or List	None	Optional	Reference input images for Golpo Canvas. The video will be generated around the provided images. NOTE:Only available when Golpo Canvas is enabled (use_2_style=True).
pen_style	str	None	Optional	Drawing pen style: "stylus", "marker", or "pen". NOTE:Only available when Golpo Canvas is enabled (use_2_style=True).
show_pencil_cursor	bool	False	Optional	Show a pencil cursor during drawing animation. NOTE:Only available when Golpo Canvas is enabled (use_2_style=True).
pacing	str	"normal"	Optional	"normal" (15s max per frame) or "fast" (10s max per frame).
display_language	str	None	Optional	Language for on-screen text in the video (e.g., 'English', 'Hindi', 'French'). Useful when the displayed text should differ from the narration language. Defaults to the value of language if omitted. Example: language: "Hindi", display_language: "English" — the narrator speaks in Hindi while all on-screen text, titles, and labels are shown in English.

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",
    bg_music="engaging",
)
print(f"Video URL: {result.url}")

Golpo Canvas — Modern Minimal

Canvas

canvas_modern_minimal.py

result = golpo_client.create_video(
    prompt="How solar panels convert sunlight to electricity",
    use_2_style=True,
    image_style="modern_minimal",
    pen_style="stylus",
    timing="2",
)
print(f"Video URL: {result.url}")

Golpo Canvas — Neon Chalkboard

Canvas

canvas_neon.py

result = golpo_client.create_video(
    prompt="Explain the water cycle for kids",
    use_2_style=True,
    image_style="neon",
    pen_style="marker",
    bg_music="whimsical",
    style="solo-female-3",
)
print(f"Video URL: {result.url}")

Golpo Sketch — Improved style

Sketch

sketch_improved.py

result = golpo_client.create_video(
    prompt="Explain blockchain technology step by step",
    use_lineart_2_style="true",
    pacing="normal",
    bg_music="engaging",
    style="solo-male-3",
    timing="2",
)
print(f"Video URL: {result.url}")

Golpo Sketch — Advanced (Formal)

Sketch

sketch_advanced.py

result = golpo_client.create_video(
    prompt="The evolution of artificial intelligence",
    use_lineart_2_style="advanced",
    pacing="fast",
    bg_music="documentary",
    style="solo-female-3",
    timing="4",
)
print(f"Video URL: {result.url}")

User images with descriptions

New

user_media.py

result = golpo_client.create_video(
    prompt="Create a product showcase video",
    user_images=["~/product_photo_1.png", "~/product_photo_2.png"],
    user_images_descriptions=["Front view of the product", "Side view with packaging"],
    use_2_style=True,
    image_style="modern_minimal",
    pen_style="stylus",
)
print(f"Video URL: {result.url}")

User video clips

New

user_videos.py

result = golpo_client.create_video(
    prompt="Create an explainer incorporating these demo clips",
    user_videos=["~/demo_clip_1.mp4", "https://example.com/clip2.mp4"],
    user_videos_description=["App walkthrough demo", "Feature highlight reel"],
    user_audio_in_video=[2],  # video 2 gets AI narration; video 1 keeps its original audio
    audio_clip="~/background_music.mp3",
    is_public=True,
)
print(f"Video URL: {result.url}")

Hindi narration with English on-screen text (display_language)

Advanced

display_language.py

result = golpo_client.create_video(
    prompt="Flower Structure for Reproduction",
    language="Hindi",           # narrator speaks in Hindi
    display_language="English", # on-screen text, titles, and labels appear in English
    style="solo-female-4",
    use_color=True,
    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",
    logo_placement="right-top",
    bg_music="dramatic",
)
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-3",
    bg_music="engaging",
    video_type="long",
    use_2_style=True,
    image_style="editorial",
    pacing="normal",
)

print(f"Video URL:       {result.url}")
print(f"Script preview:  {result.script[:200]}...")

Method Signature

create_podcast.py

result = golpo_client.create_podcast(
    prompt: str,
    uploads: Optional[Union[str, Path, Iterable[Union[str, Path]]]] = None,
    *,
    voice_instructions: Optional[str] = None,
    language:           Optional[str] = None,
    style:              Optional[str] = "solo-female-3",
    bg_music:           Optional[str] = None,
    new_script:         Optional[str] = None,
    timing:             Union[str, float] = "1",
    poll_interval:      int = 2,
) -> GenerationResult  # .url, .script, .video_id

Returns

GenerationResult with:

url(str)Direct HTTPS URL to your generated podcast audio
script(str)The generated script text used for the podcast
video_id(str)Job ID for tracking the generation

Parameters

Parameter	Type	Default	Required	Description
prompt	str	—	Required	Topic or question for the podcast.
uploads	str, Path, or iterable	None	Optional	Local file paths or remote URLs to use as source material.
voice_instructions	str	None	Optional	Voice style instructions, e.g. "calm and professional".
language	str	None	Optional	Any language string ("en", "English", "Hindi", etc.).
style	str	"solo-female-3"	Optional	"solo-female-3", "solo-female-4", "solo-male-3", or "solo-male-4".
bg_music	str	None	Optional	"jazz", "lofi", "dramatic", "whimsical", "engaging", "hyper", "inspirational", or "documentary".
new_script	str	None	Optional	Use this script instead of generating one. Auto-estimates timing from word count.
timing	str or float	"1"	Optional	Podcast duration in minutes.
poll_interval	int	2	Optional	Seconds between status polls while waiting for completion.

Podcast Examples

Basic podcast

Basic

basic_podcast.py

result = golpo_client.create_podcast(
    prompt="Discuss the future of renewable energy",
    style="solo-female-3",
    bg_music="lofi",
)
print(f"Podcast URL: {result.url}")

Solo podcast from documents

Advanced

solo_podcast.py

result = golpo_client.create_podcast(
    prompt="Summarize these research papers into a podcast episode",
    uploads=[
        "~/research/paper1.pdf",
        "https://example.com/paper2.pdf",
    ],
    style="solo-female-3",
    voice_instructions="engaging and informative",
    timing="5",
    bg_music="documentary",
)
print(f"Podcast URL: {result.url}")

Podcast with custom script

Custom

custom_podcast.py

podcast_script = """
Welcome back to Tech Talk! Today we're diving into AI assistants.
It's a fascinating topic that's reshaping how we work...
"""

result = golpo_client.create_podcast(
    prompt="Tech Talk podcast episode on AI assistants",
    new_script=podcast_script,
    style="solo-male-3",
    bg_music="engaging",
)
print(f"Podcast URL: {result.url}")

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

Method Signature

update_video.py

result = golpo_client.update_video(
    video_id: str,
    *,
    prompt:           Optional[str] = None,
    context:          Optional[str] = None,
    scenes:           Optional[int] = None,
    video_url:        Optional[str] = None,
    frame_animations: Optional[Dict[str, Any]] = None,
    jwt_token:        str,  # Required
) -> Dict[str, Any]

Parameters

Parameter	Type	Default	Required	Description
video_id	str	—	Required	The ID of the video to update.
jwt_token	str	—	Required	JWT token for authentication.
prompt	str	None	Optional	New prompt for the video.
context	str	None	Optional	New context for the video.
scenes	int	None	Optional	Number of scenes.
video_url	str	None	Optional	New video URL.
frame_animations	Dict[str, Any]	None	Optional	Frame animations dictionary to update.

Returns

Dict[str, Any] — Dictionary with the updated video data from the API.

Example

example_update_video.py

updated = golpo_client.update_video(
    video_id=result.video_id,
    prompt="Updated: comprehensive product overview",
    context="Q1 2025 product launch",
    scenes=5,
    jwt_token="your-jwt-token",
)
print(f"Updated video: {updated}")

Value	Voice Type	Description
"solo-female-3"	Female 1	Female narrator voice (Default)
"solo-female-4"	Female 2	Alternative female narrator voice
"solo-male-3"	Male 1	Male narrator voice
"solo-male-4"	Male 2	Alternative male narrator voice

bg_music key	Mood / Usage
"jazz"	Warm, neutral bed
"lofi"	Calm, study vibes
"whimsical"	Playful, upbeat
"dramatic"	Cinematic tension
"engaging"	Subtle corporate pulse (Default for videos)
"hyper"	High-energy electronic
"inspirational"	Uplifting orchestral
"documentary"	Serious factual tone

Value	Style Name	Description
"false"	Classic (Default)	Original Golpo Sketch — classic whiteboard line-art animation
"true"	Improved (Beta)	Improved line-art with cleaner strokes and a more polished look
"advanced"	Formal	Advanced sketch generation with higher detail and refined aesthetics

Do not combine use_lineart_2_style (Golpo Sketch) with use_2_style (Golpo Canvas). Use one or the other. Use the pacing parameter with Golpo Sketch: "normal" (15s max per frame) or "fast" (10s max per frame).

Set use_2_style=True to enable Golpo Canvas. Then use image_style to set the visual look, optionally pen_style to add a drawing cursor effect, and pacing to control animation speed.

NOTE:pen_style, image_style, show_pencil_cursor, and input_images are only applicable for Golpo Canvas (use_2_style=True). Do not use with Golpo Sketch.

Value	Label	Description
"chalkboard_white"	Chalkboard (B/W)	Black & white chalkboard style (Default)
"neon"	Chalkboard Color	Colorful neon chalkboard style
"whiteboard"	Whiteboard	Clean whiteboard illustrations
"modern_minimal"	Modern Minimal	Sleek, minimal modern aesthetic
"playful"	Playful	Fun, colorful playful illustrations
"technical"	Technical	Technical diagram style
"editorial"	Editorial	Magazine/editorial illustration style
"marker"	Sharpie	Bold marker/sharpie drawn style

Value	Description
"stylus"	Thin stylus pen cursor — ideal for technical/minimal styles
"marker"	Thick marker cursor — great for playful/sharpie styles
"pen"	Classic pen cursor — suits editorial/whiteboard styles

When pen_style is set, show_pencil_cursor is automatically enabled. You only need to set show_pencil_cursor=True explicitly if you want the default cursor without choosing a specific pen style.

Value	Duration
0.25	15 seconds
0.5	30 seconds
1	1 minute (Default)
2	2 minutes
4	4 minutes
8	8 minutes (Beta)
10	10 minutes (Beta)

Value	Format	Use Cases
"short"	Vertical / Portrait	TikTok, Instagram Reels, YouTube Shorts
"long"	Horizontal / Landscape (Default)	YouTube, standard video content

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.
ValueError	—	—	Optional	Cause: Invalid parameter values (e.g. timing below 0.25, mismatched frame_ids/edit_prompts). Fix: Check parameter constraints.
TimeoutError	—	—	Optional	Cause: Edit or combine job exceeded max polling attempts. Fix: Retry the operation or increase poll_interval_ms.

Golpo Python SDK

Installation

Quick Start

create_video

Method Signature

Returns

Parameters

New Parameters in v1.0.0 NEW

Usage Examples

create_podcast

Method Signature

Returns

Parameters

Podcast Examples

get_frame_animations

Method Signature

Parameters

Returns

Example

edit_video

Method Signature

Parameters

Returns

Example

combine_videos

Method Signature

Parameters

Returns

Example

update_video

Method Signature

Parameters

Returns

Example

Style & Voices

Background Music

Golpo Sketch Styles

Golpo Canvas Styles

Image Style

Pen Style

Timing

Video Type

Error Handling