Create campaigns from code

Every request needs an API key. Create one in the dashboard under Settings → API key management (owner or admin role). Keys look like sk_live_ followed by 32 hex characters. The full key is shown once at creation — we store only a SHA-256 hash, so copy it then.

Send the key on every request, either way:

Authorization: Bearer sk_live_...
# or
X-API-Key: sk_live_...

Keys are scoped. The only scope today is campaigns:create, attached to every key automatically. Responses echo the scope in the X-Clipus-Api-Scopes header. How many keys you can hold depends on your plan — see Plans & quotas.

Creates a campaign: Clipus crawls the URL, captures screens, and starts video generation. The call returns as soon as collection starts — generation continues in the background, so poll status or register a webhook_url.

curl -X POST https://www.clipus.io/api/v1/campaigns \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourproduct.com",
    "languages": ["en", "ja"],
    "webhook_url": "https://yourapp.com/hooks/clipus"
  }'

Response:

{
  "success": true,
  "campaign_id": "8f6a1c2e-...",
  "job_id": "01J...",
  "status": "collecting"
}

Successful and plan-gated responses include X-RateLimit-Plan and X-RateLimit-Limit headers so you can see your tier from the response itself.

Returns campaign status and finished videos.

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

{
  "success": true,
  "campaign_id": "8f6a1c2e-...",
  "status": "review",
  "url": "https://yourproduct.com",
  "title": "yourproduct.com Campaign",
  "languages": ["en", "ja"],
  "created_at": "2026-06-11T09:30:00Z",
  "videos": [
    {
      "id": "c91b...",
      "platform": "youtube_shorts",
      "status": "ready",
      "file_url": "https://.../videos/8f6a1c2e/vertical_en_....mp4",
      "duration_seconds": 38,
      "published_at": null
    }
  ]
}

status starts at collecting, moves through processing states (processing, scripting, voiceover, rendering), and lands on review when videos are ready. published and failed are terminal. A campaign typically takes a few minutes; polling every 10–15 seconds stays well inside the rate limits below.

There is no per-call price. API usage draws from the same monthly video quota as the dashboard, and API access starts on the Growth plan. The table below is rendered from the same constants the billing code enforces; the pricing page is the canonical source for what each plan costs.

Free and Starter plans do not include API access. When a campaign would exceed your monthly video quota, the API returns 429 with the current count — it does not bill overage.

Limits apply at two layers, and the stricter one wins. All use a 60-second sliding window.

A limited request returns 429 with { "error": "Too many requests" } and these headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1781234567890
Retry-After: 42

Honor Retry-After (seconds). If the rate-limit backend is unavailable, the API answers 503 rather than letting traffic through unmetered.

Errors are JSON: { "success": false, "error": "..." } with a human-readable message. Status codes:

Pass webhook_url when creating a campaign and we POST to it once the campaign reaches a terminal state:

{
  "event": "campaign.completed",   // or "campaign.failed"
  "campaign_id": "8f6a1c2e-...",
  "status": "review",
  "videos": [ /* same shape as GET status */ ],
  "timestamp": "2026-06-11T09:34:12Z"
}

Each delivery carries identifying headers:

X-Clipus-Event-Id: 7d0f...        # unique per event — use for deduplication
X-Clipus-Timestamp: 1781234567    # unix seconds
X-Clipus-Signature: a3b1...       # HMAC-SHA256 over "{timestamp}.{event_id}.{body}"
X-Clipus-Signature-Alg: HMAC-SHA256

Respond with any 2xx within a few seconds. Failed deliveries are retried up to 3 attempts total, so make your handler idempotent — X-Clipus-Event-Id is stable across retries. Webhooks are delivery notifications; treat GET /api/v1/campaigns/:id as the source of truth.