How to Use the Golpo AI Video API: 6 Working Payload Examples (with Code)

Full API reference (via endpoint): video.golpoai.com/api-docs/endpoints/v1.

The Golpo AI Video API turns a JSON payload into a finished, narrated, animated explainer video — usually in two to ten minutes. The API surface is tiny (one generate endpoint, one status endpoint, one upload endpoint) but each parameter changes the output in a noticeable way: the visual style, the voice, the language, the on-screen text, and where the narration comes from.

This post walks through six real payloads I sent to the API from Python and the videos that came back. Every example uses the same topic — "Why is the sky blue?" at 30 seconds — so you can compare what changes when you flip a single parameter. You will see the exact payload dict, the call that submits it, the polling loop that waits for the render, and the code that saves the finished MP4 to disk.

The 30-second mental model

• Base URL: https://api.golpoai.com
• Auth header: x-api-key: YOUR_API_KEY
• Generate endpoint: POST /api/v1/videos/generate — returns a job_id
• Status endpoint: GET /api/v1/videos/status/{job_id} — poll until status is completed
• Upload endpoint: POST /api/v1/videos/upload-file — for own audio, own video, or document attachments
• Get your API Key: 1. From the header section of the create video page - make sure you have a Scale or higher plan or API add-on with business plan 2. From the dashboard of the API Only Plan. Visit http://video.golpoai.com and buy the right plan.

The generate endpoint always needs a prompt, even when you also send a script, an audio file, or a document. Treat the prompt as the topic; everything else refines how the video gets built.

Common parameters used across every example

• prompt — required string. The topic.
• timing — duration as a string. "0.25" = 15s, "0.5" = 30s, "1" = 1 min, etc. Sending a number fails validation.
• style — voice. solo-female-3, solo-female-4, solo-male-3, solo-male-4.
• language — narration language code (en, hi, es, etc.).
• display_language — language of on-screen text. Defaults to language if omitted.
• video_type — long (16:9) or short (9:16).
• use_lineart_2_style — Sketch variant. "false" = Classic, "true" = Improved Beta, "advanced" = Formal. (String, not boolean.)
• use_2_0_style — boolean. true switches the engine to Golpo Canvas.
• image_style — only when use_2_0_style is true. Values include editorial, neon, whiteboard, modern_minimal, playful, technical, marker, chalkboard_white.

A small Python helper we will reuse in every example

The only dependency is requests (pip install requests). Paste this once at the top of your script; every example below calls generate, wait_for, and download against it. Uploads for audio and PDFs go through upload_file.

import time

import requests

API_KEY = "YOUR_API_KEY"

BASE = "https://api.golpoai.com/api/v1"

HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}

def generate(payload: dict) -> str:

"""Submit a generation job and return the job_id."""

r = requests.post(f"{BASE}/videos/generate", headers=HEADERS, json=payload)

r.raise_for_status()

return r.json()["job_id"]

def wait_for(job_id: str, every: int = 30, timeout: int = 1800) -> str:

"""Poll the status endpoint until the job finishes; return the video URL."""

start = time.time()

while time.time() - start < timeout:

r = requests.get(

f"{BASE}/videos/status/{job_id}",

headers={"x-api-key": API_KEY},

)

r.raise_for_status()

data = r.json()

print(f"{job_id[:8]} status={data.get('status')}")

if data.get("status") == "completed" and data.get("video_url"):

return data["video_url"]

time.sleep(every)

raise TimeoutError(f"Job {job_id} did not finish in {timeout}s")

def download(url: str, out_path: str) -> str:

"""Stream the finished MP4 to local disk."""

with requests.get(url, stream=True) as r:

r.raise_for_status()

with open(out_path, "wb") as f:

for chunk in r.iter_content(chunk_size=1 << 14):

f.write(chunk)

return out_path

def upload_file(path: str) -> str:

"""Upload a local file (audio or document) and return the permanent file_url."""

with open(path, "rb") as f:

r = requests.post(

f"{BASE}/videos/upload-file",

headers={"x-api-key": API_KEY},

files={"file": (path, f)},

)

r.raise_for_status()

data = r.json()

# Second step: PUT the bytes to the pre-signed S3 URL.

with open(path, "rb") as f:

put = requests.put(data["upload_url"], data=f.read())

put.raise_for_status()

return data["file_url"]

That is the entire client. Every example below is just a different payload dict handed to generate, followed by the same three-line submit/poll/download pattern.

Example 1 — Simple prompt with Golpo Sketch Classic

The minimum viable payload. One prompt, one duration, the default Sketch Classic look, and a female voice. This is what you reach for when you have a topic but no script.

payload = {

"prompt": "Why is the sky blue?",

"timing": "0.5",

"use_lineart_2_style": "false",

"style": "solo-female-3",

"video_type": "long",

"language": "en",

}

job_id = generate(payload)

print("submitted:", job_id) # -> 4eb06bfe-72fd-4c99-9a65-5f5cf12a843d

video_url = wait_for(job_id)

download(video_url, "sky_sketch_classic.mp4")

Output:

Example 2 — Your own script with Golpo Canvas Editorial (male voice)

When you already know exactly what the narration should say, send a new_script. Golpo uses that script verbatim and picks visuals to match. Add use_2_0_style: True and image_style: "editorial" to switch from whiteboard sketches to magazine-style canvas illustrations, and change style to a male voice.

payload = {

"prompt": "Why is the sky blue?",

"new_script": (

"Sunlight looks white, but it is really a mix of every color of the rainbow. "

"When that light hits our atmosphere, it bumps into tiny molecules of air. "

"Blue light has a shorter, faster wave, so it gets scattered in every direction "

"far more than red or yellow light. That scattered blue is what reaches your eyes "

"from every part of the sky, which is why the sky looks blue on a clear day. "

"At sunset, the light travels through more air, the blue gets scattered away, "

"and the reds and oranges are what is left for you to see."

),

"use_2_0_style": True,

"image_style": "editorial",

"timing": "0.5",

"style": "solo-male-3",

"video_type": "long",

"language": "en",

}

job_id = generate(payload)

video_url = wait_for(job_id)

download(video_url, "sky_canvas_editorial.mp4")

Output:

Example 3 — Use your own narration audio

If you already have a recorded voiceover (your own voice, an ElevenLabs export, a podcast clip), upload it via upload_file and pass the resulting URL as audio_clip. Golpo skips its own narration step and times the visuals to your audio.

The source audio I uploaded for this example:

Download the source narration (M4A, ~54 KB) — generated locally with macOS say for this demo.

The upload is a two-step flow under the hood: the API returns a pre-signed S3 URL, and you PUT the bytes to it. The upload_file helper handles both steps and returns the permanent file_url.

audio_url = upload_file("narration.m4a")

print("audio hosted at:", audio_url)

payload = {

"prompt": "Why is the sky blue?",

"audio_clip": audio_url,

"timing": "0.5",

"use_lineart_2_style": "false",

"video_type": "long",

"language": "en",

}

job_id = generate(payload)

video_url = wait_for(job_id)

download(video_url, "sky_own_audio.mp4")

Output:

Example 4 — Generate from a PDF document

For documents (PDF, DOCX, slides), the upload flow is identical to audio, but you pass the resulting URL inside the upload_urls array instead. Golpo extracts the text, writes a script around it, and produces the video.

One important detail from the docs: document URLs are single-use. Once you pass a URL into upload_urls, the file is permanently deleted after extraction. If you want to keep a copy for your own records, upload a second time or save your local original.

The PDF I used as the source:

Download the source PDF — "Why Is the Sky Blue?"

pdf_url = upload_file("sky.pdf")

payload = {

"prompt": "Why is the sky blue?",

"upload_urls": [pdf_url],

"timing": "0.5",

"use_lineart_2_style": "false",

"style": "solo-female-4",

"video_type": "long",

"language": "en",

}

job_id = generate(payload)

video_url = wait_for(job_id)

download(video_url, "sky_from_pdf.mp4")

Output:

Example 5 — Hindi narration with English on-screen text

language sets the voice; display_language sets the on-screen text. Setting them differently is useful for global audiences who want spoken localization but prefer English captions, labels, and chart text.

The catch: display_language only works on Golpo Canvas. On Sketch it is silently ignored and the on-screen text defaults to whatever language is. So to get "Hindi voice over English text" you have to switch the renderer to Canvas with use_2_0_style: True. Here I also picked image_style: "marker" — the sharpie-marker look — to show off a different Canvas aesthetic than the editorial one used in Example 2.

payload = {

  "prompt": "Why is the sky blue?",

  "timing": "0.5",

  "use_2_0_style": True,    # required for display_language to take effect

  "image_style": "marker",   # sharpie look

  "style": "solo-female-3",

  "language": "hi",

  "display_language": "en",

  "video_type": "long",

}

job_id = generate(payload)

video_url = wait_for(job_id)

download(video_url, "sky_hindi_voice_english_text.mp4")

Output:

Example 6 — Spanish narration with Spanish on-screen text (male voice)

The fully-localized variant: voice and on-screen text both in Spanish. This is what you would ship to a Spanish-speaking audience.

payload = {

"prompt": "Why is the sky blue?",

"timing": "0.5",

"use_lineart_2_style": "false",

"style": "solo-male-3",

"language": "es",

"display_language": "es",

"video_type": "long",

}

job_id = generate(payload)

video_url = wait_for(job_id)

download(video_url, "sky_spanish.mp4")

Output:

What the polling loop actually sees

POST /generate returns immediately with a job_id. Generation runs in the background. The wait_for helper polls GET /api/v1/videos/status/{job_id} until status becomes completed and a video_url is present. A 30-second video typically finishes in two to five minutes; longer videos take longer.

Status responses look like this while running:

{

"job_id": "4eb06bfe-72fd-4c99-9a65-5f5cf12a843d",

"status": "generating",

"created_at": "2026-04-19T04:46:52.888684+00:00",

"video_url": null

}

And like this when finished:

{

"job_id": "4eb06bfe-72fd-4c99-9a65-5f5cf12a843d",

"status": "completed",

"created_at": "2026-04-19T04:46:52.888684+00:00",

"video_url": "https://golpo-podcast-inputs.s3.us-east-2.amazonaws.com/files/67d86c55-50c9-4557-85ba-4b434429da2f.mp4"

}

Typical console output from wait_for while a job renders:

4eb06bfe status=generating

4eb06bfe status=generating

4eb06bfe status=completed

Running many jobs in parallel (we suggest do a maximum of 3 in parallel)

When you want to fire off all payloads at once and wait for them all together, submit first and poll afterwards. Each generate call returns instantly, so this is fast and simple — no threading required.

payloads = [

{"prompt": "Why is the sky blue?", "timing": "0.5",

"use_lineart_2_style": "false", "style": "solo-female-3",

"video_type": "long", "language": "en"},

# ... the other 5 payload dicts from the examples above ... (we recommend to do a maximum of 3)

]

job_ids = [generate(p) for p in payloads]

print("submitted:", job_ids)

for i, jid in enumerate(job_ids):

url = wait_for(jid)

download(url, f"sky_{i+1}.mp4")

print(f"saved sky_{i+1}.mp4 from {url}")

Gotchas worth knowing before you ship

• timing is a string. 0.5 as a number returns 422 Unprocessable Entity. Use "0.5".
• prompt is always required. Even when you send new_script, audio_clip, or upload_urls. Treat it as the topic label, but it will be ignored if the new_script or audio_clip is present.
• upload-file is two steps. The first call returns a pre-signed URL; you have to PUT the bytes to it before the file_url resolves. The upload_file helper does both.
• Document URLs are single-use. A file_url passed into upload_urls is deleted after extraction. Audio and video URLs (used in audio_clip / user_videos) persist.
• use_lineart_2_style is a string. "false", "true", or "advanced" — not a boolean.
• image_style only works with Canvas. Set use_2_0_style: True first, otherwise image_style is ignored.
• language vs display_language. language is the voice; display_language is the on-screen text. Set them independently for "Hindi voice with English captions" or vice versa.
• API access is plan-gated. If /generate returns "Your current plan does not include API access", enable the API add-on in the dashboard before retrying.
• Plan polling around 2–10 minutes. A 30-second video usually returns in 2–5 minutes; longer videos and Canvas runs take longer. A 30-second sleep between polls is plenty.
• Video URLs are durable, not permanent. Download each finished MP4 with the download helper if you need it for your own storage or distribution — the returned S3 URLs are fine for embedding, but treat your local MP4 as the source of truth.

Wrap up

The whole API surface is small enough to fit in your head: one generate endpoint, one status endpoint, one upload endpoint. Everything else is payload: choose between Sketch and Canvas, decide whether you want Golpo to write the script or use yours, pick a voice, pick a language, and for audio or documents run the two-step upload. The six Python examples above cover the patterns you will actually use day-to-day. Copy any of them, paste your API key, and you have a working video pipeline.