golpo

Golpo Video Skill

This skill turns a user request into a finished video using the Golpo Video API (https://api.golpoai.com/api/v1). It accepts:

• a prompt (Golpo writes the script),
• a prompt + custom script (new_script),
• a prompt + audio narration (audio_clip),
• a prompt + supporting documents (upload_urls: PDF/DOCX/PPTX/TXT),
• or any combination, plus optional images, logos, and styling.

All work goes through the bundled Python helper at ${CLAUDE_PLUGIN_ROOT}/skills/golpo/scripts/golpo.py. Always invoke it via python3 with that absolute path.

1. Bootstrap on every invocation

Run the helper's environment check first:

python3 "$CLAUDE_PLUGIN_ROOT/skills/golpo/scripts/golpo.py" check

It prints machine-parsable lines:

python_ok=true|false
python_version=3.x
requests_ok=true|false
key_configured=true|false
key_source=env|file|none

• If python_ok=false, tell the user to install Python 3.8+.
• If requests_ok=false, tell the user to run pip3 install --user requests (or pip install requests in their venv).
• If key_configured=false, go to step 2.

2. API key (one-time)

If no key is configured, ask the user to paste their Golpo API key. Explain:

Your key will be saved to ~/.golpo/api_key with 0600 permissions. You can rotate it any time with the same command, and GOLPO_API_KEY env var overrides the file if set. Get a key at https://video.golpoai.com.

Once they provide it, save it:

python3 "$CLAUDE_PLUGIN_ROOT/skills/golpo/scripts/golpo.py" auth --key "<KEY>"

Add --force to overwrite an existing key. Re-run check to confirm key_configured=true.

3. Gather requirements

Figure out what video the user wants. Most users will say "make a video about X" — just default everything sensible and tell them what you defaulted to. Only ask follow-ups if the request is ambiguous or the user explicitly wants control.

Sensible defaults:

Field	Default	Notes
timing	"0.5" (~30s)	string; allowed: "0.25", "0.5", "1", "2", "4", "8", "10", "auto"
video_type	"long"	long = 16:9, short = 9:16 vertical
style	"solo-female-3"	voice. See references/voices.md
language	"en"	narration language. See references/languages.md
engine	Sketch Classic (use_lineart_2_style="false")	for Canvas, set use_2_0_style=true and pick an image_style

Important field gotchas (the API rejects wrong types):

• timing is a string, not a number: "0.5", not 0.5.
• use_lineart_2_style is a string: "false", "true", "advanced", "whiteboard", "modern_minimal", "storytelling". The helper coerces for you, but pass it as a string anyway.
• use_2_0_style is a boolean.
• prompt is required even when audio_clip, new_script, or upload_urls is also passed.
• Sketch (use_lineart_2_style) and Canvas (use_2_0_style) are mutually exclusive — pick one engine per video.

For style/voice/language/music details, read the reference files on demand: references/voices.md, references/styles.md, references/languages.md, references/bg_music.md. For every parameter, see references/full-payload.md.

4. Upload step (only if the user provides an audio file or document)

Run upload once per file. Files must be ≤ 15 MB.

python3 "$CLAUDE_PLUGIN_ROOT/skills/golpo/scripts/golpo.py" upload /path/to/file.mp3

The helper prints JSON and a final FILE_URL=<url> line. Use that URL:

• audio narration → pass as --audio_clip <FILE_URL>
• documents (PDF/DOCX/PPTX/TXT) → pass as --upload_urls <FILE_URL> (you can pass --upload_urls multiple times to attach several documents)
• input images for Canvas → --input_images <FILE_URL>
• user images embedded in the video → --user_images <FILE_URL> (paired with --user_images_descriptions "<desc>" per image)

Document URLs are single-use — Golpo deletes the file after extraction. If the user wants to regenerate, re-upload.

5. Generate

Submit the job. Each API field is a --<field> flag. Repeatable list fields (--upload_urls, --input_images, --user_images, --user_images_descriptions, --user_videos, --user_videos_description, --use_as_is, --skip_animation, --user_audio_in_video) take one occurrence per value.

Examples:

Simple prompt, 30 s, default voice and Sketch Classic:

python3 "$CLAUDE_PLUGIN_ROOT/skills/golpo/scripts/golpo.py" generate \
  --prompt "Why is the sky blue?" \
  --timing 0.5 \
  --video_type long

Prompt + custom script in Canvas Editorial:

python3 "$CLAUDE_PLUGIN_ROOT/skills/golpo/scripts/golpo.py" generate \
  --prompt "Why is the sky blue?" \
  --new_script "Sunlight looks white, but it's really every color of the rainbow..." \
  --use_2_0_style true --image_style editorial \
  --timing 0.5 --style solo-male-3 --video_type long --language en

User-provided audio narration:

# 1. upload
python3 .../golpo.py upload my_narration.mp3
# -> FILE_URL=https://...

# 2. generate using that url
python3 .../golpo.py generate \
  --prompt "Why is the sky blue?" \
  --audio_clip "https://..." \
  --timing 0.5 --video_type long --language en

Document-grounded vertical short with background music:

python3 .../golpo.py upload report.pdf  # -> FILE_URL=...
python3 .../golpo.py generate \
  --prompt "Summarize the Q3 earnings report" \
  --upload_urls "<FILE_URL>" \
  --video_type short --timing 1 \
  --style solo-female-4 --bg_music documentary

Hindi voice with English on-screen text (Canvas only):

python3 .../golpo.py generate \
  --prompt "Why is the sky blue?" \
  --use_2_0_style true --image_style marker \
  --style solo-female-3 --language hi --display_language en \
  --timing 0.5 --video_type long

The helper:

1. Submits POST /videos/generate and prints JOB_ID=... and VIDEO_ID=....
2. Polls GET /videos/status/{job_id} with backoff (5 s → 30 s, capped at 90 min by default; use --max_wait_seconds N to extend further). Polling is resilient to transient 5xx responses (up to 5 retries with exponential backoff).
3. Streams progress=N% status=<state> lines while it polls — relay these to the user as short progress updates.
4. Auto-downloads the rendered MP4 to ~/Golpo/videos/ by default. Filename pattern: YYYYMMDD-HHMMSS_<title-slug>_<video-id-short>.mp4 — the slug is derived from the API-canonical video title (same string the user sees in golpo.py list and the Golpo dashboard). Override with --output_dir <path> or set GOLPO_VIDEO_DIR env var. Skip the download with --no_download.
5. On success, prints VIDEO_FILE=/abs/path.mp4 then VIDEO_URL=<url> and exits 0.
6. On failure, prints ERROR: ... to stderr and exits non-zero.

6. Show the result

When VIDEO_FILE=... and VIDEO_URL=... appear, present both to the user — the local file (they can play it immediately by clicking) and the URL (for sharing). One-line summary of the params used, e.g.:

Video ready, saved to ~/Golpo/videos/20260429-015405_why-is-the-sky-blue_a1b2c3d4.mp4. 30 s, 16:9, solo-female-3, English, Sketch Classic. Hosted at Golpo. Re-download later with python3 .../golpo.py get <VIDEO_ID>.

If the user wants the file somewhere else, regenerate with --output_dir <dir> or export GOLPO_VIDEO_DIR=<dir> once. To skip downloading (URL only), pass --no_download. If the user wants to make adjustments, regenerate with the changed flags. Note that uploaded document URLs cannot be reused — re-upload to retry.

7. Error handling

• ERROR: 401 → API key was rejected. Ask for a new key and re-run auth --force.
• ERROR: 422 followed by a JSON detail array → surface the validation messages verbatim. The most common cause is a numeric timing or boolean use_lineart_2_style; the helper coerces these but check first if the user passed something exotic.
• ERROR: 429 → rate-limited. Wait a minute and retry; if it persists, recommend running ≤ 3 jobs in parallel.
• ERROR: 403 → the user's plan doesn't include the action; point them to https://video.golpoai.com.
• Network errors → retry once; if it still fails, surface the error.
• Timeout (ERROR: timed out after Ns) → the job may still be running. Tell the user the JOB_ID and how to resume: python3 .../golpo.py status <JOB_ID>.

8. Other useful commands

• python3 .../golpo.py list --limit 10 — list the user's recent videos.
• python3 .../golpo.py get <video_id> — fetch metadata + URL for one video.
• python3 .../golpo.py status <job_id> — one-shot status check.

9. What to read on demand

Don't load these unless the user asks about advanced options:

• references/voices.md — voice IDs.
• references/styles.md — Sketch and Canvas style values, mutual exclusivity.
• references/languages.md — 44+ language codes.
• references/bg_music.md — background music options.
• references/full-payload.md — every parameter, type, default, and notes.