ClipAgent API

Turn YouTube videos into viral short-form clips programmatically. Submit a video URL, get AI-analyzed clip candidates with virality scores, then render them with captions and branding.

Base URL: https://clip-agent.com/v1

All requests use POST with a JSON body containing an action field.

Authentication

Every request requires an API key in the Authorization header:

Authorization: Bearer ca_live_xxxxxxxxxxxxxxxxx

Generate API keys from your Dashboard.

Credits

Each video analysis costs 1 credit ($2). Rendering is included — no extra charge.

Buy credits from the Dashboard. Your balance is shown there along with usage history.

Analyze a video

Submit a YouTube URL for analysis. Costs 1 credit. Returns a job ID for polling.

{
  "action": "analyze",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Response (202)

{
  "job_id": "a1b2c3d4-...",
  "status": "processing"
}

Check job status

Poll until status is "completed" or "failed". Recommended interval: 10 seconds.

{
  "action": "status",
  "job_id": "a1b2c3d4-..."
}

Response when completed

{
  "status": "completed",
  "video_title": "The Future of AI",
  "duration_seconds": 1847,
  "clips": [
    {
      "clip_id": "clip-1",
      "start_ms": 12400,
      "end_ms": 72800,
      "title_hook": "This changes everything",
      "virality_score": 9.2,
      "why_it_works": "Strong contrarian opinion in first 3 seconds...",
      "audience_type": "tech enthusiasts",
      "tags": ["hook", "controversial_take"],
      "duration_seconds": 60
    }
  ]
}

Upload brand logo

Upload a logo image (PNG or JPG, max 2MB). One active logo per account — uploading replaces the previous one.

curl -X POST https://clip-agent.com/v1 \
  -H "Authorization: Bearer ca_live_xxx" \
  -F "file=@logo.png"

Response

{
  "logo_url": "https://...supabase.co/storage/v1/object/public/brand-logos/..."
}

Render clips

Render selected clips with caption style and branding. No extra credit cost.

{
  "action": "render",
  "job_id": "a1b2c3d4-...",
  "clip_ids": ["clip-1", "clip-3"],
  "options": {
    "caption_style": "boldPop",
    "brand": {
      "mode": "logo",
      "logo_url": "https://example.com/my-logo.png",
      "position": { "x": 0.5, "y": 0.08 },
      "opacity": 0.5,
      "scale": 0.15
    }
  }
}

Brand settings are per-render — you can use a different logo, handle, or style for every render request. This is useful if you manage multiple channels or clients.

Response (202)

{
  "render_id": "r1e2n3d4-...",
  "status": "rendering"
}

Render status

{
  "action": "render_status",
  "render_id": "r1e2n3d4-..."
}

Response when completed

{
  "status": "completed",
  "clips": [
    {
      "clip_id": "clip-1",
      "download_url": "https://...supabase.co/storage/v1/...",
      "expires_at": "2026-04-02T12:00:00Z"
    }
  ]
}

Download URLs expire after 24 hours.

Caption styles

Pass one of these values as options.caption_style:

Branding options

The options.brand object controls watermark/branding on rendered clips.

Handle mode

Logo mode

Pass logo_url directly in the render request. You can use any publicly accessible image URL. Alternatively, use upload_logo to host one on our servers — if logo_url is omitted, the saved profile logo is used as fallback.

Error codes

Rate limits

10 requests per minute per API key. Polling status and render_status count toward this limit — use 10-second intervals.