Documentation Index
Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt
Use this file to discover all available pages before exploring further.
Video Clipping is the repurposing primitive for turning long-form video into distribution-ready short-form content. Submit a YouTube URL and receive multiple clips ranked by AI virality scoring — or enhance any video with captions, zooms, and B-roll. All jobs go through the unified jobs system with credits billed on completion.
CLI First
# Extract clips from a YouTube video
naive video clip "https://youtube.com/watch?v=abc123" --title "Podcast Highlights" --wait
# Add captions and effects to an existing video
naive video clip-edit "https://example.com/video.mp4" --title "Enhanced Video" --magic-zooms --magic-brolls
| Tool | Type | Description | Cost |
|---|
naive_create_clips | Core | Extract short-form clips from a YouTube video | 4 credits |
naive_clips_status | Core | Check clipping or editing job status | Free |
naive_edit_clip_video | Core | Add captions, effects, zooms, and B-roll | 3 credits |
Creating Clips
The naive_create_clips tool submits a YouTube video for AI clip extraction. The system analyzes the video, identifies the most engaging segments, and returns multiple clips with virality scores.
curl -X POST https://api.usenaive.ai/v1/video/clips \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"youtube_url": "https://youtube.com/watch?v=abc123",
"title": "Podcast Highlights",
"language": "en",
"min_clip_length": 15,
"max_clip_length": 60
}'
{
"job_id": "job-uuid",
"status": "queued",
"type": "video_clipping",
"estimated_seconds": 600,
"estimated_credits": 4,
"hint": "Poll GET /v1/video/clips/job-uuid or GET /v1/jobs/job-uuid. Clipping typically takes 5-10 minutes. Credits charged on completion only."
}
Parameters
| Param | Type | Required | Default | Description |
|---|
youtube_url | string | Yes | — | YouTube video URL to extract clips from |
title | string | Yes | — | Project title |
language | string | No | "en" | Video language code |
template | string | No | "Hormozi 2" | Caption template name |
min_clip_length | number | No | 15 | Minimum clip length in seconds |
max_clip_length | number | No | 60 | Maximum clip length in seconds |
Polling for Completion
Clip extraction takes 5-10 minutes. Poll the job:
curl https://api.usenaive.ai/v1/video/clips/job-uuid \
-H "Authorization: Bearer nv_sk_your_key"
{
"status": "completed",
"result": {
"clips": [
{
"id": "clip-uuid-1",
"title": "The Secret to Scaling",
"duration": 42,
"virality_score": {
"total": 87,
"shareability": 82,
"hook_strength": 91,
"story_quality": 85,
"emotional_impact": 90
},
"download_url": "https://...",
"direct_url": "https://...",
"preview_url": "https://..."
}
],
"clip_count": 5,
"top_virality_score": 87
},
"credits_used": 4
}
Poll every 30-60 seconds. Jobs stay in queued status until processing completes.
Virality Scoring
Every extracted clip is scored on five dimensions (0-100):
| Score | Meaning | Decision |
|---|
total | Overall viral potential | Primary ranking metric |
shareability | Likelihood of sharing | Social distribution suitability |
hook_strength | Opening seconds impact | First-impression quality |
story_quality | Narrative coherence | Standalone watchability |
emotional_impact | Emotional resonance | Engagement potential |
| Total Score | Quality | Action |
|---|
| 80+ | Strong | Prioritize for distribution |
| 60-79 | Decent | Usable content |
| Below 60 | Weak | Skip unless no alternatives |
Video Editing
The naive_edit_clip_video tool adds captions, AI-powered zooms, and B-roll to any video.
curl -X POST https://api.usenaive.ai/v1/video/clips/edit \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://example.com/video.mp4",
"title": "Enhanced Podcast Clip",
"language": "en",
"magic_zooms": true,
"magic_brolls": true,
"magic_brolls_percentage": 30
}'
Edit Parameters
| Param | Type | Required | Default | Description |
|---|
video_url | string | Yes | — | Public URL to an MP4 or MOV file (max 2GB, 2hr) |
title | string | Yes | — | Project title |
language | string | No | "en" | Video language code |
template | string | No | — | Caption template name |
magic_zooms | boolean | No | false | Enable AI-powered zooms on key moments |
magic_brolls | boolean | No | false | Enable AI-generated B-roll footage |
magic_brolls_percentage | number | No | — | Percentage of video with B-roll (0-100) |
{
"status": "completed",
"result": {
"video_url": "https://...",
"download_url": "https://..."
},
"credits_used": 3
}
Cost
| Operation | Credits | Billing |
|---|
| Clip extraction | 4 credits | Charged on completion |
| Video editing | 3 credits | Charged on completion |
Error Handling
| Error | Cause | Recovery |
|---|
insufficient_credits | Not enough credits | Top up with POST /v1/billing/topup |
provider_error | Upstream processing error | Check the video URL and try again |
invalid_input | Missing required fields | Provide youtube_url + title for clips, video_url + title for edits |
feature_not_configured | Clipping not enabled | Contact support |
Typical Workflow
Agent receives task: "Turn this podcast into YouTube Shorts"
|
+-- POST /v1/video/clips --> Submit YouTube URL
| { youtube_url: "...", title: "Podcast" }
| --> job_id: job-uuid
|
+-- GET /v1/video/clips/job-uuid --> Poll every 30-60s
| --> status: queued (5-10 min)
|
+-- GET /v1/video/clips/job-uuid --> Poll again
| --> status: completed, 5 clips extracted
| --> clips ranked by virality score
|
+-- Filter: keep clips with score 75+ --> 3 clips pass
|
+-- GET /v1/media?source_type=video_clipping --> Auto-ingested to Media Assets
|
+-- POST /v1/social/posts (x3) --> Distribute top clips
{ platforms: ["YOUTUBE"], media_urls: ["..."], content: "..." }
Completed clipping and editing jobs are automatically added to your Media Asset Manager with source_type: "video_clipping". Use naive media list --source video_clipping or GET /v1/media?source_type=video_clipping to find them. Each clip includes its virality score as a tag (e.g. virality:91). 
