Skip to main content

Videos through AI agents

The public API isn't only for code — PiratePress ships a ready-made bundle for AI agents (Claude Code, Kimi Code, Cursor, Claude Desktop, and 75+ other agents):

  • MCP server @piratepress/mcp — the tools an agent calls the API with (order, status, balance);
  • skill piratepress-video — the playbook that teaches the agent the whole flow: check the balance before ordering, never double-charge, wait for the video, and bring back the mp4 with the posting pack.

Once installed, just tell your agent "make a video about …" — it takes it from there.

One-line install​

  1. Get a key from the bot: @PiratePressBot → /apikey (the pp_… key is shown once).
  2. In your terminal:
curl -fsSL https://piratepress.fun/install.sh | PIRATEPRESS_API_KEY=pp_... bash

The installer puts the MCP server into ~/.piratepress/mcp/, installs the skill via skills CLI with auto-detection of your agents, and registers the server with Claude Code when available. Nothing outside $HOME is touched.

Manual install​

If the one-liner doesn't fit — the server is an npm package, @piratepress/mcp, and the skill lives in the piratepress/agents repo. Config snippets for Claude Code / Kimi Code / Claude Desktop are in the repo README.

Agents that don't need MCP (e.g. a web agent with a shell, like Kimi on the website) can work from the skill alone — it documents the full REST flow with curl.

MCP tools​

ToolWhat it does
quick_videoOne free-form prompt — a server-side LLM maps it to order parameters. The default for one-shot requests.
generate_videoExplicit params — the full POST /videos surface: content (theme/theme_url/reference_url, lang, duration, style, genre), advertising (placement, hook, end_card, cta + cta_target*), visuals (bg_ai, bg_preset, bg_url, bg_fit, overlays + overlay_count/overlay_level, visual_style), captions (caption_mode/caption_position/caption_scale), music & voice (music — incl. song, music_mood, voice_asset_id), media-library files (theme_asset_id, bg_asset_id, music_asset_id, banner_asset_id, banner_source_asset_id, cover_source_asset_id, reference_asset_id), plus director_mode, count (batch 1–50), watermark. Returns {id, cost, eta_seconds}.
get_video_statusPoll a job; on done returns result_url and the posting pack.
wait_videoBlocks until the final state (done/error/refunded/awaiting_review), polling every 20 s with progress notifications.
review_videoAnswer a script review in director mode: approve / edit (with text) / regen (with a wish).
list_assetsThe user's media library (voice clones, theme packs etc.) — ids for the *_asset_id order fields.
upload_assetUpload local files to the media library (POST /assets, multipart): theme pack (txt/md/pdf, photos, voice notes, zip), own background, own track, banner, reference video, voice sample (paid, like in the bot). Limits: ≤20 files, ≤20 MB per file, per-kind extension whitelist, 2 GB library quota. The returned id plugs into generate_video as theme_asset_id / bg_asset_id / music_asset_id / banner_asset_id / banner_source_asset_id / cover_source_asset_id / reference_asset_id / voice_asset_id.
get_balanceWallet: {dublones, subscription, fair_use_left}. 1🪙 = 1₽.

Outside the public API (bot only): balance top-ups and subscription purchases, plus the scheduled firing of channel autopilot itself (the bot's worker; the channel schedule is managed via the API — PATCH /channels). When the user asks for one of these, the agent points them to the bot instead of improvising.

What the MCP table above doesn't cover yet, but is already available to the agent via REST (the skill documents the full curl flow): cutting long videos into clips with offer banners (POST /public/v1/clips — mass-posting clipper offers, AI banner, split view — see Clips) and channel management (LLM concepts, an instant video from a channel, scheduling — see Channels). Dedicated MCP tools for these domains are coming in the next @piratepress/mcp release.

How a trained agent behaves​

  • Balance first, order second — and it tells you the price before charging.
  • Idempotency-Key on every order — retries never double-charge.
  • No silent paid retries — on failure it asks you first.
  • Batches go in waves: 10 active jobs max, 30 POST/min (on 429 it waits Retry-After).
  • Links as input: an article URL in the prompt lands in theme_url (content source); a YouTube/TikTok link lands in reference_url (format clone).
  • AI background via bg_ai: "illustrations" — AI art per scene; "lite" — the same scenes animated image-to-video (pricier, a heavy job under subscription fair-use). Animating a user-uploaded photo is not in the public API — lite animates scenes the service generates itself.

Statuses and money​

Doubloons are charged when the job is created. The job then moves queued → running → done, or ends in a terminal error / refunded state (director mode may pause at awaiting_review).

  • error — failed with no doubloon charge (trial, or an externally paid order);
  • refunded — a paid order failed: the doubloons were refunded to the balance automatically, and the error field says so. Double-check with get_balance.

result_url is a public signed link (7-day TTL, no key needed to download): instead of proxying the file through the agent, you can hand the link straight to the user.

Where next​

  • REST quickstart — three calls to your first video;
  • Error codes — what to do on 402/409/429;
  • Webhooks — video.done / video.error / video.refunded / video.awaiting_review / clip.done / clip.error instead of polling;
  • FAQ — director mode, fair use, and limits.