> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cuttr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Clip

> Submit a video for AI clipping

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](/api-reference/endpoint/get-clip-status).

<Note>
  **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.
</Note>

## Option 1: JSON with video URL

```bash theme={null}
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

```bash theme={null}
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

<ParamField header="X-API-Key" type="string" required>
  Your API key. Create one from the [dashboard](https://platform.cuttr.com/dashboard/api-platform).
</ParamField>

### Body parameters (JSON)

<ParamField body="video_url" type="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.
</ParamField>

<ParamField body="num_clips" type="integer" default="1">
  Number of clips to generate (1-10).
</ParamField>

<ParamField body="style" type="string" default="viral">
  Clipping style. One of `viral`, `business`, `general`, or `gaming`.
</ParamField>

<ParamField body="length" type="integer">
  Target clip duration in seconds (10-180). Omit to let the AI decide.
</ParamField>

<ParamField body="prompt" type="string">
  Custom AI instructions for clip selection (e.g. "focus on product demos" or "find the funniest moments").
</ParamField>

<ParamField body="camera_mode" type="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)
</ParamField>

<ParamField body="hook_length" type="integer">
  Hook duration in seconds (2-15). The hook is the attention-grabbing opening of each clip. Omit to let the AI decide.
</ParamField>

<ParamField body="auto_heading" type="boolean" default="true">
  Automatically generate a short viral heading overlay for each clip using AI.
</ParamField>

<ParamField body="heading" type="object">
  Heading style customization. Applies to both auto-generated and custom headings.

  <Expandable title="properties">
    <ParamField body="heading.text" type="string">
      Custom heading text. When provided, overrides `auto_heading`.
    </ParamField>

    <ParamField body="heading.style" type="string" default="stroke">
      Heading visual style. Determines which color options are available:

      * `stroke` — bold outlined text with no background. Use `heading.color` to set the text color. `heading.bg_color` is ignored.
      * `instagram` — text on a rounded pill-shaped background. Use `heading.bg_color` to set the pill color (`black` or `white`). Text color is automatically set to contrast (black bg → white text, white bg → black text). `heading.color` is ignored.
    </ParamField>

    <ParamField body="heading.color" type="string" default="white">
      Text color. One of `white`, `black`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`. **Only used with `stroke` style** — ignored when style is `instagram`.
    </ParamField>

    <ParamField body="heading.font" type="string" default="Montserrat">
      Heading font. One of `Proxima Nova`, `Montserrat`, `Luckiest Guy`, `Everlasting`, `Komika`, `Burbank`, `Bebas Neue`, `Anton`. Tip: `Proxima Nova` works well with the `instagram` style.
    </ParamField>

    <ParamField body="heading.position" type="string" default="top">
      Heading vertical position. One of `top`, `middle`, `bottom`.
    </ParamField>

    <ParamField body="heading.bg_color" type="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`.
    </ParamField>

    <ParamField body="heading.instructions" type="string">
      Optional instructions to guide AI heading generation (e.g. "focus on product benefits", "use question-style headings"). Only applies when `auto_heading` is true and no custom `text` is provided. Max 1500 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="captions" type="object">
  Caption settings.

  <Expandable title="properties">
    <ParamField body="captions.enabled" type="boolean" default="false">
      Whether to burn captions into the clip.
    </ParamField>

    <ParamField body="captions.color" type="string" default="white">
      Caption highlight color. One of `white`, `black`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`.
    </ParamField>

    <ParamField body="captions.font" type="string" default="Montserrat">
      Caption font. One of `Proxima Nova`, `Montserrat`, `Luckiest Guy`, `Everlasting`, `Komika`, `Burbank`, `Bebas Neue`, `Anton`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="music_url" type="string">
  URL to a background music file (MP3, WAV, AAC). The music will be mixed into all generated clips at 30% volume.
</ParamField>

### Form data fields (multipart upload)

<ParamField body="video" type="file">
  Video file (mp4, mov, avi, mkv, webm). Required if not providing `video_url`.
</ParamField>

<ParamField body="num_clips" type="string" default="1">
  Number of clips to generate (1-10).
</ParamField>

<ParamField body="style" type="string" default="viral">
  Clipping style. One of `viral`, `business`, `general`, or `gaming`.
</ParamField>

<ParamField body="length" type="string">
  Target clip duration in seconds (10-180). Omit to let the AI decide.
</ParamField>

<ParamField body="prompt" type="string">
  Custom AI instructions for clip selection.
</ParamField>

<ParamField body="camera_mode" type="string" default="standard">
  How the video is framed. One of `standard`, `facecam`, `speaker-zoom`, `center-crop`, `active-speaker`.
</ParamField>

<ParamField body="hook_length" type="string">
  Hook duration in seconds (2-15). Omit to let the AI decide.
</ParamField>

<ParamField body="music" type="file">
  Background music file (MP3, WAV, AAC). Will be mixed into all clips at 30% volume.
</ParamField>

<ParamField body="auto_heading" type="string" default="true">
  `"true"` or `"false"` — auto-generate a viral heading per clip.
</ParamField>

<ParamField body="heading_text" type="string">
  Custom heading text. Overrides auto-generated heading.
</ParamField>

<ParamField body="heading_style" type="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`.
</ParamField>

<ParamField body="heading_color" type="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`.
</ParamField>

<ParamField body="heading_font" type="string" default="Montserrat">
  Heading font. One of `Proxima Nova`, `Montserrat`, `Luckiest Guy`, `Everlasting`, `Komika`, `Burbank`, `Bebas Neue`, `Anton`.
</ParamField>

<ParamField body="heading_position" type="string" default="top">
  Heading vertical position. One of `top`, `middle`, `bottom`.
</ParamField>

<ParamField body="heading_bg_color" type="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`.
</ParamField>

<ParamField body="heading_instructions" type="string">
  Instructions to guide AI heading generation. Max 1500 characters.
</ParamField>

<ParamField body="captions_enabled" type="string" default="false">
  `"true"` or `"false"` — whether to burn captions.
</ParamField>

<ParamField body="captions_color" type="string" default="white">
  Caption highlight color. One of `white`, `black`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`.
</ParamField>

<ParamField body="captions_font" type="string" default="Montserrat">
  Caption font. One of `Proxima Nova`, `Montserrat`, `Luckiest Guy`, `Everlasting`, `Komika`, `Burbank`, `Bebas Neue`, `Anton`.
</ParamField>

### Response

<ResponseField name="job_id" type="string">
  Job ID (UUID) to poll for results via [Get Job Status](/api-reference/endpoint/get-clip-status).
</ResponseField>

<ResponseField name="num_clips" type="integer">
  Number of clips being generated.
</ResponseField>

<ResponseField name="cost_cents" type="integer">
  Total amount charged in cents (\$1.50 per clip).
</ResponseField>

<ResponseField name="status" type="string">
  Always `"processing"` on success.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "num_clips": 3,
    "cost_cents": 450,
    "status": "processing"
  }
  ```

  ```json 402 theme={null}
  {
    "error": "Insufficient wallet balance",
    "required_cents": 450,
    "balance_cents": 200
  }
  ```
</ResponseExample>