Clipus API reference

The Clipus API lets you create demo video campaigns from a SaaS URL programmatically. Most people should use the Clipus Claude Code plugin, which wraps this API. Use the REST API directly when you are building your own integration.

Base URL

https://www.clipus.io

Authentication

Create an API key in the Dashboard under Settings → API Keys. Keys look like sk_live_…, are shown once, and carry the campaigns:create scope. The API requires a Growth plan or above.

Send the key on every request, either as a bearer token or in the X-API-Key header:

curl https://www.clipus.io/api/v1/campaigns \
  -H "Authorization: Bearer sk_live_your_key_here"

# or
curl https://www.clipus.io/api/v1/campaigns \
  -H "X-API-Key: sk_live_your_key_here"

Keep the key server-side. Never commit it or expose it in client code.

Rate limits

Limits are plan-based. Every response includes these headers:

• X-RateLimit-Plan — your current plan.
• X-RateLimit-Limit — requests allowed per minute on that plan.
• X-Clipus-Api-Scopes — the scopes your key carries.

Over the limit returns 429. Your monthly video quota is separate and also returns 429 when reached.

Create a campaign

POST /api/v1/campaigns

Reads your live product and generates a multilingual demo video. The request is synchronous while Clipus captures your product, so it can stay open for a few minutes before returning.

Request body:

{
  "url": "https://your-saas.com",
  "languages": ["en", "ja", "ko"],
  "title": "My launch demo",
  "webhook_url": "https://your-app.com/hooks/clipus"
}

• url (required) — the public SaaS product URL to read.
• languages (optional) — output languages; defaults to ["en", "ja", "ko"]. The count is capped by your plan.
• title (optional) — a label for the campaign.
• webhook_url (optional) — a URL Clipus can call about this campaign.

Success returns the campaign id and an initial status:

{
  "success": true,
  "campaign_id": "b1c2d3e4-…",
  "job_id": "01J…",
  "status": "collecting"
}

Use campaign_id to poll status.

Get campaign status

GET /api/v1/campaigns/{id}

curl https://www.clipus.io/api/v1/campaigns/b1c2d3e4-… \
  -H "Authorization: Bearer sk_live_your_key_here"

Response:

{
  "success": true,
  "campaign_id": "b1c2d3e4-…",
  "status": "rendering",
  "url": "https://your-saas.com",
  "title": "My launch demo",
  "languages": ["en", "ja", "ko"],
  "created_at": "2026-06-29T00:00:00Z",
  "videos": [
    {
      "id": "v1",
      "platform": "youtube",
      "status": "ready",
      "file_url": "https://…/video.mp4",
      "duration_seconds": 30,
      "published_at": null
    }
  ]
}

Each entry in videos carries a file_url download link once that output is ready.

Error responses

Errors return a JSON body with success: false and an error message. Common statuses:

• 400 — invalid request (missing or malformed url, or more languages than your plan allows).
• 401 — missing or invalid API key.
• 403 — your plan does not include API access (Growth or above required).
• 404 — campaign id not found.
• 422 — Clipus could not capture screenshots from the URL (the page may block bots or require login).
• 429 — rate limit or monthly video quota reached.