---
name: aiclipper
description: Turn the user's own long video (a local file or their YouTube video) into short captioned social clips with aiclipper.video. Use when the user asks to clip, cut highlights from, or repurpose a video for TikTok, YouTube Shorts, Instagram Reels, LinkedIn, or X.
---

# aiclipper.video

Creates short, captioned clips from long videos through the `aiclipper` MCP server
(https://aiclipper.video/agents). The AI finds the strongest moments, reframes them for each
feed, burns in captions, and writes social copy. Processing takes a few minutes and uses the
user's AI credits.

## Before you start

- The `aiclipper` MCP server must be connected (endpoint `https://aiclipper.video/mcp`, header
  `Authorization: Bearer <agent token>`). If its tools are missing, tell the user to create a
  token in Settings → Agent access and follow https://aiclipper.video/agents.
- Only process videos the user owns or has permission to use. `create_clips` requires
  `rights_confirmed: true`: ask the user to confirm ownership or permission first, and never set it
  on their behalf without asking.
- Call `get_account` first if you are unsure the user has credits. New projects need credits.
  If they run out, `list_credit_packs` shows the one-time packs and `buy_credits` returns a
  checkout link the user opens and pays in their browser (you cannot pay). Credits arrive after
  payment.
- Before creating a project, call `estimate_credits` with the video's length in minutes (and the
  formats, `target_languages`, or `cover_mode` you plan to use). `required_now` is what the project
  needs to start (transcription plus clip selection) and `enough` says whether the balance covers it.
  Tell the user the `total` before you start. If `enough` is false, `create_clips` would fail at once,
  so buy credits first.

## Clip a local video file (preferred)

Upload original files. YouTube URL ingestion, channel automation, and the browser extension are disabled by default; use those paths only when tools/list advertises their inputs or tools.

1. Work out the file facts:
   - size in bytes: `wc -c < FILE`
   - MIME type from the extension: `.mp4` → `video/mp4`, `.mov` → `video/quicktime`,
     `.webm` → `video/webm`, `.mkv` → `video/x-matroska`
   - Base64 MD5: `openssl md5 -binary FILE | base64`
   - Limits: 2 GB, 15 seconds to 2 hours, must contain audio.
   - Source resolution is retained; YouTube downloads and extension SABR imports select up to 2160p (4K). Exports keep existing format dimensions (up to 1080p), with H.264 CRF 18. A 4K source improves crop detail; it does not enable 4K exports.
2. Call `create_upload` with `filename`, `byte_size`, `content_type`, `md5_base64`.
3. PUT the file to the returned `url` with exactly the returned `headers` (Content-Type,
   Content-MD5, Content-Disposition) and the file bytes as the body. The `example` field is a
   ready-made curl command. The upload must return HTTP 200. The URL expires in one hour.
4. **The upload is not a project yet.** Call `create_clips` with `upload_id` (do not also pass
   `source_url`) and `rights_confirmed: true` to start processing. An upload that is not turned into a project with create_clips is deleted automatically about a day after it was created.

For separate streams already uploaded by the browser extension, pass the completed video stream's
ID as `upload_id` and the completed audio stream's ID as `audio_upload_id`. Both uploads must belong
to the signed-in user, be unused, and total no more than 2 GB. `audio_upload_id` requires `upload_id`;
do not pair audio with `source_url`. Ordinary local video files need no separate audio upload.

Server YouTube URL/channel imports are disabled in the current deployment. Use local uploads or completed extension stream uploads; `extension.enabled` is independent of the server `youtube.ingestion_enabled` gate.

## Clip a YouTube video the user owns

Only when `create_clips` advertises `source_url`, pass a single owned video URL and
`rights_confirmed: true`. Default deployments accept uploads only. Never download someone else's
video without permission. If URL ingestion fails, report the error and request the original file;
do not repeatedly retry a blocked link or promise the extension can bypass restrictions.

## Choose formats

Call `list_formats` for details. Pass `formats` as an array of ids:

| id | Ratio | Best for |
|---|---|---|
| `punch` (default) | 9:16 full-bleed crop | TikTok, Shorts, Reels |
| `studio` | 9:16 centered fit | podcasts and interviews with several people |
| `square` | 1:1 | LinkedIn, X, Instagram feed |
| `portrait` | 4:5 | Instagram and Facebook feeds |
| `cinema` | 16:9 | YouTube, X, Facebook Watch |

Other useful `create_clips` options: `clip_count` (an integer 1-5, or `"auto"`; default 3), `clip_length`
(15-120 seconds, the maximum length, default 30), `goal` (`virality`, `education`, `storytelling`), `caption_style`
(`pop` karaoke highlight, `clean` sentence case, or `impact` one big word at a time — ask the user which look they
want; colors and size follow via `caption_color`, `caption_highlight_color`, and `caption_size`),
`cover_mode` (`frame` is free and
makes the cover from a frame of the video with your headline; `none` skips it), `target_languages` for dubbed versions.

Branding: pass `watermark_text` (up to 60 characters), hex `watermark_color`, and
`watermark_position` (use the advertised enum). For logos, call `create_brand_logo_upload` with
filename, byte_size, content_type, and md5_base64 (PNG/JPEG/WebP, at most 5 MB), PUT bytes using
returned headers, then pass its `upload_id` as `brand_logo_upload_id` to `create_clips`. The logo
must belong to this account, be fully uploaded, and not already attached elsewhere.

`clip_count: "auto"` lets the AI decide how many clips the video yields: it picks every strong, self-contained
moment and sizes each clip to its natural start and end, up to `clip_length`. Auto stops at 12 clips per project
(fewer when many formats are rendered) and can return fewer when the video has few strong moments. Use it when
the user asks for "all the good moments" or does not name a number. Clips are scored by AI editorial estimates,
not predicted views, so say that rather than promising a clip will go viral. `estimate_credits` prices Auto at its
upper bound and says "up to".

## Wait for the result

1. `create_clips` returns a `project_id`. Poll `get_project` every 20-30 seconds until `status`
   is `completed` or `failed`. Statuses go queued → downloading → transcribing → analyzing →
   rendering → completed.
2. If `failed`, report `error_message` exactly. For a failed project, `retry_project` re-queues it
   and reuses finished steps.
3. When completed, give the user each clip's `title`, `score`, `format`, `social_description`,
   and `video_url`. Download links expire after one hour: call `get_project` or `get_clip` again
   for fresh ones.

## Publish, share, and refine

- `publish_clip` uploads a ready clip to the user's connected channel: YouTube Shorts (square or
  vertical, under 3 minutes), TikTok (vertical, under 3 minutes), or Instagram Reels (9:16, 5-90
  seconds) — pass the matching `provider`. The user must connect the channel in Settings →
  Publishing first; if it is not connected, tell them to. TikTok and Instagram fetch the video
  through the clip's public share link, which is turned on automatically. Read `publications` in
  `get_clip` or `get_project` to follow pending, published, failed, or uncertain status. Only
  published confirms success; uncertain requires checking the provider before retrying, to avoid
  duplicate posts. Read-only fields include provider, status, external_id, url, published_at,
  error, and operation_stage. Resumable credentials and operation IDs are never exposed.
- `share_clip` turns a public link (`/s/<token>`) on or off for a clip. Give the URL to the user for
  feedback or approvals; anyone with it can watch and download the clip.
- `update_clip` renames a clip or rewrites its description. `generate_social_copy` has AI rewrite
  the description from the clip's transcript (1 credit) — offer it when the user wants punchier copy.
- `recut_clip` re-renders a clip with new start and end seconds (5 to 120, inside the video).
  Rendering is free; dubbed copies cannot be recut. Existing media stays live until the new render succeeds.
  The web clip page offers the same operation with a visual timeline, keyboard handles, and
  selection preview when the source is retained; agents pass exact timestamps via `recut_clip`.
- `reselect_moments` re-runs moment selection on a finished project with new settings (goal, count,
  minimum score). Old clips remain until replacements render successfully; only selection (1 credit) is charged again.
- `rate_clip` records whether a clip worked (up or down, optional note). Ask the user after they
  review clips; ratings tune future selection.
- `delete_clip` permanently removes one clip (confirm with the user first).

## Channels

`list_channels` remains available for existing connections. `create_channel`, `update_channel`,
and `sync_channel` are advertised only when the operator explicitly enables YouTube ingestion.
When offered, channel creation requires ownership/permission confirmation and
`rights_confirmed: true`; preferences apply to future videos. Do not offer disabled automation.

## More tools

- `add_format` renders finished moments in another format without re-transcribing. It,
  `reselect_moments`, `recut_clip`, and `retry_project` need original video, removed after 14 days.
- `reattach_source` restores a purged source without new project or AI charges: call `create_upload`,
  upload the exact original combined file, then pass `project_id`, `upload_id`, and explicit
  `rights_confirmed: true`. It does not start processing; retry the desired edit afterwards.
  Exact saved fingerprint, duration, video and audio must match. Alternate encodings, separate
  streams, and legacy projects without saved fingerprints are rejected; create a new project instead.
- `correct_transcript` takes `project_id` and `segments` (1–10000 objects containing only numeric
  `start`, numeric `end`, and nonblank `text` up to 10000 characters). Segments must be ordered,
  non-overlapping, and inside source duration, with end greater than start. Requires finished
  processing and retained original source. It rerenders original-audio clips free; dubbed clips
  are not retranscribed or redubbed. Poll `get_project` after correction.
- `correct_transcript`, `recut_clip`, and `reselect_moments` reject projects with pending or
  uncertain publications. Wait for publishing or resolve its uncertain outcome first. Edits keep
  existing ready clips until replacements finish; failed replacements do not discard originals.
  `add_format` also waits until any staged project edit finishes.
- `get_clip` returns score breakdown, rationale, captions, cover links, and publication states.
- `get_transcript` returns timestamped transcript segments for posts or correction.
- `generate_hook_cover` makes a new preview cover from a frame of the clip's video with your hook text
  (`mode: "frame"`, free). To change the headline, pass different `custom_hook` text.
- `list_projects` finds earlier projects with optional `status`, `limit` (integer 1–100, default 20),
  and signed opaque `cursor`. Pass returned `next_cursor` unchanged with the same filter to get
  the next stable newest-first page; null means no more. Invalid cursors return errors.
- `delete_project` is permanent: confirm with the user first.
- `export_account_data` returns the user's own data as JSON (projects, clips, credit purchases,
  AI usage). It is read-only. Account deletion is not available to agents; point the user to
  Settings in the web app.

## Rules

- Stop and report the exact error if any step fails. Do not guess or silently change approach.
- Never claim clips exist until `get_project` shows `completed` and returns clips.
- Do not put the agent token in chat, files, or commits.