Docs

Clip long videos, over an API.

Ounie accounts hit the REST endpoints with a bearer key; AI assistants — including the Ounie AI Team — connect over MCP and get a native tool surface. Both drive the same clipping engine and draw your shared Ounie credits (1 credit = 1¢) — refused when short, never overdrawn. There is no keyless x402 rail.

Overview

Long-form video in, short vertical clips out — as an API.

A job is the unit of work: one source video, a highlight count (1–60), and an aspect ratio. Clipping a long source runs for a few minutes, so a job returns immediately as running and you poll until it settles. Finished clips are stored on permanent public URLs — real mp4 videos you download and post.

The source can be a YouTube URL or a direct video file link(.mp4, .mov, .webm, …). It does not use your Ounie brain — it's an external clipping engine.

Base URL https://clips.ounie.com · JSON everywhere · aspect ratios 9:16, 1:1, 4:5, 16:9, 4:3, 3:4 · max 5 jobs in flight per account.

Authentication

Three credentials, one rule: the caller owns everything it touches.

Session cookie

The dashboard's own auth. Every REST endpoint accepts it, so the calls below work from your browser session too.

App key · clp_live_…

Minted at Dashboard → API keys (shown once, up to 5 active). Send it as Authorization: Bearer clp_live_…or, where headers can't be set, as ?api_key=clp_live_….

Master key · ounie_live_…

One key across the whole Ounie app fleet. Enable "Use across Ounie apps" on the key at ounie.com → Settings → API keys and it works here as a Bearer too. The Ounie AI Team connects with this key in the URL: ?api_key=ounie_live_….

Credits & refusal semantics

Reserve → settle → refund. Refused, never overdrawn.

Clipping is priced on the AI processing it takes: the source video's length plus the number of clips. Submitting a job reserves 20 credits per minute of source video (read at submit) plus 20credits per clip requested, from the caller's shared Ounie wallet. The video charge is fixed; on success the per-clip charge settles on the clips actually returned; a short, failed, timed-out, or aborted job refunds the unused reserve automatically — exactly once, however many pollers race.

If the wallet can't cover the reserve, the call is refused up front with 402 insufficient_credits and a buy_credits_url (https://ounie.com/dashboard/settings). Nothing is charged, nothing goes negative — an agent on your key can never overdraw you.

Free by design: GET reads, the library, clip downloads, and share pages.

REST endpoints

The same routes the dashboard uses. All accept cookie or Bearer auth.

POST/api/jobs— Create a clipping job

{
  "video_url": "https://youtu.be/…",   // YouTube or direct video URL
  "num_highlights": 10,                // 1–60
  "aspect_ratio": "9:16"               // optional, one of 9:16 / 1:1 / 4:5 / 16:9 / 4:3 / 3:4
}

Reserves source minutes × 20 + num_highlights × 20 credits and returns 202 with the job as "running". Poll GET /api/jobs/:id until "succeeded". The video charge is fixed by the source length; you're charged only for clips actually returned.

GET/api/jobs— List jobs

Query params: status=queued|running|succeeded|failed|aborted, limit, offset. Free.

GET/api/jobs/:id— Poll one job

Lazily advances a still-running job — each call can settle or refund it. This is how agents wait on a clip run. Free.

DELETE/api/jobs/:id— Abort or delete

A queued/running job is aborted with a full refund; a finished one is deleted along with its stored clips. Free.

POST/api/jobs/:id/share— Toggle the share page

{ "public": true }

Succeeded jobs only. Returns share_url (/c/:id). Default is private — clips go public only by explicit owner action. Free.

GET/api/credits— Credit balance

Spendable credits + monthly included remaining + buy_credits url. Free.

GET/api/pricing— The price list

Public — the credit formula (per minute of video + per clip), highlight bounds, and aspect ratios. No auth.

For developers & AI agents · MCP

Native tools for Claude, Cursor, ChatGPT, the AI SDK — and the Ounie AI Team.

Endpoint  https://clips.ounie.com/api/mcp
Header    Authorization: Bearer clp_live_…       (or ounie_live_…)

# Clients that can't set headers append the key to the URL —
# this is how the Ounie AI Team connects:
https://clips.ounie.com/api/mcp?api_key=clp_live_…

Tool	What it does	Cost
create_clip_job	Start a clipping run from a YouTube or video URL with a highlight count (1–60) and aspect ratio. Returns immediately with a job id — poll get_clip_job.	minutes × 20 + clips × 20
get_clip_job	Poll one job; advances a still-running clip job and settles or refunds when it finishes.	free
export_clip_job	Return the finished clip URLs for a succeeded job.	free
list_clip_jobs	List your jobs, filterable by status.	free
get_credit_balance	Spendable Ounie credits in the shared wallet.	free
get_pricing	The credit formula — credits_per_minute_of_video, credits_per_clip, and formula — plus bounds and aspect ratios. No auth required.	public
whoami	The authenticated key's owner and key id.	free

The whole loop is async: create_clip_job → poll get_clip_job until succeeded → export_clip_job for the finished clip URLs.

No x402 rail

Clipping needs an account and a key.

Clip Machine has no keyless x402 pay-per-call path. Clipping is a multi-minute asynchronous job — a source is submitted, processed, and its clips re-hosted, which outlives a single 402 response. The reserve → settle → poll lifecycle exists for exactly that, and it needs an Ounie account so the job has an owner and a wallet to settle against.

Agents use a clp_live_ key (or the fleet master ounie_live_key) over REST or MCP, and draw the owner's Ounie credits.

Errors

Errors are JSON: { "error": "code", … }. A charged-then-failed job always refunds.

Code	Status	Meaning
unauthorized	401	Missing or invalid credential — send a session cookie, a clp_live_ Bearer, or ?api_key=.
insufficient_credits	402	The wallet can't cover the reserve (source minutes × 20 + clips × 20). The body includes required, balance, and buy_credits_url. Nothing was charged.
invalid_video_url	400	The video_url isn't a YouTube link or a direct video file URL.
num_highlights_too_high / _too_low	400	num_highlights must be between 1 and 60.
invalid_aspect_ratio	400	aspect_ratio must be one of 9:16, 1:1, 4:5, 16:9, 4:3, 3:4.
too_many_running	429	You already have 5 jobs in flight — wait for one to finish or abort one.
not_found	404	No job with that id belongs to this account.
clipping_unavailable	503	Clipping isn't configured on this deployment.
clipping_failed	502	The provider refused or failed the job. Reserved credits were refunded.

The job object

Returned by every job route as { "job": … }.

{
  "id": "9f2c…",                    // uuid
  "video_url": "https://youtu.be/…",
  "video_label": "youtube · dQw4…",
  "num_highlights": 10,             // clips requested
  "aspect_ratio": "9:16",
  "status": "succeeded",            // queued | running | succeeded | failed | aborted
  "clips": ["https://…/0.mp4", "…"],// public mp4 URLs (succeeded)
  "clip_count": 10,
  "is_public": false,               // share page off by default
  "error": null,
  "source": "api",                  // web | api | mcp
  "credits_reserved": 400,          // source minutes × 20 + num_highlights × 20 (10-min source)
  "credits_spent": 400,             // 0 on failure — the reserve was refunded
  "created_at": "2026-07-13T…",
  "completed_at": "2026-07-13T…"
}