PiratePressPiratePress

Video Generation API: How to Build Videos with Code

A video generation API is what developers need when clips are required not one at a time but in a stream: content farms, autoposting, integration into your own product. PiratePress exposes the bot's entire pipeline through a public REST API. Here it is on working examples.

What you need to prepare

  1. An API key. Issued by the bot: @piratepress_bot → the /apikey command. The pp_… key is shown once — save it immediately.
  2. An HTTP client. curl is enough; the base URL is https://api.piratepress.fun/public/v1.
  3. A dublon balance. A basic video is 100 dublons (about $1); the exact price returns in the creation response.
  4. The OpenAPI reference at hand: https://api.piratepress.fun/public/v1/docs.

How to generate videos with code

Step 1. Create an order. Two paths. A one-line master prompt — a server-side LLM maps it into parameters:

curl -X POST https://api.piratepress.fun/public/v1/videos:quick \
  -H "X-API-Key: pp_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt": "a 30-second video about a cat astronaut, English narration"}'

Or explicit parameters via POST /videos — predictable config and price:

curl -X POST https://api.piratepress.fun/public/v1/videos \
  -H "X-API-Key: pp_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"theme": "a story about a cat astronaut", "lang": "en", "duration": "30", "caption_mode": "karaoke", "bg_ai": "illustrations"}'

The Idempotency-Key header (uuid) is required: a retry with the same key returns the same order instead of a duplicate. The response is {id, cost, eta_seconds}.

Step 2. Poll the status. GET /videos/{id} returns PublicVideoOut: status (queued → running → done / error / refunded), cost, and on done — result_url (a signed mp4 link, 7-day TTL), result_urls for batches, and metadata — the posting pack (title, description, hashtags). Poll no more than once per 20–30 seconds, or subscribe to webhooks.

Step 3. Download the result immediately. The link lives for a week — grab the mp4 right after done.

Step 4. Scale. Batch generation via the count field (1–50 videos per order). Your own files (theme packs, backgrounds, tracks, voice samples) upload through POST /assets (multipart); the returned id goes into the *_asset_id fields.

Common mistakes

Requests without idempotency. A retry without an Idempotency-Key is a duplicate order and a double charge. The key must be unique per logical operation and stored for retries.

Aggressive polling. Ten requests a second won't speed up rendering but will eat your limits. 20–30 seconds between polls; for the impatient — webhooks (video.done).

Ignoring the refunded status. On generation failure dublons are returned automatically, and the order goes to refunded, not error. Handle both statuses.

FAQ

How does videos:quick differ from POST /videos? Quick is a free-form prompt with LLM mapping (can drift off-topic, price known only after creation, the mapper is throttled). Explicit parameters are deterministic. Use POST /videos for pipelines.

How do I know the price before ordering? The exact price is computed from parameters and returned in cost at creation. The base is 100 dublons; extras (AI background, AI music, etc.) are priced per the tariff.

Are there limits? Media library: 20 files, up to 20 MB each, 2 GB total. One active API key per user.

Is the API production-ready? Yes: idempotency, webhooks, batch orders and auto-refunds on failures are built exactly for programmatic pipelines.

How do I handle 422 errors? The response carries a human-readable cause: parameter conflicts, an unknown asset id, exceeded limits. Log the error body — it tells you exactly what to fix in the order.

Can I cancel an order after creating it? No: the order enters the generation queue immediately. That's why idempotency keys and parameter checks before sending are your main protection against accidental charges.

How do I structure a reliable pipeline? The classic scheme: a topic queue in your DB → a worker creating orders with stored Idempotency-Keys → polling or webhooks → downloading the mp4 and posting pack → publishing. Every step is idempotent and survives restarts.

Start with the key: open @piratepress_bot, run /apikey — and build your first video with code five minutes later.