Skip to main content
POST
/
api
/
platform
/
v1
/
clip
Create Clip
curl --request POST \
  --url https://api.cuttr.com/api/platform/v1/clip \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "video_url": "<string>",
  "num_clips": "<string>",
  "style": "<string>",
  "length": "<string>",
  "prompt": "<string>",
  "camera_mode": "<string>",
  "hook_length": "<string>",
  "auto_heading": "<string>",
  "heading": {
    "heading.text": "<string>",
    "heading.style": "<string>",
    "heading.color": "<string>",
    "heading.font": "<string>",
    "heading.position": "<string>",
    "heading.bg_color": "<string>",
    "heading.instructions": "<string>"
  },
  "captions": {
    "captions.enabled": true,
    "captions.color": "<string>",
    "captions.font": "<string>"
  },
  "music_url": "<string>",
  "heading_text": "<string>",
  "heading_style": "<string>",
  "heading_color": "<string>",
  "heading_font": "<string>",
  "heading_position": "<string>",
  "heading_bg_color": "<string>",
  "heading_instructions": "<string>",
  "captions_enabled": "<string>",
  "captions_color": "<string>",
  "captions_font": "<string>"
}
'
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "num_clips": 3,
  "cost_cents": 450,
  "status": "processing"
}
Submit a video to generate AI-powered short-form clips. You can provide either a public URL or upload the file directly. Each clip costs $1.50 and is deducted from your wallet upfront. The response returns a job_id that you can poll with Get Job Status.
Both modes respond immediately. Whether you provide a URL or upload a file, the response comes back right away while the video is processed in the background. Use the returned job_id to poll for status.

​
Option 1: JSON with video URL

curl -X POST https://api.cuttr.com/api/platform/v1/clip \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/video.mp4",
    "num_clips": 3,
    "style": "viral",
    "prompt": "focus on the product demo moments",
    "camera_mode": "speaker-zoom",
    "auto_heading": true,
    "heading": { "style": "instagram", "bg_color": "black", "font": "Proxima Nova" },
    "captions": { "enabled": true, "color": "yellow", "font": "Luckiest Guy" }
  }'

​
Option 2: File upload via form data

curl -X POST https://api.cuttr.com/api/platform/v1/clip \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "video=@/path/to/video.mp4" \
  -F "num_clips=3" \
  -F "style=viral" \
  -F "camera_mode=speaker-zoom" \
  -F "auto_heading=true" \
  -F "heading_style=instagram" \
  -F "heading_bg_color=black" \
  -F "heading_font=Proxima Nova" \
  -F "captions_enabled=true" \
  -F "captions_color=yellow" \
  -F "captions_font=Luckiest Guy"

​
Headers

​
X-API-Key
string
required
Your API key. Create one from the dashboard.

​
Body parameters (JSON)

​
video_url
string
A URL to the source video. Supports YouTube, Twitch, Kick, TikTok, Instagram, Vimeo, and 1000+ other platforms — as well as direct links to video files. Required if not uploading a file.
​
num_clips
integer
default:"1"
Number of clips to generate (1-10).
​
style
string
default:"viral"
Clipping style. One of viral, business, general, or gaming.
​
length
integer
Target clip duration in seconds (10-180). Omit to let the AI decide.
​
prompt
string
Custom AI instructions for clip selection (e.g. “focus on product demos” or “find the funniest moments”).
​
camera_mode
string
default:"standard"
Controls how the video is framed for vertical (9:16) output. One of:
  • standard — blurred background with centered video
  • facecam — detects facecam overlay and separates gameplay + facecam
  • speaker-zoom — zooms into the speaker’s face
  • center-crop — crops the center of the video
  • active-speaker — tracks and zooms into the active speaker (multi-person)
​
hook_length
integer
Hook duration in seconds (2-15). The hook is the attention-grabbing opening of each clip. Omit to let the AI decide.
​
auto_heading
boolean
default:"true"
Automatically generate a short viral heading overlay for each clip using AI.
​
heading
object
Heading style customization. Applies to both auto-generated and custom headings.
​
captions
object
Caption settings.
​
music_url
string
URL to a background music file (MP3, WAV, AAC). The music will be mixed into all generated clips at 30% volume.

​
Form data fields (multipart upload)

​
video
file
Video file (mp4, mov, avi, mkv, webm). Required if not providing video_url.
​
num_clips
string
default:"1"
Number of clips to generate (1-10).
​
style
string
default:"viral"
Clipping style. One of viral, business, general, or gaming.
​
length
string
Target clip duration in seconds (10-180). Omit to let the AI decide.
​
prompt
string
Custom AI instructions for clip selection.
​
camera_mode
string
default:"standard"
How the video is framed. One of standard, facecam, speaker-zoom, center-crop, active-speaker.
​
hook_length
string
Hook duration in seconds (2-15). Omit to let the AI decide.
​
music
file
Background music file (MP3, WAV, AAC). Will be mixed into all clips at 30% volume.
​
auto_heading
string
default:"true"
"true" or "false" — auto-generate a viral heading per clip.
​
heading_text
string
Custom heading text. Overrides auto-generated heading.
​
heading_style
string
default:"stroke"
stroke (bold outlined text, no background) or instagram (text on rounded pill background). Determines which color fields apply — see heading_color and heading_bg_color.
​
heading_color
string
default:"white"
Heading text color. One of white, black, red, orange, yellow, green, teal, blue, purple, pink. Only used with stroke style — ignored when style is instagram.
​
heading_font
string
default:"Montserrat"
Heading font. One of Proxima Nova, Montserrat, Luckiest Guy, Everlasting, Komika, Burbank, Bebas Neue, Anton.
​
heading_position
string
default:"top"
Heading vertical position. One of top, middle, bottom.
​
heading_bg_color
string
default:"black"
Background pill color. One of black, white. Text color auto-adjusts for contrast. Only used with instagram style — ignored when style is stroke.
​
heading_instructions
string
Instructions to guide AI heading generation. Max 1500 characters.
​
captions_enabled
string
default:"false"
"true" or "false" — whether to burn captions.
​
captions_color
string
default:"white"
Caption highlight color. One of white, black, red, orange, yellow, green, teal, blue, purple, pink.
​
captions_font
string
default:"Montserrat"
Caption font. One of Proxima Nova, Montserrat, Luckiest Guy, Everlasting, Komika, Burbank, Bebas Neue, Anton.

​
Response

​
job_id
string
Job ID (UUID) to poll for results via Get Job Status.
​
num_clips
integer
Number of clips being generated.
​
cost_cents
integer
Total amount charged in cents ($1.50 per clip).
​
status
string
Always "processing" on success.
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "num_clips": 3,
  "cost_cents": 450,
  "status": "processing"
}