Developer API

Use RipClip from your own program: import a video from a link, find clips in it, read the finished clips with their download links, and save post drafts. The API uses the same account, plan and Horizon Units (HU) as the website, with no extra charge per request.

Basics

Getting a token

A developer key, for your own account

In RipClip open Account, then Connect to AI, then Developer keys. Name the key, tick what it may do and set its monthly HU limit. The key starts with rc_live_ and is shown once, so store it somewhere safe. It lasts 90 days, you can have up to 20, and you can revoke one at any time; it stops working at once.

OAuth 2.0, for an app other people connect

RipClip supports the authorization code flow. The person signs in to RipClip, sees what your app asks for, and approves it. Access tokens last 15 minutes and come with a refresh token.

To get a client ID and secret for your integration, email support@ripclip.org with its name and callback address.

Permissions

ScopeAllows
readRead the account, its videos, jobs, results and clips
importImport a video from a link
generateEstimate a video's cost, find clips and search for moments
planSave a post draft

What it costs

Sending a POST safely

Every POST needs an Idempotency-Key header: 8 to 128 letters, digits, ., _, : or -. Make a new random one for each thing you mean to do, and send the same one again only to retry that same request. For 24 hours the same key with the same body returns the first answer and starts nothing new. The same key with a different body returns 409.

How a job runs

Importing and clip finding take time, so those requests answer 202 straight away with a job_id, a status_url and a results_url. Ask GET /jobs/{job_id} every few seconds until status is done or failed, then read GET /results/{job_id}. Results answer 409 until the job is done.

Endpoints

RequestScopeWhat it does
GET /mereadThe account: its ID, email, plan, HU balance, plan limits, what this token may do and what it used this month.
POST /importsimportImports a video from a link. Body: url, and rights: true to confirm you own the video or have permission to use it. Answers 202 with a job; its result holds the new project_id.
POST /estimatesgenerateWhat finding clips in a video would cost. Body: project_id, and optionally range_start and range_end (0 means to the end). Answers hu and processed_minutes. Reserves nothing.
POST /generationsgenerateFinds clips in a video. Body: project_id and max_hu; optionally count (0 lets RipClip decide, default 5), min_seconds (20), max_seconds (45), prompt (what to look for, up to 500 characters), range_start, range_end, auto_reframe (true), template_id (one of your clipping presets) and ai_titles. Answers 202 with a job and the HU it reserved.
POST /momentsgenerateSearches a video for a topic by meaning. Body: project_id, topic, max_hu; optionally count (5), min_seconds (20), max_seconds (60). The result lists moments with start_seconds, end_seconds, score and quote.
GET /jobs/{job_id}readOne job: job_id, status (queued, running, done or failed), kind, progress, reserved_hu, created_at, finished_at, project_id and name.
GET /jobsreadThe account's newest jobs, newest first. Optional status, kind (generate, import_url or find_moments) and limit (1 to 100, default 25).
GET /results/{job_id}readWhat a finished job made. An import gives its project_id. Clip finding gives each clip's title, start, end and length, a link to open it in the editor, and a download link.
GET /projectsreadThe account's videos, uploads included, newest first: project_id, name, updated_at. Optional limit (1 to 100, default 25).
GET /clipsreadThe account's clips, newest first, each with a fresh download link. Optional limit (1 to 100, default 25).
GET /clips/{clip_id}readOne clip with a fresh download link.
POST /postsplanSaves a post draft for a clip. Body: clip_id, platform (tiktok, youtube, instagram, facebook, threads or bluesky); optionally caption, scheduled_at (ISO 8601 with its offset) and account_id. Nothing is scheduled or published until the person does it in RipClip.

Download links are private and work for 5 minutes. Ask for the clip or the result again to get a fresh one.

Example

Import a video, then find three clips in it for at most 20 HU:

curl https://ripclip.org/api/v1/imports \
  -H "Authorization: Bearer $RIPCLIP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-11-20-a1" \
  -d '{"url": "https://example.com/my-video.mp4", "rights": true}'

# ask GET /jobs/<job_id> until status is "done"; GET /results/<job_id> gives the project_id

curl https://ripclip.org/api/v1/generations \
  -H "Authorization: Bearer $RIPCLIP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clips-2026-11-20-a1" \
  -d '{"project_id": "<project_id>", "count": 3, "max_hu": 20}'

Limits

Errors

An error answers {"error": {"code": "...", "message": "..."}} with a matching HTTP status. A body that doesn't fit the request answers 422 with detail.

CodeMeaning
unauthenticated (401)The token is missing, wrong, revoked or out of date
insufficient_scope (403)The token may not do this
idempotency_required (400), idempotency_conflict (409)The Idempotency-Key is missing, or was already used with a different body
invalid_argument, rights_required (400)A value is not allowed, or rights was not true on an import
budget_exceeded (402)The job would cost more than your max_hu
key_budget_exceeded (402)The key reached its monthly HU limit
insufficient_credits (402)The account doesn't have enough HU
premium_feature (402)This needs a paid plan
source_limit (403)The video is longer than the plan allows
not_found (404)No such video, job or clip on this account
results_not_ready (409)The job has not finished yet
rate_limited, queue_full (429)Too many requests this minute, or too many jobs running for this account. Wait for Retry-After, or for a job to finish
capacity_limited (503)New jobs are paused for a short time; try again later

Help

Questions, or something the API doesn't do yet: support@ripclip.org. Using the API falls under the Terms and the Privacy Policy.