opus-pro/opusclip

OpusClip

Turn long-form videos into short clips via the OpusClip API.

BETA — features and pricing are subject to change. API pricing may diverge from web pricing.

Prerequisites

• OPUSCLIP_API_KEY must be set. If the user already has an Enterprise or Pro plan, they can copy their key from https://clip.opus.pro/dashboard. Otherwise, direct them to the pricing page — API access requires Enterprise or Pro.
• The CLI at scripts/opusclip requires Node.js (>=18) — it is a bundled JS file

CLI Quick Reference

Run the bundled CLI at scripts/opusclip. All commands output JSON.

opusclip submit --url URL [options]           Submit video for clipping (alias: create-project)
opusclip list --project ID [--summary]        List clips (alias: get-clips)
opusclip list-projects [--page N]             List the org's clip projects (most recent first)
opusclip describe --project ID --clip CID     Get clip details (transcript, layout info)
opusclip transcript --project ID              Get the source-video transcript (paragraphs + word timing in ms)
opusclip storyboard --project ID --clip CID   Generate 2x2 frame preview (requires ffmpeg)
opusclip trim --project ID --clip CID --start S --end E    Local ffmpeg trim (no API call, no captions)
opusclip edit-clip <sub> [flags]              Server-side clip edits (charged, re-renders the clip) (beta — pricing may change)
  get             Fetch EditingScript JSON for round-trip edits (beta — pricing may change)
  apply           Submit an edited EditingScript directly (beta — pricing may change)
  censor          Profanity censor (dictionary-based; --beep adds sound effect) (beta — pricing may change)
opusclip preview --project ID [--output PATH] Generate HTML preview and open in browser
opusclip share --project ID                   Share project (alias: share-project)
opusclip templates                            List brand templates
opusclip upload --file PATH [options]         Upload local video + create project
opusclip thumbnail --url URL [options]        Generate YouTube thumbnails (experimental; credit-charged per call)
opusclip usage                                Show the org's API cap usage (monthly + concurrent, or uncapped)
opusclip collections <sub> [options]          Manage collections
opusclip post <sub> [options]                 Social posting (publish, schedule, generate copy)
  schedule        Schedule a post for future publishing (beta — pricing may change)

submit

Alias: create-project

Copyright hint

Immediately before calling opusclip submit or opusclip upload, narrate the following sentence to the user as a plain notice (not an AskUserQuestion, not a yes/no gate):

Using video you don't own may violate copyright laws. By continuing, you confirm this is your own original content.

This mirrors the inline disclaimer the OpusClip web app shows on its submit panel. Show it verbatim on every submit/upload; do not block on a confirmation.

opusclip submit --url "https://youtube.com/watch?v=..." --durations "30,60,90" [more options]

| Flag | Description | |------|-------------| | --url | (required) Video URL | | --durations | (required in practice) Target clip lengths in seconds, e.g. "30,60,90". API rejects payloads without curationPref.clipDurations. | | --model | ClipBasic (talking-head) or ClipAnything (diverse) | | --prompt | Custom clipping prompt (ClipAnything only) | | --keywords | Comma-separated topic keywords (ClipBasic only) | | --aspect | portrait (default), landscape, square | | --range-start / --range-end | Clip only a portion (seconds) | | --template | Brand template ID | | --genre | Video genre hint | | --lang | Source language code | | --title | Video title metadata | | --webhook | Webhook URL for completion notification | | --skip-curate | Process original video without AI curation | | --remove-filler | Remove filler words |

upload

Same flags as submit plus --file PATH. Handles the full 4-step GCS upload flow automatically.

list

Alias: get-clips

opusclip list --project PROJECT_ID
opusclip list --project PROJECT_ID --summary

| Flag | Description | |------|-------------| | --project | (required) Project ID to fetch clips for | | --summary | Deprecated no-op (kept for back-compat) — scored/human-readable fields are always included now |

To list the clips in a collection, use collections clips --id COLLECTION_ID.

Clips already include human-readable fields (title, description, hashtags, scores) by default. Display clips with their title and description rather than just clip IDs.

The output contains project_id and clip_id as separate fields. Use clip_id (e.g. 0RiWBs5xuF) for --clip flags, not the composite ID.

list-projects

List the calling org's clip projects, most recent first. Use this to find a project_id when the user hasn't given one.

opusclip list-projects
opusclip list-projects --page 1 --page-size 50

| Flag | Description | |------|-------------| | --page | Page number, 0-based (default 0) | | --page-size | Items per page, 1–100 (default 20) |

Each row has project_id, title, source_type, source_video_id, stage, created_at, updated_at, is_deleted.

transcript

Get a project's source-video transcript: paragraphs with word-level timing (in milliseconds).

opusclip transcript --project PROJECT_ID

| Flag | Description | |------|-------------| | --project | Project ID to fetch the transcript for |

Returns { project_id, paragraphs: [{ paragraph_id, start_ms, end_ms, text, words: [{ word, start_ms, end_ms }] }] }. If the project has no transcript yet (still processing), paragraphs is omitted.

preview

Generate an HTML preview page with video players for all clips and open it in the browser.

opusclip preview --project PROJECT_ID
opusclip preview --project PROJECT_ID --output /path/to/output.html

| Flag | Description | |------|-------------| | --project | Project ID | | --output | Custom output path (default: /tmp/opusclip-preview-{id}.html) |

The preview page shows clips sorted by score with inline video players, titles, descriptions, hashtags, and detailed AI scores (hook, coherence, connection, trend). Use this whenever the user wants to watch or preview their clips.

share

Alias: share-project

opusclip share --project PROJECT_ID

| Flag | Description | |------|-------------| | --project | (required) Project ID |

collections

opusclip collections list
opusclip collections clips --id COL_ID
opusclip collections create --name "NAME"
opusclip collections export --id ID
opusclip collections add-clip --id COL_ID --content-id PROJECT_ID.CLIP_ID

Destructive/complex collection operations (deleting a collection, removing a clip) are intentionally web-only — the CLI exposes only the basic, safe operations. Collections can be exported (download links) but cannot be shared publicly. To share clips publicly, use share --project on the project instead.

edit-clip

BETA — features and pricing are subject to change. API pricing may diverge from web pricing.

Workflow guidance

Before running more than 3 edit-clip operations on a single clip in one session, ask the user to confirm — these may incur charges that don't match the web UX.

Never run edit-clip or post schedule in a loop without user confirmation each iteration.

Server-side edits to an existing clip. All sub-verbs except get re-render the clip (charged, beta caps apply). The CLI does the EditingScript walking client-side; the API is a generic passthrough that mirrors the web editor's Save action. See references/editing-script.md for the mutation paths and recipes.

opusclip edit-clip get             --project PID --clip CID [--output FILE]
opusclip edit-clip apply           --project PID --clip CID --script FILE
opusclip edit-clip censor          --project PID --clip CID [--beep]

caption edits / trims

The caption-fix, caption-replace, and server-side trim sub-verbs were removed (they hand-rolled EditingScripts in the CLI and drifted from the engine). For those edits use the get -> edit the EditingScript -> apply round-trip; see references/editing-script.md for worked recipes. censor is the one remaining convenience verb.

apply / censor return {jobId}. Poll status via opusclip describe --project PID --clip CID — render_pending is true while the re-render runs (absent or false when done), and export_url then points at the new mp4.

For a caption typo or a trim, fetch the script with edit-clip get, edit the relevant textElement.text or timing fields, then edit-clip apply --script FILE. See references/editing-script.md. (The top-level opusclip trim remains as a free, instant, no-caption ffmpeg cut on the preview mp4.)

describe

Get structured information about a clip. Use this to understand clip content without watching the video.

opusclip describe --project PROJECT_ID --clip CLIP_ID
opusclip describe --transcript --project PROJECT_ID --clip CLIP_ID
opusclip describe --layout --project PROJECT_ID --clip CLIP_ID

| Flag | Description | |------|-------------| | --project | (required) Project ID | | --clip | (required) Clip ID | | --transcript | Show only transcript text | | --layout | Show only layout/framing info |

Without --transcript or --layout, the default output includes content fields (title, description, transcript, hashtags, keywords, score, duration_sec, aspect), media URLs (preview_url, export_url), and render_pending (true while a re-render is in flight; absent or false when done) — what powers re-render polling. Use --transcript when you only need the spoken text. Use --layout to check current framing before suggesting layout changes.

Polling a re-render (after any edit-clip sub-verb):

while :; do
  opusclip describe --project P --clip C \
    | jq -e '.render_pending != true' >/dev/null && break
  sleep 10
done

storyboard

Generate a 2x2 frame grid image from a clip's preview video. Requires ffmpeg.

opusclip storyboard --project PROJECT_ID --clip CLIP_ID
opusclip storyboard --project PROJECT_ID --clip CLIP_ID --output /path/to/output.jpg

| Flag | Description | |------|-------------| | --project | (required) Project ID | | --clip | (required) Clip ID | | --output | Custom output path (default: /tmp/opusclip-storyboard-{clipId}.jpg) |

Opens the image automatically on macOS/Linux. Use this for quick visual review of a clip's content.

trim

Trim a clip's preview video locally. Requires ffmpeg.

opusclip trim --project PROJECT_ID --clip CLIP_ID --start 3 --end 50
opusclip trim --project PROJECT_ID --clip CLIP_ID --start 3 --end 50 --output trimmed.mp4

| Flag | Description | |------|-------------| | --project | (required) Project ID | | --clip | (required) Clip ID | | --start | (required) Start time in seconds | | --end | (required) End time in seconds | | --output | Custom output path (default: /tmp/opusclip-trimmed-{clipId}.mp4) |

post

BETA — features and pricing are subject to change. API pricing may diverge from web pricing. Applies to post publish and post schedule.

Workflow guidance

Before scheduling more than 5 posts in one session, ask the user to confirm — scheduled posts may begin to incur per-post charges.

Never run edit-clip or post schedule in a loop without user confirmation each iteration.

Manage social posting — publish clips to YouTube, TikTok, Facebook, Instagram, LinkedIn, and X.

opusclip post accounts
opusclip post generate-copy --project PID --clip CID --account AID [--prompt "tone"]
opusclip post copy-status --job JOB_ID
opusclip post publish --project PID --clip CID --account AID --title "Title" [--description "..."] [--privacy public]
opusclip post schedule --project PID --clip CID --account AID --title "Title" --at 2026-03-25T14:00:00Z
opusclip post cancel --schedule SCHEDULE_ID

| Subcommand | Description | |------------|-------------| | accounts | List connected social accounts (default) | | generate-copy | Generate AI-optimized post copy for a clip | | copy-status | Poll for generated copy result | | publish | Publish a clip immediately | | schedule | Schedule a clip for future publishing (beta — pricing may change) | | cancel | Cancel a scheduled post |

Supported platforms: YouTube, TikTok Business, Facebook Page, Instagram Business, LinkedIn, X (Twitter). "Twitter" refers to X — the platform identifier is TWITTER. Each X post costs 1 credit.

When the user doesn't specify a post title, use the clip's title from the list --summary output.

thumbnail

EXPERIMENTAL — features and pricing are subject to change. Daily caps apply. The endpoint may be temporarily disabled while in experimental status.

Generate AI-designed YouTube thumbnails from a source video. Results are downloaded automatically on completion.

Cost: Every call is credit-charged for Pro/Enterprise callers — the API surface has no free quota (free quota is web-only). Each call costs a fixed number of credits (currently 7). Free/Starter callers get a QuotaExceedErr.

opusclip thumbnail --url "https://youtube.com/watch?v=..."
opusclip thumbnail --url URL --reference ./face.png --prompt "bold red text 'EPIC'" --output ./thumbs/

| Flag | Description | |------|-------------| | --url | (required) Source video URL — same sources as submit (sourceUri). | | --reference | Optional local image to reference (face, brand asset). Uploaded via /upload-links usecase: FreeToolMedia. | | --mask | Optional local image used as a mask. Same upload flow. | | --prompt | Optional text prompt steering the design (style, copy). | | --output | Output directory for downloaded PNGs (default: /tmp/opusclip-thumbnails-{jobId}/). |

The command POSTs to /generative-jobs with jobType: thumbnail, polls GET /generative-jobs/{jobId} every 5s, and downloads each result.generatedThumbnailUris[] into the output directory (opens it automatically on macOS).

Error codes:

• 403 — not on Pro/Enterprise, or the thumbnail jobType isn't exposed for your account.
• 429 — daily cap or 30 req/min rate limit hit (Retry-After may be present).
• 503 — the endpoint is temporarily disabled (kill switch). Try again later.

The endpoint is governed by a kill switch (pro_api_generative_jobs_enabled); a 503 means the capability is paused, not that something is wrong with your call.

usage

Show the calling org's API cap usage — answers "how much of my monthly API cap have I used / how close am I to the limit?". Takes no flags; reads GET /api/api-usage?q=mine.

opusclip usage

Two output shapes:

• Capped: { uncapped: false, monthly: { used, limit, remaining, reset_at }, concurrent: { used, limit } }. The monthly numbers are the same ones stamped on every API response as X-RateLimit-Limit / X-RateLimit-Remaining (and reset_at is the ISO form of X-RateLimit-Reset), so this can't drift from what's actually enforced; concurrent is in-flight projects vs the concurrent cap.
• Uncapped: { uncapped: true } — the workspace has no API cap (some Enterprise plans); no numbers to report.

Common Workflows

Clip a YouTube video

opusclip submit --url "https://youtube.com/watch?v=VIDEO_ID" --durations "30,60,90"
# Wait for processing, then:
opusclip list --project PROJECT_ID --summary
# Preview clips in browser:
opusclip preview --project PROJECT_ID

--durations is required in practice — the API rejects payloads without curationPref.clipDurations. Pick the target clip lengths you want generated (each value becomes a [0, N] bucket).

Use ClipAnything with a custom prompt

opusclip submit \
  --url "https://youtube.com/watch?v=VIDEO_ID" \
  --model ClipAnything \
  --prompt "Find the most emotional moments" \
  --durations "30,60,90"

Upload a local video, clip, and organize

opusclip upload --file video.mp4 --title "Interview" --model ClipBasic
opusclip list --project PROJECT_ID
opusclip collections create --name "Best Clips"
opusclip collections add-clip --id COL_ID --content-id PROJECT_ID.CLIP_ID
opusclip collections export --id COL_ID

Clip, curate, and share

opusclip submit --url "https://youtube.com/watch?v=..." --durations "30,60,90"
opusclip list --project PROJECT_ID --summary

# Understand clip content
opusclip describe --transcript --project PROJECT_ID --clip CLIP_ID

# Visual review
opusclip storyboard --project PROJECT_ID --clip CLIP_ID

# Share
opusclip share --project PROJECT_ID

Clip, generate copy, and post to social

# 1. Submit and get clips
opusclip submit --url "https://youtube.com/watch?v=..." --durations "30,60,90"
opusclip list --project PROJECT_ID --summary

# 2. See where you can post
opusclip post accounts

# 3. Generate platform-optimized copy
opusclip post generate-copy --project PROJECT_ID --clip CLIP_ID --account ACCOUNT_ID --prompt "witty and engaging"
opusclip post copy-status --job JOB_ID

# 4a. Publish immediately
opusclip post publish --project PROJECT_ID --clip CLIP_ID --account ACCOUNT_ID --title "Check this out!"

# 4b. Or schedule for later
opusclip post schedule --project PROJECT_ID --clip CLIP_ID --account ACCOUNT_ID --title "Check this out!" --at 2026-03-25T14:00:00Z

# Cancel if needed
opusclip post cancel --schedule SCHEDULE_ID

Edit a clip, then post

# Server-side edit (censor / apply)
opusclip edit-clip censor --project PROJECT_ID --clip CLIP_ID --beep

# Wait for the re-render
while :; do
  opusclip describe --project PROJECT_ID --clip CLIP_ID \
    | jq -e '.render_pending != true' >/dev/null && break
  sleep 10
done

# Post the edited clip
opusclip post publish --project PROJECT_ID --clip CLIP_ID --account ACCOUNT_ID --title "..."

Constraints

• Rate limit: 30 req/min
• Max video: 10 hours, 30 GB
• Max concurrent: 50 projects
• Projects expire after 30 days
• 1 credit = 1 minute of video
• Thumbnail API: credit-charged per call (Pro/Enterprise only; currently 7 credits); experimental, may be disabled without notice (503)

API Reference

For detailed endpoint schemas, parameters, and response formats, see references/api-reference.md.