clipapi/API Reference

Quick Start

clipapi is a multi-modal video intelligence API. Send a video URL, get back 60+ dimensions of analysis — transcript, scenes, entities, music, hook scoring, retention predictions, and more.

1. Get an API key

Sign up at /signup to get your free API key. The free plan includes 50 analyses per month.

2. Analyze a video

curl
"color:#A78BFA">curl "color:#F59E0B">-X POST https://api.clipapi.dev/v1/analyses \
  "color:#F59E0B">-H "Authorization: Bearer YOUR_API_KEY" \
  "color:#F59E0B">-H "Content">-Type: application/json" \
  "color:#F59E0B">-d '{"video_url": "https://www.tiktok.com/@creator/video/7234567890"}'

3. Poll for results

The response includes an analysis_id. Poll the status endpoint or use SSE streaming for real-time progress.

curl
"color:#A78BFA">curl https://api.clipapi.dev/v1/analyses/job_a1b2c3d4e5f6 \
  "color:#F59E0B">-H "Authorization: Bearer YOUR_API_KEY"

Authentication

All API requests require an API key passed via the Authorization header or X-API-Key header.

Header format
# Option 1: Bearer token
Authorization: Bearer ve_live_abc123...

# Option 2: X"color:#F59E0B">-API-Key header
X"color:#F59E0B">-API-Key: ve_live_abc123...

API keys use the format ve_live_<32-char-random>. Keys are hashed with SHA-256 before storage — we never store your key in plaintext.

Managing keys

Create, list, and revoke keys from the dashboard or via the API.

Note: API keys (ve_live_*) are for API access. Dashboard login uses JWT tokens issued by the auth endpoints.

Analyze a Video

POST/v1/analyses

Submit a video URL for asynchronous analysis. Supports TikTok, Instagram Reels, YouTube Shorts, and direct video file URLs.

Request body

video_url
stringrequired
Public video URL (TikTok, Instagram, YouTube, or direct .mp4/.mov/.webm)
storage_path
string
S3/R2 storage path (alternative to video_url). Format: s3://bucket/key
pipeline_preset
string
Pipeline preset: "full" (default), "meta_only", "audio_only"
external_id
string
Your own reference ID. Returned in the response for correlation.
webhook_url
string
URL to POST results to on completion. Receives the full analysis JSON.

Response

201 Created
{
  "analysis_id": "job_a1b2c3d4e5f6",
  "status": "queued",
  "stream_url": "/api/v1/analyses/job_a1b2c3d4e5f6/stream"
}

Upload a File

POST/v1/analyses/upload

Upload a video file directly instead of providing a URL. Use multipart/form-data encoding.

curl
"color:#A78BFA">curl "color:#F59E0B">-X POST https://api.clipapi.dev/v1/analyses/upload \
  "color:#F59E0B">-H "Authorization: Bearer YOUR_API_KEY" \
  "color:#F59E0B">-F "file=@video.mp4" \
  "color:#F59E0B">-F "pipeline_preset=full"

Parameters

file
filerequired
Video file. Supported: MP4, MOV, WebM, MKV. Max 500MB.
pipeline_preset
string
Pipeline preset (same as analyze endpoint).
external_id
string
Your reference ID.
webhook_url
string
Callback URL on completion.

Get Results

GET/v1/analyses/{analysis_id}

Poll this endpoint to check analysis status. Returns the full result when complete.

In progress

200 OK
{
  "analysis_id": "job_a1b2c3d4e5f6",
  "status": "processing",
  "current_step": "visual_analysis"
}

Completed

Returns the full AnalysisResult object with all extracted data. See Response Schema.

Real-time Streaming

GET/v1/analyses/{analysis_id}/streamSSE

Subscribe to Server-Sent Events for real-time pipeline progress. Each pipeline step emits events as it starts and completes.

Event stream
event: step_start
data: {"event": "step_start", "step": "ingest", "job_id": "job_a1b2c3d4e5f6"}

event: step_done
data: {"event": "step_done", "step": "ingest", "duration_ms": 2340}

event: step_start
data: {"event": "step_start", "step": "audio_analysis"}

event: step_done
data: {"event": "step_done", "step": "audio_analysis", "duration_ms": 4120}

event: pipeline_done
data: {"event": "pipeline_done", "analysis_id": "job_a1b2c3d4e5f6"}

JavaScript example

JavaScript
const es = new EventSource(
  "https://api.clipapi.dev/v1/analyses/job_a1b2c3d4e5f6/stream"
);

es.addEventListener("step_done", (e) => {
  const data = JSON.parse(e.data);
  console.log(`✓ ${data.step} completed in ${data.duration_ms}ms`);
});

es.addEventListener("pipeline_done", (e) => {
  console.log("Analysis complete!");
  es.close();
  // Fetch full results
  fetch("/v1/analyses/job_a1b2c3d4e5f6", { headers });
});

Response Schema

The full analysis result is a deeply structured JSON object organized into three layers: media understanding (extraction), creator intelligence (analysis), and growth intelligence (prediction).

Top-level fields

analysis_id
stringrequired
Unique analysis identifier
status
stringrequired
completed | failed
source
objectrequired
URL, platform, source type
media
objectrequired
Duration, aspect ratio
scores
objectrequired
Aggregate scores (0-100)
media_understanding
objectrequired
Layer 1 — extracted signals
creator_intelligence
objectrequired
Layer 2 — strategy analysis
growth_intelligence
objectrequired
Layer 3 — viral predictions
processing
objectrequired
Timing metadata

Layer 1: Media Understanding

Raw content extraction from the video — structured signals across vision, audio, and text.

media_understanding
{
  "content_overview": {
    "title": "How I Grew 100K in 30 Days",
    "summary": "Creator shares a step-by-step growth strategy...",
    "category": "Educational",
    "format": "talking_head_with_broll"
  },
  "transcript": {
    "full_text": "So today I want to show you...",
    "segments": [
      {"start": 0.0, "end": 3.2, "speaker": "A", "text": "...", "confidence": 0.97}
    ],
    "language": "en",
    "word_count": 342
  },
  "visual_analysis": {
    "keyframes": [
      {"frame_index": 0, "t": 0.0, "image_url": "https://..."}
    ],
    "cinematography": "handheld, close-up dominant",
    "motifs": ["face-to-camera", "text-overlay"]
  },
  "audio_analysis": {
    "speech": {"language": "en", "speech_rate_wpm_est": 162},
    "music": {"track_title": "Aesthetic — Tollan Kim", "present": true, "bpm_estimate": 124}
  },
  "entities": {
    "people": ["@creator_handle"],
    "brands": ["Nike"],
    "topics": ["social media growth", "content strategy"],
    "hashtags": ["#growthhack", "#tiktoktips"]
  }
}

Layer 2: Creator Intelligence

Strategic analysis of the creator's execution — hooks, retention, storytelling.

creator_intelligence
{
  "hook_analysis": {
    "score": 82,
    "hook_type": "curiosity_gap",
    "primary_hook": "Opens with a 'what if' question...",
    "suggestions": ["Add pattern interrupt in first 0.5s"]
  },
  "retention_analysis": {
    "retention_score": 74,
    "drop_risk_moments": [
      {"timestamp": 6.1, "severity": "minor", "reason": "Scene transition"}
    ],
    "pacing": "fast"
  },
  "story_structure": {
    "logline": "Creator reveals an algorithm hack...",
    "beats": ["hook", "problem", "solution", "proof", "cta"]
  }
}

Layer 3: Growth Intelligence

Viral potential, platform fit, trend alignment, and audience predictions.

growth_intelligence
{
  "virality_model": {
    "score": 67,
    "predicted_view_range": {"low": 5000, "expected": 15000, "high": 80000},
    "factors": ["strong hook", "trending topic"],
    "completion_pressure": 0.72
  },
  "platform_fit": {
    "platform": "tiktok",
    "algorithm_alignment": 0.81,
    "share_probability": 0.34,
    "loopability": 0.45
  },
  "trend_alignment": {
    "uses_trending_audio": true,
    "trend_category": "creator_economy",
    "cycle_stage": "growth"
  },
  "predicted_retention_curve": [
    {"t": 0, "retention": 1.0},
    {"t": 5, "retention": 0.82},
    {"t": 15, "retention": 0.61},
    {"t": 30, "retention": 0.48}
  ]
}

Scores & Signals

The scores object contains aggregate metrics on a 0-100 scale.

hook_strength
How compelling is the opening hook
retention_design
How well the video retains viewers
visual_clarity
Quality and effectiveness of visuals
audio_clarity
Audio production quality
cta_effectiveness
Strength of call-to-action
educational_value
Information density and clarity
overall_creator_clarity
Overall execution quality
confidence_overall
Model confidence in the analysis

Errors

The API uses standard HTTP status codes. Error responses include a JSON body with a detail field.

Error response
{
  "detail": "Invalid or expired API key"
}
400Bad RequestInvalid parameters or missing required fields
401UnauthorizedMissing or invalid API key / JWT token
402Payment RequiredMonthly quota exceeded
403ForbiddenAccount disabled or insufficient permissions
404Not FoundResource not found
409ConflictEmail already registered (signup)
429Too Many RequestsRate limit exceeded. Check Retry-After header
500Internal ErrorServer error. Contact support if persistent
504TimeoutAnalysis timed out (demo: 90s limit)

Rate Limits

Rate limits are enforced per API key with a sliding window. Current limits by plan:

PlanAnalyses/moMax durationRPM
Free50120s5
Pro500300s60
EnterpriseUnlimitedUnlimited200

Rate limit headers

Every response includes rate limit information:

Response headers
X"color:#F59E0B">-RateLimit-Limit: 5
X"color:#F59E0B">-RateLimit-Remaining: 3
X"color:#F59E0B">-RateLimit-Reset: 1710180000

When rate limited, the API returns 429 Too Many Requests with a Retry-After header (seconds).