sailtonight/kaloclip-skill

Kaloclip AI video creation (clip)

Kaloclip turns product info and images into a short-video script, and a script into a finished video. The account is the one that owns the API key: its credits, its Kaloclip membership (video queue size, watermark on Free), its image assets and jobs. Most commands are free. The [credits] commands submit paid jobs — see "Spending credits" before using them.

Run

The CLI ships inside this skill (scripts/clip.py, Python 3.11+ stdlib only — nothing to install):

python3 <this-skill-dir>/scripts/clip.py options

All examples below write clip as shorthand for python3 <this-skill-dir>/scripts/clip.py.

Output is TOON (token-oriented) on stdout; add --json to any command for raw JSON. Errors are structured on stdout with actionable help: lines. Exit codes: 0 ok, 1 error, 2 usage.

Setup — check this before the first call

Every command needs a KaloData OpenAPI key (sent as the secret-key header). It is the same key the kalo CLI of the kalodata skill uses, stored in the same place. Before the first call of a session run clip config and look at api_key. If it says missing, stop — don't guess a key and don't retry. Walk the user through these steps and wait:

1. Get a key — sign in at https://www.kalodata.com/open-center/account and click generate key. No account yet? Register at https://www.kalodata.com/open-center/home first.

2. Save it — clip config set --key <API_KEY> (stored in ~/.config/kalodata/config.toml, mode 0600, shared with kalo), or set KALODATA_API_KEY in the environment.

3. Credits — the same credit balance as KaloData; Kaloclip prices and membership rules apply. clip credit shows the balance.

   call	credits
   options, credit, product resolve, image upload/import, video preview, any get / job	free
   script create	2
   video create	what video preview says for the model/duration/resolution (e.g. sd2 · 15s · 720P = 28)
   analysis create	Kaloclip's price for a script analysis

Commands

command	what
clip options	models, durations, resolutions available right now; which model allows which duration
clip credit	remaining credits
clip product resolve <link>	product link → title, categories, selling points, image assets
clip image upload <file...>	1–6 local images (JPEG/PNG/GIF/WebP, ≤5MB) → asset ids
clip image import <url...>	1–6 public https image URLs → asset ids
clip script create	[credits] draft a script; --product-link, or --image --title --category
clip script get <job_id>	draft state and script text; --wait
clip script candidates <job_id>	the two candidates of a rewrite job made on the Kaloclip website
clip video preview	credits a video would cost; --model --duration --resolution --ratio
clip video create	[credits] final script → video; --script-job / --script-file / --script
clip video get <job_id>	video state; videoUrl when completed; --wait
clip analysis create <video_url>	[credits] shot-by-shot breakdown of an existing video; --commerce --country
clip analysis get <job_id>	analysis state and result (kept 30 days); --wait
clip job <job_id>	any job's state and output; --wait
clip config	show/set key (shared with kalo) and endpoint (--base-url staging)

The video flow

1. clip options — pick --model and --duration together from its output. Models and their durations change; never use a model from memory.
2. Product material, either:
   • clip product resolve <link> to check what the link yields, then pass the same --product-link to script create; or
   • the user's own images: clip image upload a.png b.jpg → --image ASSET_ID=IMAGE_URL (repeat, 1–6), plus --title and --category.
3. Ask what the video should feel like (tone, scene, hook) and pass it as --description.
4. clip script create --product-link <link> --model <M> --duration <S> --description "..." → a dry run. Show it, get a yes, rerun with --yes --idempotency-key <key from the hint> --wait (a draft takes about 30–60s; the credits are charged on submit).
5. Show the script. To change it, write the edited text to a file and use --script-file.
6. clip video create --script-job <job_id> [--script-file edited.txt] [--resolution 1080P] → a dry run that includes the credit cost. Get a yes, rerun with --yes --idempotency-key <key>.
7. clip video get <job_id> --wait — a 15s video takes about 15 minutes (--wait polls up to 20). Tell the user it is running; if --wait times out, poll again — never resubmit. Hand videoUrl (mp4) and coverImageUrl to the user.

--script-job reuses the images, title, model and duration the draft was submitted with when the draft was made on this machine; otherwise pass them again (--product-link covers most of it).

Spending credits

[credits] commands never act on the first run: without --yes they print the exact request (dry_run:), its credit cost and an idempotency key, and send nothing. Show it to the user, get an explicit yes, then rerun with --yes --idempotency-key <key>. Never add --yes on your own, and never loop submits.

• Retrying: if a submit ends with "outcome is unknown" (timeout / 5xx / SUBMISSION_IN_PROGRESS), rerun the identical command with the same --idempotency-key within 5 minutes — Kaloclip then returns the original job instead of billing again. A new key means a new paid job. SUBMISSION_OUTCOME_UNKNOWN: stop and tell the user; don't resubmit.
• Jobs are async: keep the job id; poll with --wait (every 5s). Never resubmit a job that is queued or processing.
• TASK_QUEUE_FULL: the membership's video queue is full (Free: one video at a time). Nothing was charged; wait for the running video, then submit again.
• RATE_LIMIT_EXCEEDED: per-user limits (uploads/imports 10/min, product resolve 10/min, preview 20/min, videos 5/min) — wait at least 60 seconds.

Script analysis

clip analysis create <tiktok|kalodata|youtube-shorts url> breaks a video into scenes (video_scripts[]: time, shot scale, visual description, voice-over, each with a translation), plus presenter gender, spoken language, camera moves and why it works. Shoppable TikTok videos: add --commerce --country US. Results stay readable for 30 days (clip analysis get <job_id>); add --json for every field. Use it to learn from a viral video before drafting your own script.

Reading the data right

• A completed draft's script is long-form direction (talent, style, scene, per-scene VISUAL / AUDIO / TALENT ACTION). Show it whole; don't summarize it away before the user approves.
• video preview is an estimate; a submit can still be refused (queue, membership, inputs).
• videoUrl is the finished file; Free-membership videos carry a watermark.
• selling_points from product resolve can be empty while Kaloclip is still analysing the product — rerun in a minute or go on without them.
• Image assets belong to the account; asset ids from one key don't work with another.