Vugola API

The Vugola API lets you build AI video clipping into your own apps, agents, and workflows. You send a long-form video URL, Vugola returns multiple short-form clips with AI-generated titles and virality scores. You can also schedule clips to post on X, Instagram, TikTok, YouTube, Facebook, LinkedIn, Threads, and Bluesky from the same API.

Base URL:

https://www.vugolaai.com/api/v1

Agent-friendly from day one. The same endpoints are available as MCP tools through our official server at vugola-mcp on npm. One command in Claude Desktop, Claude Code, Cursor, or Cline — see MCP server.

Three steps: get a key, check your credits, start a clipping job.

1. Get an API key

Visit vugolaai.com/dashboard/api-key while signed in. Keys are prefixed vug_sk_. API access is available on every paid plan (Starter, Creator, and Agency).

2. Check your credits

Sanity-check that the key is valid:

curl https://www.vugolaai.com/api/v1/status \
  -H "Authorization: Bearer $VUGOLA_API_KEY"

Returns your plan name and remaining credits. One credit = one minute of source video.

3. Clip a video

Kick off a clipping job:

curl https://www.vugolaai.com/api/v1/clip \
  -H "Authorization: Bearer $VUGOLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "aspect_ratio": "9:16",
    "caption_style": "minimalist"
  }'

You get back a job_id immediately. Poll GET /clip/:job_id every 30–60 seconds. Most jobs complete in 10–30 minutes. Vugola also emails you when clips are ready.

Every request needs a Bearer token in the Authorization header.

Authorization: Bearer vug_sk_your_key_here

Keys are tied to a single Vugola account. Never commit them to a public repo — GitHub secret scanning watches the vug_sk_ prefix. To rotate, generate a new key at /dashboard/api-key and delete the old one.

Free accounts without an active paid subscription receive a 403 subscription_required response with an upgrade_url in the body. Upgrade at /pricing.

Per-account limits are enforced by the API layer. Hitting them returns 429 Too Many Requests.

Credits themselves are not a rate limit — they reset with your billing cycle. Clipping cost is calculated at job completion as max(1, ceil(video_minutes)), so a 5:30 video consumes 6 credits.

Errors are returned as JSON with error (a stable code you can branch on) and message (a human-readable string).

All user-supplied URLs (for video_url and media_url) are SSRF-protected server-side: no private IP ranges, no cloud metadata endpoints, no file://.

Turn a long-form video into multiple short-form clips with AI-generated titles, virality scores, and captions. Jobs are asynchronous.

Start a clipping job

Example request:

curl https://www.vugolaai.com/api/v1/clip \
  -H "Authorization: Bearer $VUGOLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "aspect_ratio": "9:16",
    "caption_style": "minimalist",
    "caption_color": "#FFE600"
  }'

Response (202 Accepted):

{
  "job_id": "c2c0205e-d5e9-47e0-8328-127c05de1b4e",
  "status": "processing",
  "message": "Video is being processed. Poll GET /clip/:job_id for status."
}

Check job status

Returns one of three status values: processing, complete, or failed. Poll every 30–60 seconds.

curl https://www.vugolaai.com/api/v1/clip/c2c0205e-... \
  -H "Authorization: Bearer $VUGOLA_API_KEY"

While processing:

{
  "job_id": "c2c0205e-...",
  "status": "processing",
  "progress": 45,
  "clips_ready": 2,
  "clips_total": 5
}

When complete:

{
  "job_id": "c2c0205e-...",
  "status": "complete",
  "credits_used": 8,
  "clips": [
    {
      "clip_id": "uuid",
      "title": "The moment X happened",
      "duration": 42.5,
      "virality_score": 0.92,
      "download_url": "https://<storage>.supabase.co/.../clip-1.mp4?token=..."
    }
  ]
}

duration is seconds (float). virality_score is a 0–1 float (higher is better). Each download_url is a presigned link — open it in a browser without any headers. Valid for roughly one hour.

Get all clip download URLs

Returns every rendered clip for a completed job. Each download_url is a presigned link that works directly in a browser (no Authorization header required) and expires after roughly one hour. Save clips promptly or re-fetch this endpoint to refresh the links.

{
  "job_id": "c2c0205e-...",
  "clips": [
    {
      "clip_index": 1,
      "clip_id": "uuid",
      "title": "The moment X happened",
      "filename": "1-the-moment-x-happened.mp4",
      "virality_score": 0.92,
      "duration": 42.5,
      "download_url": "https://<storage>.supabase.co/.../clip-1.mp4?token=..."
    }
  ],
  "note": "download_url is a presigned link valid for approximately 1 hour. No Authorization header required."
}

Download a specific clip

Streams the clip directly as video/mp4. clip_index is 1-based.

curl https://www.vugolaai.com/api/v1/clip/c2c0205e-.../download/1 \
  -H "Authorization: Bearer $VUGOLA_API_KEY" \
  -o clip-1.mp4

Queue posts to up to 8 social platforms in a single request. Supported platforms: x, instagram, tiktok, youtube, facebook, linkedin, threads, bluesky.

Schedule posts

Send up to 25 posts per request.

Example request:

curl https://www.vugolaai.com/api/v1/schedule \
  -H "Authorization: Bearer $VUGOLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "posts": [
      {
        "platform": "tiktok",
        "caption": "My caption",
        "scheduled_at": "2026-05-01T15:00:00.000Z",
        "media_url": "https://cdn.example.com/clip.mp4"
      }
    ]
  }'

Response (201):

{
  "success": true,
  "posts": [
    {
      "id": "uuid",
      "platform": "tiktok",
      "status": "scheduled",
      "scheduled_at": "2026-05-01T15:00:00.000Z"
    }
  ]
}

List scheduled posts

Optional query parameters: status (scheduled, processing, posted, failed), platform, limit (default 20, max 100), offset (default 0).

{
  "posts": [
    {
      "id": "uuid",
      "platform": "tiktok",
      "caption": "My caption",
      "title": null,
      "status": "scheduled",
      "scheduled_at": "2026-05-01T15:00:00.000Z",
      "posted_at": null,
      "failure_reason": null
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Get one scheduled post

Returns the full record for a single post. Useful for checking whether a post has gone live or failed with a reason.

{
  "id": "uuid",
  "platform": "tiktok",
  "caption": "My caption",
  "title": null,
  "status": "posted",
  "scheduled_at": "2026-05-01T15:00:00.000Z",
  "posted_at": "2026-05-01T15:00:12.428Z",
  "failure_reason": null
}

Cancel a scheduled post

Only posts with status: scheduled can be cancelled. Posts that are already processing or have posted return 409 cannot_cancel.

{
  "success": true,
  "id": "uuid",
  "status": "cancelled"
}

Check balance

Minimal balance check. Safe to call before every job.

{
  "credits_remaining": 847,
  "credits_total": 1200,
  "plan": "agency"
}

Usage with monthly breakdown

{
  "credits_remaining": 847,
  "credits_total": 1200,
  "credits_used_this_month": 353,
  "plan": "agency"
}

Transaction history

Paginated list of credit transactions. Query params: limit (default 20, max 100), offset (default 0).

{
  "transactions": [
    {
      "id": "uuid",
      "type": "debit",
      "amount": 8,
      "date": "2026-04-14T20:14:00Z",
      "video_url": "https://www.youtube.com/watch?v=..."
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Vugola ships an official Model Context Protocol server so AI agents — Claude Desktop, Claude Code, Cursor, Cline — can clip videos, download clips to disk, and manage scheduled posts on your behalf.

One command, Claude Desktop:

npx vugola-mcp@1.2.1 install

The installer prompts for your API key and auto-edits the Claude Desktop config. Fully quit and reopen Claude Desktop to pick up the tools.

Seven tools are available to any agent: clip_video, get_clip_status, get_usage, schedule_post, list_scheduled_posts, cancel_scheduled_post, and download_clip (saves a finished clip to the user's Downloads folder).

The MCP server is listed in the official MCP Registry. Full source, changelog, and per-tool reference at github.com/VCoder25/vugola-mcp.

2026-04-15 — MCP v1.2.1

• Three new MCP tools: list_scheduled_posts, cancel_scheduled_post, and download_clip (saves a finished clip to the user's Downloads folder).
• download_url values returned by the API are now presigned — clickable in a browser with no Authorization header, valid for ~1 hour.
• MCP server listed in the official MCP Registry as io.github.VCoder25/vugola-mcp.

2026-04-14 — v1.0 launch

• Public REST API available at www.vugolaai.com/api/v1.
• Endpoints: POST /clip, GET /clip/:job_id, GET /status, GET /usage, POST /schedule.
• Bearer auth with vug_sk_-prefixed keys, available on every paid plan (Starter, Creator, Agency).
• Official MCP server published as vugola-mcp on npm.