Clipora API

Programmatically turn long videos into face-aware, captioned 9:16 reels. REST endpoints for upload, job status, and clip download.

Quickstart

Three calls: generate a key → upload → fetch clips.

1. STEP 1 · Generate an API key

   Sign in, then visit /keys to create a key. Format: ck_live_…. The plaintext is shown ONCE — store it as $CLIPORA_API_KEY.

   # Export the key into your shell so the examples below pick it up
   export CLIPORA_API_KEY="ck_live_AbCdEf...your-key-here"

2. STEP 2 · Upload a video

   curl -X POST https://your-host/api/upload \
     -H "X-API-Key: $CLIPORA_API_KEY" \
     -F "video=@/path/to/video.mp4" \
     -F 'options={"numClips":3,"captionPreset":"mozi","aspectRatio":"9:16"}'
   
   # → {"jobId":"abc123…","wsUrl":"/ws?jobId=abc123…",...}

3. STEP 3 · Wait for completion, then fetch clips

   # Poll job status, then fetch clips when status is completed
   curl https://your-host/api/jobs/abc123 \
     -H "X-API-Key: $CLIPORA_API_KEY"
   
   curl https://your-host/api/clips/abc123 \
     -H "X-API-Key: $CLIPORA_API_KEY"

Authentication

Protected API routes require authentication. Use an API key for server-to-server calls (Business plan), or the session cookie from the login pages for browser apps. Public routes: /api/billing/plans and auth signup/login.

API key (recommended for server-to-server)

Create a key at /keys. Pass it as either of:

X-API-Key: ck_live_AbCdEf...your-key-here
# or, equivalently:
Authorization: Bearer ck_live_AbCdEf...your-key-here

• Keys are 256-bit random tokens, SHA-256 hashed at rest — the plaintext is shown once at creation
• Up to 10 active keys per account; revoke unused ones from /keys
• Revoked or wrong keys return 401 immediately (no fallback)
• API keys cannot manage other keys, billing checkout, or billing portal — session only
• Upload/jobs/clips/downloads are scoped to your account; clip files cannot be read without auth
• /ws?jobId=… requires the same auth (cookie or X-API-Key) and job ownership
• Keep keys secret — never commit them to git or expose them in frontend JavaScript

Cookie session (browser-side apps)

The login pages set a httpOnly cookie named reels_session, automatically sent by any browser on same-origin requests. Use this for in-browser apps and dashboards; use API keys for everything else.

Errors

All errors return JSON with an error field:

{ "error": "video file required" }