# ClipOnIt API — guide for AI agents

> ClipOnIt turns a long video into short, subtitled, reframed clips. REST API under `/api/*` (OpenAPI 3.1 at `/openapi.json`, interactive docs at `/docs`) and an MCP server at `POST /mcp` (discovery at `/.well-known/mcp.json`). Base URL: https://cliponit.app

## Auth

- API key: `Authorization: Bearer ck_…`. Get one with `POST /api/me/api-key` (returns the key once; Starter plan or above, else 403). The user creates it in the app under Settings → API, or you can log in with `POST /api/auth/login {email,password}` → `{token}` and use that token as Bearer (30 days).
- MCP: same header on `POST /mcp` (JSON-RPC 2.0, streamable-http; JSON responses, SSE only for agent-job waits with a progressToken). 401 without key, JSON-RPC `-32003` if the plan has no API access (free plan). 70 tools, each with `annotations` (readOnlyHint / destructiveHint / idempotentHint / openWorldHint): ask the user before calling a destructive one. A tool error comes back as `isError: true` with text `HTTP <status>: <message> [what to do]`; an unknown tool name is JSON-RPC `-32602`.
- MCP via OAuth 2.1 (Claude.ai / ChatGPT connectors): no key needed. The 401 carries `WWW-Authenticate: Bearer resource_metadata=…`; discovery at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, dynamic client registration `POST /oauth/register`, PKCE S256, access tokens `cko_…` (1 h) + refresh (90 d, rotated). Same plan rules as the API key.
- Chrome extension: `Authorization: Bearer cke_…`, minted by `POST /api/extension/token` from the signed-in website only (session cookie, not a Bearer). It is a portable session, so it works on **every plan including free** (unlike `ck_…`), slides 180 days forward on each call, and is listed/revoked with `GET /api/me/extensions` and `DELETE /api/me/extensions/{id}`.
- Never put the key in a URL.

## Typical flow

1. `GET /api/me` → read `quota` (`videos_used`/`videos_limit`, feature booleans).
2. `POST /api/videos/url {url}` (or multipart `POST /api/videos` with `file`) → video `{id, status:"processing"}`.
3. Poll `GET /api/videos/{id}` every ~10 s until `state` is `ready` (or `failed` → read `error`; `POST /api/videos/{id}/retry`). `state` is `queued` (with `queue_position`) or `running`, `eta_s` is the estimated seconds left (~0.25 × duration). Processing takes ~1-5 min for 20 min of video. Over MCP use `wait_video` instead (server-side long-poll, one call).
4. `clips[]` sorted chronologically; choose by `score` (0-100) and `reason`. Need another moment? `POST /api/videos/{id}/search {query}` creates a clip.
5. Optional edits on a clip (one edit per `?orientation=vertical|horizontal`):
   - `PATCH /api/clips/{id} {start_s, end_s}` to trim (absolute seconds, ≥ 3 s; pick word boundaries from `GET /api/clips/{id}/transcript`)
   - `POST /api/clips/{id}/auto-reframe` (faces → layout/keyframes, synchronous, up to 2 min), THEN `POST /api/clips/{id}/auto-zoom` (a later auto-reframe overwrites zoom keyframes)
   - `POST /api/clips/{id}/silences` → `{cuts}` then `PUT /api/clips/{id}/edit {cuts}` (merge with `edit.cuts` from `GET /api/clips/{id}` if you had some)
   - `PUT /api/clips/{id}/edit` is a partial patch: `{subtitles:{style:"boxed"}}` changes only that field
   - `POST /api/videos/{vid}/clips/{id}/description`, B-roll/music/emojis (Starter+)
   - `DELETE /api/clips/{id}` removes a clip (e.g. one created by search)
6. Subtitle defaults for every new clip edit: `PUT /api/me/subtitle-preset {style, color, size, words_per_line…}` once per account (merged over the built-in defaults, `GET` to read).
7. `POST /api/clips/{id}/export?orientation=vertical` → `{id, status:"queued", eta_s}`, or `POST /api/videos/{vid}/export-all?orientation=vertical` → `{exports:[{clip_id, export_id}]}` (one export per clip). Poll `GET /api/exports/{id}` every ~5 s (`eta_s`, `progress`) until `done` → download `url` (`/files/exports/<id>.mp4`, prefix with the base URL). `GET /api/exports/{id}/frame?t=3` returns a 360 px JPEG to check framing/subtitles. `DELETE /api/exports/{id}` cancels a queued or running export (`status: canceled`). Over MCP use `wait_export`, `export_all_clips`, `get_export_frame`, `cancel_export`.

## Units and conventions

- Times are seconds (float). Clip `start_s`/`end_s`, `cuts`, B-roll and emoji ranges: absolute in the source video. Keyframe `t`: relative to the clip start.
- Zones `{x,y,w,h}` and emoji `x,y`: fractions 0..1. Layouts: vertical (1 zone), split (2), trio (3), spotlight (1), centered (1), horizontal (0 = full frame).
- `PUT /edit` is a patch: every field optional, absent = unchanged; `subtitles` merged field by field; `keyframes`/`cuts`/`broll`/`emojis` replace their list; `music: null` removes it. The edit row (and the account subtitle preset) is created on first access.
- Subtitles: `style` karaoke|boxed|outline|glow|minimal, `color` yellow|white|green|cyan|pink|orange|rainbow, `position` bottom|middle|top, `size` 1|2|3, `words_per_line` 3..8, `lang` "original" or ISO code.

## Errors (`{"error": "message"}`)

- 400 validation (bounds, enums, zone counts) — the message names the field (`champ subtitles.size invalide : attendu 1..3`); fix the payload, do not retry blindly.
- 401 missing/invalid key — ask the user for a key.
- 402 quota reached: monthly videos, 5 searches/day on free, file too big/long on free — stop and tell the user to upgrade at https://cliponit.app/billing.
- 403 feature not in plan: API/MCP (Starter), translation/caption overrides/B-roll/music (Starter), Premiere XML (Pro), exporting the demo video (free) — tell the user, do not retry.
- 404 not found or not owned by this key's user — the message names the resource and id (`clip <id> introuvable…`).
- 5xx transient (face model missing, ffmpeg) — retry once after a few seconds.

## Links

- OpenAPI: https://cliponit.app/openapi.json
- Docs: https://cliponit.app/docs
- MCP: https://cliponit.app/.well-known/mcp.json (endpoint https://cliponit.app/mcp)
- Plans: https://cliponit.app/pricing
- Affiliate program (30% for life): `GET /api/me/affiliate` → `{ref_code, link, signups, paying, pending_cents, paid_cents, payouts}`; share `link`, sign-ups within 60 days are attributed. Public page: https://cliponit.app/affiliates


## Formats & hook (v2026-10)
- orientation: vertical 1080x1920 | horizontal 1920x1080 | square 1080x1080 | portrait45 1080x1350. One independent edit per orientation; auto_reframe supports vertical|horizontal only (square/portrait45 start from a centered crop, use update_clip_edit keyframes to move it).
- subtitles.hook: {enabled, text (null = clip title, max 120 chars), duration_s 0.5..10 (default 2.5), style card|plain} — title card burned at the top during the first seconds. Set it via update_clip_edit or set_default_subtitles before export.
- auto_zoom anchors the punch-in on the mean face box of the clip when faces were detected (run auto_reframe first).

## Explainer videos (v2026-10)
Fully generated vertical videos (voice-over, pixel-art or dithered low-poly 3D scenes) from a JSON script that references catalogue elements by name — you never draw anything. Two styles, chosen by `script.style`: `pixel-news` (default, 2D pixel art panel + HUD + subtitles) and `archibald` (full-screen low-poly 3D, moving camera, red highlights, title/number at the top). Contract: docs/explainer.md.
- `GET /api/explainer/styles` → `[{id, name, description, theme, scene_fields, video_fields, camera_presets, catalogue, library, safe_area}]`; `safe_area` = usable area in panel coordinates (pixel-news e.g. `{x:[0,180], y:[-18,150]}`: subtitles above, caption/credit below) — keep elements inside.
- `GET /api/explainer/library?style=<id>&compact=1` → `{style, text}`: that style's catalogue (~2-3k tokens). Read it once. `?all=1` → merged catalogue (one entry per concept, one variant per style). Animated previews: `/explainer-assets/<style>/el/<name>.webp` (public).
- `POST /api/explainer/check {script}` → `{errors:[], warnings:[]}` (errors empty = valid; warnings such as "scène 3, élément 2 (label) : touche la zone des sous-titres" never block the render). A word anchor not found in `say` is an error.
- Script features: element `in`/`out` = seconds or `{word, occurrence?, offset?, edge?:"end"}` (when that word of the scene's `say` is spoken, real voice timing); video `cast` `{id: {hair, hair_color, beard, glasses, outfit, colors, party, label…}}` + element `who: id` (element `figure` = configurable person); 2D elements `scale` 0.25..6, `anchor` center|bottom, `zoom {to, at:[t0,t1], x?, y?}`; scene `camera.target` = element index; video `gap` (s between scenes, default 0.3, 0..2; 0 with imported audio), `subscribe_text` (end-screen slogan, "" = none). The server passes them through untouched.
- `POST /api/explainer/library/suggest-batch {texts: [≤ 60 sentences or short concept queries], style?, limit?}` → `{results: [one suggest text per input, same order]}` — one call for the whole video instead of `?suggest=` per scene.
- `POST /api/explainer/preview {script, scene, t}` → `image/jpeg` 1080x1920 (scene index from 0, t seconds from the scene start; voice timing estimated).
- `POST /api/explainer/compose {topic, selection?, style?}` → `{script}` written by the server's Claude (up to ~3 min, paid plans).
- `POST /api/explainers {script}` → 201 `{id, status:"queued", warnings}` (paid plans; 400 `{error, errors, warnings}` if invalid; warnings alone never block); the same script already queued or running → 200 `{id, status, duplicate:true}` (no second render). Render ~4 min.
- `GET /api/explainers/{id}` → `{id, title, status queued|running|done|failed, progress 0..1, url (/files/exports/explainer_<id>.mp4 when done), error, created_at, script, ahead (queued only: renders before this one)}`; `GET /api/explainers` lists them (newest first); `DELETE /api/explainers/{id}`.
- Own pixel art (pixel-news element `custom`, self-contained in the script): `{"el":"custom", "pixels":["..11..", ...] (1 char = 1 px, "." transparent, max 128x100), "palette":{"1":{"name":"part name","color":"#rrggbb or theme token accent|accent sombre|clair|gris clair|gris|gris foncé|sombre|noir"}} (≤ 24), "frames":[[rows], ...] (≤ 12 images), "fps":4, "anchor":"center|bottom", x, y, k, parts:{name:#hex}}`.
- `GET /api/explainer/my-elements` → `[{id, name, family, data, element (ready to insert), preview}]`; `POST` `{name, family?, pixels, palette, frames?, fps?, anchor?}` (or `{name, kind: "3d", primitives}`) → 201 (validated, 200 per account); `GET|PUT|DELETE /api/explainer/my-elements/{id}`; `GET …/{id}/preview.webp` (animated); `POST /api/explainer/pixelize` multipart `file`, `width` 16..128, `colors` 2..24, `theme` 1 → `{pixels, palette}`.
- Shared library in DB (table library_elements, docs/explainer.md §1 sexies): `GET /api/explainer/library/elements?q=&path=&kind=code|data&style=&enabled=1|0|all&limit=&offset=` → `{total, items: [{style, name, kind, family, path, tags, description, params, parts, preview, source, enabled, data, element}]}` (any account; enabled=0/all: admins). Admins (`ADMIN_EMAIL` or `ADMIN_EMAILS` comma list): `POST /api/explainer/library/elements` {name ([a-z][a-z0-9_], unique per style), style?, family?, path?, tags?, description?, data: custom {pixels, palette, ...} or custom3d {kind: "3d", primitives}, enabled?} → 201 (validated, animated preview `/explainer-assets/data/{style}/{name}.webp`; usable by name in scripts and listed by library/search/suggest/browse without a redeploy); `PUT …/{style}/{name}` {enabled?, family?, path?, tags?, description?, data?} (code elements: enabled only); `DELETE …/{style}/{name}` (data: deleted; code: disabled). enabled=false hides an element from the index, search, suggest, browse and the catalogue page (existing scripts still render). `POST /api/explainer/my-elements/{id}/publish` {name?, path?, tags?, ...} → 201 {status: "pending"} (admin enables it).
- Custom 3D objects (style archibald): element `custom3d` {primitives: [{shape: box|cylinder|cone|sphere|dome|torus|hyperboloid|plane|prism|group, part, pos [x,y,z], rot [x,y,z] deg, scale, color (#hex or "accent"), shade 0..1, segments, motion {type: spin|swing|slide, axis, speed|angle|period|offset}, ...shape params}]}; groups {shape: "group", children: [...]}; max 64 primitives, 16 parts, 20k triangles. Save one: `POST /api/explainer/my-elements` {name, kind: "3d", primitives}; list with `?kind=3d|all` (default 2d).
- `GET /api/explainer/schema?style=pixel-news|archibald&elements=a,b` → JSON Schema 2020-12 of the script, generated from the catalogue (full ≈ 2 MB; `elements` = short schema for structured outputs).
- `POST /api/explainer/export` {script | element, format: glb|obj|png|gif|sheet|explainer, scene?, t?, scale? 1..16, animate?, fps? 1..60 (30), all_scenes?, particles? full|lite|off (lite)} → file (glb = glTF binary, one node per part, animated by default like the video: moves, entries/exits, moving parts, camera with its move, red highlight (KHR_animation_pointer + grey/red swap fallback); animate:false = static at t; all_scenes = whole video, one animation per scene + "Vidéo complète"; particle effects (smoke, steam, fire, explosion, cloud) = one animated unlit sphere per particle, color/opacity via KHR_animation_pointer, emissive fire (particles: lite = ≤ 150 per effect at ≤ 15 fps, full, off); obj = zip obj+mtl, static by nature (animate:true → 400); sheet = zip png+json; explainer = .explainer.json); `GET /api/explainer/my-elements/{id}/export?format=…&animate=…&fps=…&particles=…`.
- Import your own voice-over (the video plays it instead of TTS): `POST /api/explainer/audio` multipart `file` (audio or video, ≤ 300 MB) or JSON `{url}` (YouTube or direct audio link) → 202 `{id, status:"queued"}` (paid plans; max duration = plan limit, 30 min at most: 402 on upload, `failed` for a link; YouTube blocked → error asking to upload the file). The server transcribes it word by word and splits it into scenes. `GET /api/explainer/audio/{id}` → `{id, name, source_url, status queued|running|done|failed, progress 0..1, error, duration, created_at}` + `text`, `language`, `scenes [{say, start, end, words}]` when done; `GET /api/explainer/audio` lists them; `GET /api/explainer/audio/{id}/file` → audio/mpeg (Range supported); `DELETE /api/explainer/audio/{id}`. `POST /api/explainer/audio/{id}/compose {style?, topic?}` → `{script}` (one scene per segment, `say` = transcript, `audio: {id, segments:[[start,end],...]}`); keep `audio` as is, then check / preview / render as usual. A script whose audio was deleted → 400. Any `audio.src` / `audio.words` you send is ignored.
- MCP: explainer_styles, explainer_library {style}, explainer_suggest_elements {text | texts (≤ 60), style?, limit?}, explainer_browse {path?, style?}, explainer_search_elements {query}, explainer_describe_elements {names}, explainer_check (errors + warnings), explainer_preview (inline JPEG), explainer_compose, explainer_render, explainer_wait (≤ 120 s long-poll), explainer_list, explainer_delete {id}, explainer_audio_list, explainer_my_elements {id?}, explainer_create_element (2d or kind 3d), explainer_library_elements {q?, path?, kind?, style?}, explainer_library_add_element {name, data, style?, family?, path?, tags?, description?} (admins), explainer_schema {style, elements?}, explainer_export {format, script|element|id, animate?, fps?, all_scenes?, particles?} → temporary URL (24 h) + inline file when < 200 KB, explainer_import_audio {url} → explainer_audio_status {id} (≤ 120 s long-poll, until done) → explainer_compose_from_audio {id, style?, topic?} → explainer_check → explainer_render.

Explainer catalogue for AIs: GET /api/explainer/library?style=pixel-news&compact=1 = index of element names by family (~6k tokens); &describe=a,b = exact parameters and parts of those elements; &search=words&limit=n = keyword search (both styles; lines end with | path=… | tags=… | preview=…); ?browse=<path> = walk the taxonomy of ~10,000 elements (empty = 48 root categories with counts; a node = sub-nodes + its elements when ≤ 80; path ≤ 200 chars, no ..); ?suggest=<narration sentence>&limit=n (≤ 500 chars, 1..30, default 10) = best elements for a scene. browse/suggest without style = all styles. MCP order: explainer_library once -> explainer_suggest_elements per scene (or explainer_browse / explainer_search_elements) -> explainer_describe_elements -> explainer_check -> explainer_render.

## Agents: produce a video end to end without a human
- `POST /api/agent/produce` {topic | script | audio_id | audio_url (exactly one), style?, duration_s 15..180?, voice?, brand? bool, title?} → 202 {job}: compose → check → render in the background.
- `GET /api/jobs/{id}` → {id, status queued|running|done|failed|canceled, step queued|transcribe|compose|check|render|done, step_label, step_label_en, percent 0..100, message, explainer_id, doc, url (absolute mp4 link when done), editor_url (absolute link opening the video in the editor), error, cost_usd}; `GET /api/jobs?active=1`; `POST /api/jobs/{id}/cancel`; `GET /api/jobs/{id}/events` (SSE).
- Templates: `GET /api/explainer/my-templates`, `POST /api/explainer/my-templates` {name, description?, script with {{params}}}, `POST /api/explainer/my-templates/{id}/run` {values, mode fixed|recompose, style?, voice?, brand?, duration_s?} → 202 {job}.
- Errors: 402 monthly render quota or AI budget reached, 403 plan or read-only key (do not retry), 429 two jobs already running (retry later).
- MCP: get_quota → explainer_produce → explainer_job_wait {job_id} until done (streams notifications/progress when the call has _meta.progressToken and Accept: text/event-stream, up to 1800 s; otherwise ≤ 120 s, call again) → url. Templates: explainer_my_templates → explainer_template_run → explainer_job_wait. Also explainer_job_status, explainer_jobs {active?}, explainer_job_cancel, explainer_template_save.
- Reference client (Python stdlib): scripts/mcp_agent.py --url …/mcp --key ck_… --topic "…" --duration 45 --out dir.