Golpo Python SDK

Python SDK for Golpo — generate AI-powered explainer videos and podcasts from text and documents.

Installation

pip install golpo

Quick start

from golpo import Golpo

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

# Submit a video generation job
job = client.create_video(prompt="Explain quantum computing in 2 minutes")
print(job.video_id)  # Job ID

# Check status
status = client.get_video_status(job.video_id)
print(status.status)  # processing | completed | failed
if status.status == "completed":
    print(status.url)
    print(status.script)

Client setup

from golpo import Golpo

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

API reference

1. create_podcast — Generate a podcast

Submits an AI-generated podcast job from a prompt and optional documents. Returns immediately with a job ID.

Returns: VideoJobResult (.video_id, .status, optional .variant_job_ids)

Example

from golpo import Golpo, VideoJobResult

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

# Prompt only
job: VideoJobResult = client.create_podcast(
    prompt="Create a 5-minute podcast about climate change and renewable energy."
)
print(job.video_id)  # Job ID
print(job.status)    # processing

# With document URLs (no upload)
job = client.create_podcast(
    prompt="Summarize this document and discuss key points.",
    uploads=["https://example.com/document.pdf"],
)

# With local files (uploaded to S3 automatically)
job = client.create_podcast(
    prompt="Turn this into an explainer podcast.",
    uploads=["./my-doc.pdf", Path("./other-doc.pdf")],
    style="solo-female-3",
    bg_music="lofi",
)

# Poll using unified status endpoint
status = client.get_video_status(job.video_id)
if status.status == "completed":
    print(status.url)     # podcast URL
    print(status.script)  # generated script

Parameters

2. create_video — Generate a video

Submits an AI-generated explainer video job from a prompt and optional documents. Returns immediately with a job ID.

Returns: VideoJobResult (.video_id, .status, optional .variant_job_ids)

Example

from golpo import Golpo, VideoJobResult

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

job: VideoJobResult = client.create_video(
    prompt="Create a 2-minute explainer on how photosynthesis works.",
)
print(job.video_id)  # Job ID
print(job.status)    # processing

# Golpo Canvas style
result = client.create_video(
    prompt="How solar panels convert sunlight to electricity",
    use_2_style=True,
    image_style="modern_minimal",
    pen_style="stylus",
    timing="2",
)

# Golpo Sketch style
result = client.create_video(
    prompt="Explain blockchain technology step by step",
    use_lineart_2_style="true",
    pacing="normal",
    timing="2",
)

# With user-provided images and videos
result = 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"],
    user_videos=["~/demo_clip.mp4"],
    user_videos_description=["App walkthrough demo"],
    user_audio_in_video=[1],  # video 1 gets AI narration; video 2 keeps its original audio
    timing="2",
)

# Script only mode submission
job = client.create_video(
    prompt="Explain recursion in programming",
    just_return_script=True,
)
print(job.video_id)

Parameters

3. get_video_status — Check video generation status

Checks one submitted generation job by job_id. The SDK auto-selects the backend status endpoint from the submitted request payload:

• just_return_script=True -> /script-status/{job_id}
• otherwise -> /status/{job_id}

Returns: VideoStatusResult (.video_id, .status, .url, .script, .error)

Example

from golpo import Golpo, VideoStatusResult

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

job = client.create_video(prompt="Explain recursion in programming")
status: VideoStatusResult = client.get_video_status(job.video_id)
print(status.status)

if status.status == "completed":
    print(status.url)
    print(status.script)
elif status.status == "failed":
    print(status.error)

# For script-only jobs, SDK auto-detects mode from request payload
script_job = client.create_video(prompt="...", just_return_script=True)
script_status = client.get_video_status(script_job.video_id)
if script_status.status in ("completed", "script_ready"):
    print(script_status.script)

Parameters

4. edit_video — Edit specific frames

Edits selected frames of an existing video using text prompts, then regenerates the video. Optionally combines all frames into one final video.

Returns: VideoEditResult (.video_url, .job_id; also supports result["video_url"], result.get("job_id"))

Example

from golpo import Golpo, VideoEditResult

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

# Use video_id from create_video result
result: VideoEditResult = client.edit_video(
    video_id="your-video-id",
    frame_ids=["0", "2", "5"],
    edit_prompts=[
        "Add a chart showing growth",
        "Change background to blue",
        "Add a callout to this section",
    ],
    video_url="https://..../original-video.mp4",
)
print(result.video_url)
print(result.job_id)

# With auto_combine: merge all frames into one video with audio
result = client.edit_video(
    video_id="your-video-id",
    frame_ids=["1"],
    edit_prompts=["Make the diagram larger"],
    video_url="https://..../original-video.mp4",
    auto_combine=True,
    poll_interval_ms=3000,
)

Parameters

5. combine_videos — Combine multiple videos

Combines several MP4 URLs into a single video. Useful for merging frame-level animations (e.g. after editing) with optional audio from an original video.

Returns: CombinedVideoResult (.url)

Example

from golpo import Golpo, CombinedVideoResult

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

result: CombinedVideoResult = client.combine_videos(
    mp4_urls=[
        "https://..../frame-0.mp4",
        "https://..../frame-1.mp4",
        "https://..../frame-2.mp4",
    ],
    video_url="https://..../original-with-audio.mp4",  # Optional: use for audio
    poll_interval_ms=2000,
)
print(result.url)  # Combined video URL

Parameters

6. get_frame_animations — Get frame animation URLs

Returns a mapping of frame index → animation URL for a video. Use this to inspect frame-level outputs or to pass URLs into combine_videos.

Returns: Dict[str, str] (frame index → animation URL)

Example

from golpo import Golpo

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

animations = client.get_frame_animations(video_id="your-video-id")
# e.g. {"0": "https://.../frame-0.mp4", "1": "https://.../frame-1.mp4", ...}

for frame_id, url in animations.items():
    print(f"Frame {frame_id}: {url}")

# Use with combine_videos
urls = list(animations.values())
combined = client.combine_videos(mp4_urls=urls, video_url=original_video_url)

Parameters

7. update_video — Update video metadata

Updates video metadata such as prompt, context, scenes, video URL, and frame animations. Requires JWT authentication.

Returns: Dict[str, Any]

Example

from golpo import Golpo

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

result = client.update_video(
    video_id="your-video-id",
    prompt="Updated prompt text",
    scenes=8,
    jwt_token="your-jwt-token",
)

Parameters

Result types

Import from golpo:

from golpo import (
    GenerationResult,
    VideoJobResult,
    VideoStatusResult,
    VideoEditResult,
    CombinedVideoResult,
)

Uploads (local files vs URLs)

• URLs (e.g. https://... or s3://...): Sent as-is in the upload_urls form field.
• Local paths (str or pathlib.Path): Uploaded to S3 via /upload-url, then the resulting URLs are sent. Uploads run in parallel with a fixed internal worker pool in both create_video and create_podcast.

You can mix URLs and paths in a single list:

client.create_video(
    prompt="...",
    uploads=[
        "https://example.com/doc.pdf",
        "./local-file.pdf",
        Path("~/Documents/other.pdf"),
    ],
)

Errors

The SDK may raise:

• ValueError — Invalid arguments (e.g. empty prompt, mismatched frame_ids/edit_prompts, missing video_url, timing < 0.25).
• FileNotFoundError — A local path in uploads does not exist.
• TimeoutError — Edit/combine job did not complete within the allowed time.
• requests.HTTPError — API returned an error status (e.g. 4xx/5xx).

Handle these in your code as needed (retries, logging, user message).

Links

• Homepage: https://video.golpoai.com
• Python: Requires 3.8+