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
- Base URL:
https://ripclip.org/api/v1. HTTPS only. Requests and answers are JSON. - Every request carries
Authorization: Bearer <token>. Browser cookies never work here. - Times are Unix seconds. Lengths and positions in a video are seconds.
- The machine-readable description (OpenAPI) is at
GET /api/v1/openapi.json, with the same token.
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.
- Authorize:
GET https://ripclip.org/oauth/authorizewithclient_id,redirect_uri,response_type=code,scopeandstate - Token and refresh:
POST https://ripclip.org/oauth/token, form-encoded, withgrant_type=authorization_codeorgrant_type=refresh_token
To get a client ID and secret for your integration, email support@ripclip.org with its name and callback address.
Permissions
| Scope | Allows |
|---|---|
read | Read the account, its videos, jobs, results and clips |
import | Import a video from a link |
generate | Estimate a video's cost, find clips and search for moments |
plan | Save a post draft |
What it costs
- Importing a video and asking for an estimate cost no HU.
- Finding clips or moments costs what it costs on the website. You send
max_huwith the request, and RipClip refuses the job instead of going over it. - A job that fails or is cancelled gives its HU back.
- A developer key also has its own monthly HU limit, which you set when you make it.
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
| Request | Scope | What it does |
|---|---|---|
GET /me | read | The account: its ID, email, plan, HU balance, plan limits, what this token may do and what it used this month. |
POST /imports | import | Imports 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 /estimates | generate | What 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 /generations | generate | Finds 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 /moments | generate | Searches 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} | read | One job: job_id, status (queued, running, done or failed), kind, progress, reserved_hu, created_at, finished_at, project_id and name. |
GET /jobs | read | The 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} | read | What 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 /projects | read | The account's videos, uploads included, newest first: project_id, name, updated_at. Optional limit (1 to 100, default 25). |
GET /clips | read | The account's clips, newest first, each with a fresh download link. Optional limit (1 to 100, default 25). |
GET /clips/{clip_id} | read | One clip with a fresh download link. |
POST /posts | plan | Saves 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
- 60 requests a minute for each key. Over that the answer is 429 with a
Retry-Afterheader. - The same video length and job limits as your plan has on the website.
Errors
An error answers {"error": {"code": "...", "message": "..."}} with a matching HTTP status. A body that doesn't fit the request answers 422 with detail.
| Code | Meaning |
|---|---|
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.