Tools

clip_video

Agentic clipping: give a public video link (YouTube, TikTok, Instagram, X, Twitch, Kick, Vimeo, a direct file URL) and Heavenly finds the best short clips, reframes them to 9:16, 1:1 or 16:9 and burns in captions. Returns a job id at once; poll get_clip_job about every 15 s until completed (usually 1-5 minutes), then list_clips. Spends Clips minutes for the video's length (check get_credits); the audio is transcribed. For a local file, use the CLI (heavenly clip ./video.mp4) or the REST upload API.

Access token · edit · Changes account data

Parameters

aspect_ratio string optional

Frame of the clips: 9:16 (default), 1:1 or 16:9.

View schema

{
  "description": "Frame of the clips: 9:16 (default), 1:1 or 16:9.",
  "type": "string",
  "enum": [
    "9:16",
    "1:1",
    "16:9"
  ]
}

caption_style string optional

Burned-in caption look; none turns captions off. Default: Heavenly's highlight look.

View schema

{
  "description": "Burned-in caption look; none turns captions off. Default: Heavenly's highlight look.",
  "type": "string",
  "enum": [
    "viral-bold",
    "clean-creator",
    "high-energy",
    "editorial",
    "none",
    "highlighted",
    "scale",
    "minimalist",
    "box",
    "staticbox",
    "glow",
    "hormozi",
    "vlog",
    "classic",
    "pop-box",
    "beast",
    "karaoke",
    "bold-pop",
    "one-word",
    "comic",
    "neon",
    "read-along",
    "reveal",
    "highlighter",
    "clean",
    "podcast",
    "label",
    "impact",
    "cinema",
    "elegant",
    "marker",
    "bubble",
    "typewriter"
  ]
}

caption_color string optional

Accent colour of the spoken word, #RRGGBB.

View schema

{
  "description": "Accent colour of the spoken word, #RRGGBB.",
  "type": "string",
  "pattern": "^#[0-9a-f]{6}$"
}

clip_count integer optional

How many clips to return. Default: as many as the video holds.

View schema

{
  "description": "How many clips to return. Default: as many as the video holds.",
  "type": "integer",
  "minimum": 1,
  "maximum": 60
}

min_seconds number optional

Shortest clip. Default 30.

View schema

{
  "description": "Shortest clip. Default 30.",
  "type": "number",
  "minimum": 5,
  "maximum": 180
}

max_seconds number optional

Longest clip. Default 60.

View schema

{
  "description": "Longest clip. Default 60.",
  "type": "number",
  "minimum": 10,
  "maximum": 240
}

mode string optional

What to look for: auto (default), funny, story, insight, quotes and more.

View schema

{
  "description": "What to look for: auto (default), funny, story, insight, quotes and more.",
  "type": "string",
  "enum": [
    "auto",
    "high-retention",
    "story",
    "insight",
    "funny",
    "controversial",
    "emotional",
    "quotes",
    "product",
    "custom"
  ]
}

platform string optional

Where the clips will be posted. Default Shorts.

View schema

{
  "description": "Where the clips will be posted. Default Shorts.",
  "type": "string",
  "enum": [
    "TikTok",
    "Shorts",
    "Reels",
    "LinkedIn",
    "X"
  ]
}

instructions string optional

Plain words about what to find, e.g. "every moment about pricing".

View schema

{
  "description": "Plain words about what to find, e.g. \"every moment about pricing\".",
  "type": "string",
  "maxLength": 2000
}

video_url string required

Public https link to the video (YouTube, TikTok, Instagram, X, Twitch, Kick, Vimeo, a file URL…).

View schema

{
  "description": "Public https link to the video (YouTube, TikTok, Instagram, X, Twitch, Kick, Vimeo, a file URL…).",
  "type": "string",
  "maxLength": 2048,
  "format": "uri"
}

start_seconds number optional

Only clip from here (seconds).

View schema

{
  "description": "Only clip from here (seconds).",
  "type": "number",
  "minimum": 0
}

end_seconds number optional

Only clip up to here (seconds).

View schema

{
  "description": "Only clip up to here (seconds).",
  "type": "number",
  "exclusiveMinimum": 0
}

title string optional

Name for the project.

View schema

{
  "description": "Name for the project.",
  "type": "string",
  "minLength": 1,
  "maxLength": 150
}

idempotency_key string optional

Reuse to retry safely: the same key returns the same job and holds minutes once. Default: same link and settings today = same job.

View schema

{
  "description": "Reuse to retry safely: the same key returns the same job and holds minutes once. Default: same link and settings today = same job.",
  "type": "string",
  "minLength": 1,
  "maxLength": 255
}

Request example

{
  "name": "clip_video",
  "arguments": {
    "video_url": "https://www.youtube.com/watch?v=VIDEO_ID"
  }
}

Replace example values with ids and arguments read from your own Heavenly account. This example does not execute a tool.

Returns

The tool result from Heavenly’s workspace, encoded as MCP text content. The connector returns isError when an argument, permission, plan or account check fails.

Account access and permissions are checked by Heavenly. See errors for failure handling.