# 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).
   The account owner gets an e-mail when a video finishes processing (clips ready, or failed); turn it off with `PATCH /api/me {notify_ready:false}` (`user.notify_ready` in `GET /api/me`). `user.live` says whether the Live studio (`/api/live/*`) is open for this account.
2. `POST /api/videos/url {url}` (or multipart `POST /api/videos` with `file`) → video `{id, status:"processing"}`.
   Optional clip objective (same fields as multipart text fields, `resources` as JSON there): `goal` = views | clients | comments | followers, `brief` (≤ 1000 chars), `resources` (≤ 5: `{kind:"site", url:"https://…"}` = the offer's site, read server-side to align the CTA; `{kind:"video", video_id}` = another of your videos for B-roll). It changes which moments are picked, the score (`score_detail.goal_fit`, 30 %), the titles, and adds `clip.cta` (caption call to action). Change it later with `PUT /api/videos/{id}/objective {goal?, brief?, resources?}` (replaces; `GET` to read, incl. `site_summary`) then `POST /api/videos/{id}/regenerate`. MCP: `import_video_url` / `upload_video_file` take the same fields; `set_video_objective {video_id, goal?, brief?, resources?, regenerate?}`.
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, weighted sum of `score_detail` sub-scores 0-10: hook, standalone, payoff, emotion, value, shareability) and `reason`. YouTube imports may also return `heatmap: [{start_s, end_s, value}]` (the "Most replayed" curve, value 1 = most replayed slice; absent when YouTube has none) — handy to check which parts viewers rewatch. Need another moment? `POST /api/videos/{id}/search {query}` creates a clip (AI search), or `POST /api/videos/{id}/clips {start_s, end_s, title?, snap?}` creates one from exact bounds (3-180 s, snapped to sentence starts/ends within 0.6 s, else to the nearest word boundary within 0.6 s, unless `snap:false`; AI title when omitted, written in the background a few seconds after the response (the response carries the first words as a provisional title), inserted chronologically, no quota; full transcript with word timings: `GET /api/videos/{id}/transcript`, each segment carries `speaker` (0, 1, 2…) when the video was diarized). MCP: `create_clip`.
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). `goal` echoes the clip goal chosen at import (`views|clients|comments|followers`, null if none). 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, weighted sum of `score_detail` sub-scores 0-10: hook, standalone, payoff, emotion, value, shareability) and `reason`. YouTube imports may also return `heatmap: [{start_s, end_s, value}]` (the "Most replayed" curve, value 1 = most replayed slice; absent when YouTube has none) — handy to check which parts viewers rewatch. Need another moment? `POST /api/videos/{id}/search {query}` creates a clip (AI search), or `POST /api/videos/{id}/clips {start_s, end_s, title?, snap?}` creates one from exact bounds (3-180 s, snapped to sentence starts/ends within 0.6 s, else to the nearest word boundary within 0.6 s, unless `snap:false`; AI title when omitted, written in the background a few seconds after the response (the response carries the first words as a provisional title), inserted chronologically, no quota; full transcript with word timings: `GET /api/videos/{id}/transcript`). MCP: `create_clip`.
5. Optional edits on a clip (one edit per `?orientation=vertical|horizontal`):
   - `PATCH /api/clips/{id} {start_s, end_s}` to trim, `{title}` to rename (unknown fields → 400) (absolute seconds, ≥ 3 s; pick word boundaries from `GET /api/clips/{id}/transcript`)
   - `POST /api/clips/{id}/auto-reframe?mode=auto|speaker_tracking|keynote_split|keynote_speaker|follow|mix&framing=tight|medium|wide` (faces + camera cuts + speech level + slides → layout/keyframes, synchronous; `auto` (default, also applied in 9:16 to every detected clip after import) = keynote if a slide + speaker are detected, else `speaker_tracking` = frame whoever is talking (audio × mouth movement), clean cut per turn, split during rapid exchanges; `keynote_split` = slide on top + speaker (layout `keynote`); `keynote_speaker` = speaker only; `mode=mix` = mixed auto layout per shot: vertical / split / trio / full-frame wide shot; `framing` default medium, zoom capped), THEN `POST /api/clips/{id}/auto-zoom` (a later auto-reframe overwrites zoom keyframes)
   - `POST /api/clips/{id}/silences` → `{cuts}` (adaptive threshold, works with background noise) then `PUT /api/clips/{id}/edit {cuts}` (merge with `edit.cuts` from `GET /api/clips/{id}` if you had some)
   - `POST /api/clips/{id}/tics?intensity=light|normal|aggressive&apply=true` → removes ums, hesitations, repeats, false starts and dead air (keeps manual cuts; each auto cut has `kind`, removable one by one). Or `POST /api/clips/{id}/export?tics=normal` to do it at render time.
   - `POST /api/clips/{id}/export?style=premium` (also `export-all`; paid plans) → the "Premium" render, edited for the scroll without touching the edit: hook card quoting the clip, uppercase 3-word captions with keywords in yellow, ums/silences cut, shots from the video, light punch-ins, -14 LUFS. `style=standard` (default) = the edit as is.
   - `POST /api/montages` {media_ids, intent, reference_url | template_id | recipe, music, rights: true} (paid plans, 1 video of the monthly quota) → "Montage": the user's rushes (uploaded with `POST /api/media`) edited into a 9:16 video on the STRUCTURE of a reference link (TikTok, Reels, Facebook, Shorts: cuts, layout, on-screen texts, captions, tempo; the file is deleted after analysis, already-analysed references are reused for free) or a house format (`GET /api/montage/templates`: tier list, two-column sort, paid vs free, rated /10, wrong vs right split, before/after…). Poll `GET /api/montages/{id}` → url, edit_url, report (cost_usd, warnings). Recipe JSON schema: `GET /api/montage/schema`. Find references: `GET /api/montage/search?q=`. MCP: `montage_create`, `montage_wait`.
   - « Sans musique » (no music): `POST /api/clips/{id}/export?music=0` (also `export-all`, `montage=…`) → the render leaves out every music WE add (edit music bed, Montage pro library track); the clip's own sound/voice stays, loudness target unchanged. Remembered with the clip edit (`no_music`, also settable by `PUT /api/clips/{id}/edit {no_music:true}`); `music=1` puts it back. For the user to post, then pick a trending licensed sound in TikTok (« Add sound » → Trending, then « Volume » to keep the voice on top) or Instagram Reels (« Audio »). ClipOnIt never supplies third-party music. MCP: `music: false` on export_clip, export_all_clips, montage_pro, render_clip. Montage: `POST /api/montages {music: "none"}`. Explainer: `script.mix.mute: ["music"]` (also removes a chosen `script.music`).
   - `POST /api/clips/{id}/export?montage=entrepreneur|podcasteur|formateur|ecole|marque|auto` (paid plans, once `GET /api/montage` says `enabled`) → "Montage pro": Premium render edited like an ad — cold open on the strongest verified line, TikTok loop with rewind (`loop=1`), musical beat (wordless moment of the source chosen by loudness/motion), interlude shot from the shot index, boxed title, rhythm; options `cold_open`, `loop`, `moment`, `intermede`, `title` = 1/0; `auto` reads `brief` (« façon pub avec une boucle »). On a whole video: `POST /api/videos/{vid}/export-all?montage=…&n=3` = the 3 best moments. The export's `montage_report` lists what was applied or skipped and a hook score 0-3. MCP: `montage_pro`. Editable plan first: `POST /api/clips/{id}/montage/plan?recipe=entrepreneur` → cold-open options, title, musical beats, interlude shots, verified data cards (counter, table, transfer, quote) and toggles (split screen, ambient shots, loop, pace, handle); send it back as `{plan}` in the body of the export call.
   - `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+)
   - B-roll from the user's own video (Starter+): `POST /api/clips/{id}/broll/illustrate?orientation=` adds muted full-frame inserts taken from OTHER moments of the same source that show what is said (no talking-head shot, 1.5-2.5 s, ≥ 4 s apart; first call indexes the video, ~30-60 s) → `{broll, inserts, shots_indexed}`; `GET /api/clips/{id}/broll/shots` lists usable shots, `POST /api/clips/{id}/broll/from-video {start, end, source_s, shot?}` places one yourself. Add `?source_video_id=` (or `source_video_id` in the from-video body) to take the shots from another of your ready videos. MCP: `illustrate_clip_with_video`, `list_video_shots`, `add_video_broll`. Illustrate and shots also draw on the account's B-roll library (shots from your other videos; `source_video_id` on those shots).
   - B-roll library (all plans; free: 12 shots): reusable shots extracted from each of your videos (no talking head, not dark, sharp, 1.5-6 s) as 720x1280 + 1280x720 MP4 with tags, description and quality score. `GET /api/broll/library?q=&video_id=&tag=&favorite=` → `{items:[{id, video_id, start_s, end_s, description, tags, score, favorite, vertical_url, horizontal_url, thumb_url}], videos:[{id, status}], max}`; `PATCH /api/broll/library/{id} {favorite}`, `DELETE /api/broll/library/{id}`; `POST /api/videos/{id}/broll-library` (extract on demand, automatic on paid plans); `POST /api/clips/{id}/broll/library?orientation= {item_id, start, end?}` places one. `GET /api/videos/{id}/shots` = the full visual index as JSON (`talking`, `library`). MCP: `broll_search`, `broll_list`, `broll_add_to_clip`.
   - Add media (clip editor + Explainer studio): sources `{kind: broll|clip|upload, id}` resolved only for their owner. `GET /api/media` (your uploads), `POST /api/media` (multipart `file`, video or image, 200 MB, Starter plan; images become a 30 s still), `DELETE /api/media/{id}`, `GET /api/media/clips?q=` (your clips). Clip: `POST /api/clips/{id}/broll/media?orientation= {kind, id, start, end, mode: full|pip|split, audio}` → broll list (`place` + `audio` per item). Explainer: scene field `media: {kind, id, mode, at, dur?, audio}`, embedded at render.
   - `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), keynote (2: slide on top in 16:9, speaker below).
- `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|behind|serif|hollow|highlight (behind = one giant word behind the person, Premium), `bw` true = black & white, `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
- Integration guide (copy-paste curl / JavaScript / Python, MCP client configs, webhooks, quotas per plan): https://cliponit.app/integrations
- MCP: https://cliponit.app/.well-known/mcp.json (endpoint https://cliponit.app/mcp), server card SEP-2127 https://cliponit.app/mcp/server-card
- Catalogs: https://cliponit.app/.well-known/ai-catalog.json (AI Catalog), https://cliponit.app/.well-known/api-catalog (RFC 9727 linkset)
- 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 all four (square/portrait45: same face-following plan as vertical, at their own ratio).
- 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. Styles chosen by `script.style`: `pixel-news` (default, 2D pixel art panel + HUD + subtitles), `archibald` (full-screen low-poly 3D, moving camera, red highlights, title/number at the top), and every other style listed by `GET /api/explainer/styles`. Contract: docs/explainer.md.
- `GET /api/explainer/styles` → `[{id, name, description, family (visual family), scene (2d|3d: scenes shaped like pixel-news / archibald), tags, poster, 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.
- `GET /api/explainer/library/items?style=&family=&q=&offset=&limit=` → `{total, items: [{el, concept, family, kind, preview, description, tags, path, styles}], style_total, families: [{name, n}], styles: [{id, name, n}], concepts, variants, animations}` — paged browse of a style's whole element library (limit ≤ 120), `q` = engine search (meaning + words) then word match.
- `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}}`.
- Import your own style: `POST /api/explainer/my-styles` multipart `files` (3-10 references: PNG/JPG/WebP ≤ 8 MB, one MP4/MOV/WebM ≤ 40 MB counts as 3, one TTF/OTF font), `consent=true`, `name?` → 201 {id: "perso-<hex>", name, base (closest registry style), engine, palette {bg, accent, ink, colors}, knobs {trait, grain, intensite} 0..1, font, description, candidates, demo: [3 JPEG URLs], cost_usd, secs}; `GET /api/explainer/my-styles` → {styles, limit}; `GET|DELETE …/{id}`; `PUT …/{id}` {name?, knobs?, palette?, font?, base?, regenerate?: true = next closest engine} (demo re-rendered); `GET …/{id}/demo/{0|1|2}.jpg`. Private: listed in `GET /api/explainer/styles` for its owner only (`private: true`), usable as `script.style`. Paid plans, styles per plan: starter 2, pro 5, business 20 (402). MCP: style_import, style_list.
- `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=<style id>&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=…`.
- Listen to one scene's voice exactly as the render will produce it: `POST /api/explainer/voice/take {voice, say, fresh?}` (`voice` = the script's `voice` object as is, `say` = the scene's text ≤ 2000 chars) → `{url, dur, words:[{w, red, t0, t1}], cached, cost_usd, fallback?}`; `GET {url}` → audio/wav (owner only, Range). Same per-account voice cache as rendering: already synthesized → free and reused by the next render. `fresh: true` = new take (cache entry replaced; the next render uses it). Paid plans; 100 syntheses per day (then cached voices only, 402); 503 if no voice provider is available.
- 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. Change the audio while keeping the visuals: import or record a new one, then `POST /api/explainer/audio/{id}/fit {says: [current text of each scene]}` → `{id, duration, matched, segments, says}` (no AI cost); put `id` and `segments` in `script.audio`. Audio tracks of the render: `script.mix = {voice, music, sfx: volume 0..2 (1 = normal), mute: ["music"…]}`; background music: upload with multipart `source=music` (not transcribed, no audio minutes) and set `script.music = {id, name}` (looped, ducked under the voice). An audio without speech (music, silence) ends `failed` with an error starting `no_speech:` instead of a phantom transcript such as “Thanks for watching!”.
- 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. `voice` = an ElevenLabs voice of the catalogue, by id or name — French: N6vE6dp4ouYqQlMCBL5j Guillaume (Natural, relaxed storyteller), J50pwizkkVglhJNh30K8 Aslan (Lively social-media tone), jfEwztGDkpbpy89xeku6 Cyp (Soft and calm, for explaining), TojRWZatQyy9dujEdiQ1 Koraly (Expressive storyteller), O31r762Gb3WFygrEOGh0 Victoire (Young and fluid, TikTok tone), 5OnMHwgTFgvPVwE8jP6B Anaïs (Clear and educational, news tone); English: nPczCjzI2devNBz1zQrb Brian (Deep, warm narrator), TX3LPaxmHKxFdv7VOQHJ Liam (Energetic short-form creator), pFZP5JQG7iQjIQuC4Bku Lily (British, clear, documentary tone), cgSgspJ2msm6clMCkdW9 Jessica (Bright and playful). The voice's language is the video's language. In a script: `voice: {voice_id, model?: "eleven_v4", style?: 0..1 expressiveness (default 0.3), speed?: 0.5..2}`; old scripts with an OpenAI `voice` name (ash, nova…) still render with OpenAI. Without a voice: N6vE6dp4ouYqQlMCBL5j (French).
- `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.


## Creation tools and execution plans (any agent, v2026-11) — docs/outils-creation.md
- `GET /api/agent/tools` → `{tools:[{name, description, input_schema (JSON Schema, additionalProperties:false), output}]}`; `POST /api/agent/tools/{name}` with the arguments as body → the tool's JSON output (400 names the bad field).
- Tools: import_video, detect_moments, cut_silences_tics, reframe (modes passed through), illustrate_with_source (internal B-roll), add_hook, style_captions, edit_clip, render_clip (tier standard|premium, waits), make_loop (payoff → rewind → start, seamless loop), add_music_beat (1.5-4 s shot without speech under music or real sound), check_dark_shots, brighten, critique_clip (measures + vision model chosen by the server's CRITIQUE_MODEL + checklist, timed fixes, contact sheet), predict_clip (honest percentile, measured interval, reliability; never an invented view count), improve_clip (fixes → ready-to-run plan), produce_explainer, partners_join, publish_tiktok (returns a confirm_url: posting needs the account owner in a browser session).
- Post-processing tools (make_loop, add_music_beat, brighten) create a NEW export (`parent_id`, `tool`) usable like any export. Clip/edit times are absolute source seconds; export times (at_s, loop_at_s, ranges) are the export's own timeline.
- `POST /api/agent/plan` `{steps:[{id?, tool, args}], vars?}` or `{template, vars}` → `{plan_id}`; the whole plan is validated before step 1. Args may reference earlier outputs: `"$prev.export_id"`, `"$<step id>.moments.0.clip_id"`, `"$vars.x"` (absent var = optional field omitted). `GET /api/agent/plan/{id}` → `{status running|done|failed, error, steps:[{tool, ok, output|error, ms}], output}`. Max 30 steps, 2 running plans per account.
- `GET /api/agent/plan-templates`: clip_long_video_premium {video_id, query?, music_id?, hook?, intention?}, import_and_clip {url, …}, critique_and_improve {export_id}, analyze_competitor_video {url}, saas_ad_from_url {brief}, partners_campaign_clip {campaign_id}. A small model only has to pick one and fill `vars`.
- MCP: the same tools by name, plus plan_templates, run_plan {template|steps, vars, wait}, plan_status {plan_id}; templates are also MCP prompts. ChatGPT/Claude setup: docs/connecteurs-ia.md, /help/connecteurs.

## Intégration TikTok — session utilisateur uniquement
La page /settings/tiktok connecte le compte TikTok, importe les vidéos autorisées et propose brouillon, Direct Post, programmation consentie et statistiques publiques. Aucune de ces actions n'est exposée au MCP ni aux clés API : ouvrir l'interface pour obtenir les choix et consentements du titulaire.
GET/DELETE /api/tiktok/account : état/capacités ou révocation. GET /api/tiktok/connect puis /api/tiktok/callback : OAuth lié au cookie de session. GET /api/tiktok/creator : visibilité, interactions et durée permises. GET /api/tiktok/sources : exports appartenant à l'utilisateur (kind clip : id = export_id ; kind explainer : id = explainer_id). POST /api/tiktok/import {url,rights_confirmed:true} : import soumis aux quotas et droits.
GET/POST /api/tiktok/posts : historique ou demande {source_kind,source_id,mode:direct|draft,title?,privacy_level?,allow_comment?,allow_duet?,allow_stitch?,brand_organic?,brand_content?,is_aigc?,consent:true,rights_confirmed:true,no_watermark_confirmed:true,scheduled_at?:RFC3339,idempotency_key:UUID}. Direct Post exige confidentialité explicite et is_aigc=true pour un explainer ; programmation entre une minute et 30 jours. Réponse Post : id, source_kind, source_id, title, mode, privacy_level, status, scheduled_at, publish_id, video_ids, error, stats, share_url, created_at, updated_at. Même UUID + même corps = même demande ; corps différent = 409.
DELETE /api/tiktok/posts/{id} : annulation scheduled/queued uniquement. POST /api/tiktok/posts/{id}/refresh : statut et compteurs. GET /api/tiktok/posts/{id}/metrics : instantanés horaires sur 30 jours. GET /api/tiktok/analytics?cursor= : 20 vidéos publiques, views/likes/comments/shares ; aucune rétention ou statistique publicitaire. POST /api/tiktok/webhook : signature HMAC TikTok sur corps brut, sans session.
États : scheduled, queued, submitting, processing, inbox_delivered, published, failed, canceled, unknown. Un brouillon doit être terminé dans TikTok ; un statut unknown exige une vérification manuelle, sans nouvelle publication automatique. Secrets et jetons restent côté serveur. Activation soumise au domaine vérifié, aux scopes réellement accordés et à l'audit TikTok ; avant audit Direct Post est limité à SELF_ONLY. Voir docs/tiktok-integration.md et les schémas TikTok de /openapi.json.

## Premium (HeyGen avatars and dubbing, paid plans, premium credits)
- Hidden unless `GET /api/premium/status` returns `{enabled:true}` (otherwise 404 and no `premium_*` MCP tools).
- `GET /api/premium` (balance, price per minute, packs), `GET /api/premium/catalog` (public avatars, voices, languages).
- `POST /api/premium/avatar {avatar_id, tier?: standard|premium, voice_id?, script? | explainer_id?, consent?, dry_run?}` and `POST /api/premium/translate {clip_id, language, quality?: speed|precision, consent, dry_run?}`: call with `dry_run:true` first (price, consent text), then without. `consent:true` is required for dubbing a clip and for an avatar on an explainer's voice. Returns a job; poll `GET /api/premium/jobs/{id}` until `done` (`url`) or `failed` (credits refunded).
- Errors: 402 = free plan or not enough credits, 429 = 2 jobs running or the 24 h cap (30 min avatar, 60 min dubbing). MCP: `premium_status`, `premium_catalog`, `premium_avatar`, `premium_translate`, `premium_job_wait`.

## Reliability constraints

Uploads enforce the plan byte limit while receiving chunks, even without Content-Length. URL imports reject credentials, local hostnames and literal private/reserved IPs; the video downloader has a one-hour deadline and monitors partial-file size. DNS rebinding and redirects require additional network isolation. A B-roll edit/render may only reference an id/path registered for the same clip and account. Removing it from an edit preserves the source for Undo and other orientations until clip/video/account deletion or retention; shared files are deleted after their last reference. Exports fail explicitly when required subtitle/watermark filters are unavailable; polling must handle failed and canceled states. Overlapping cuts count once toward removed duration. Exports allow at most 512 retained audio ranges after merging cuts; larger fragmented edits fail explicitly before FFmpeg starts.

Video/import/export creation and job enqueue are atomic; concurrent retries cannot create duplicate active jobs. Regeneration preserves existing clips/edits/files until a successful transactional replacement. Explainer creation (including free examples) and audio import/cleaning atomically commit their object, applicable quota and job. An identical queued/running explainer script returns the existing render, including at the final monthly credit. /files serves only allowed media/export formats with noindex and private no-store headers; internal sidecars are blocked, but known media URLs remain anonymously accessible.

Export cancellation is durable across render completion, retries and worker restart. A cancellation committed before final publication prevents the output and success event; if completion already committed, the finished export remains available.

## ClipOnIt Live (podcast en direct)
Pro (4 h of live per month, 2 guests) and Business (20 h, up to 3 guests) plans (closed until LIVE_ENABLED; 404 live_disabled). GET/POST /api/live/sessions {title?, max_guests 1..3 (402 above the plan), format? 16:9|9:16, goal? views|clients|comments|followers} → {id, status:ready, invite_url}; one open session per account (409), monthly live minutes (402). POST /api/live/sessions/{id}/join: host (session) or guest {invite_token, name, consent:true} → {participant, secret lvp_… (once), sfu:{url, room_id, token, peer_id, ice_servers}}; WebRTC media goes browser → LiveRelay SFU directly (POST {sfu.url}/sfu/conference, then /sfu/conference/subscribe {target_peer_id} for later joiners). POST …/start, …/end (writes the post-live manifest), GET …/events (SSE, ?pt=lvp_…), POST …/events {kind moment|scene|speaker|title|note, t_ms}. Local recordings: POST …/tracks {kind, mime, t0_ms} → track_id; PUT …/tracks/{track}/chunks/{n} (raw bytes ≤ 50 MB, any order); POST …/tracks/{track}/complete {chunks}. Incoming sources (OBS/RTMP/SRT/WHIP): POST …/sources {name, kind} → stream_key + URLs. GET …/manifest. After the live: GET …/episode → {status queued|running|ready|failed, progress, episode_url, tracks[{id,name,kind,url}], markers, video_id} (assembled in the background from the host program, falling back to cameras then black when chunks are missing); POST …/episode restarts it; POST …/episode/send → {video_id, url} creates the Smart Clipper video (same quotas as an import, 402; 409 until ready); GET …/files/episode|{track_id} downloads. Moments marked during the live become clip candidates proposed first (clip.live_marker true). No detection during the live, no streaming. Full contract: docs/live-api.md. MCP: live_create_session, live_list_sessions, live_episode_status, live_send_to_clipper.
## Promo video from a SaaS URL (closed: PROMO_ENABLED + admins; 404 promo_disabled)
POST /api/promos {url, brief?, lang? fr|en, voice? (catalogue name/id or ElevenLabs id), duration_s? 30-60, auto_render?} → {id, status: exploring}. A headless browser films the public site (robots.txt, GET only, no login, no form, personal data blurred) and reads brand colors, fonts, logo and prices as written; an LLM writes a storyboard from the site only (hook, problem, demo, proof, price, cta) → status storyboard (warnings = numbers/quotes not found on the site). PUT /api/promos/{id}/storyboard {storyboard} to edit, POST /api/promos/{id}/render → rendering → done (outputs.videos {16x9, 9x16}, planches, video_id + shorts [{clip_id, export_id, hook}] exported vertically) or config_ready (render engine not plugged: outputs.config_json). GET /api/promos/{id} → status, progress, site, storyboard, outputs, cost {usd, calls}. GET /api/promos, DELETE /api/promos/{id}. MCP: promo_create (auto_render true by default), promo_status.

## Partnerships (paid clipping campaigns, closed: PARTNERS_ENABLED + admins; 404 partners_disabled)
A creator opens a campaign on his ready videos; clippers are paid per 1,000 views (cpm_cents) from the budget. GET /api/partners/campaigns?scope=open|mine|joined. POST /api/partners/campaigns {title, video_ids[1..5], cpm_cents, budget_cents, min_views?, max_per_clip_cents?, max_per_clipper_cents?, max_submissions?, platforms? [tiktok,youtube,instagram], rules? {hashtags[], mention, min_s, max_s}, goal?, brief?, ends_at?, license_accepted:true} → draft. POST …/{id}/status {status: open|paused|ended|closed} (open = publish; budget funding is simulated). POST …/{id}/join → {video_ids}: the source is copied into the clipper's Smart Clipper (no download, outside the monthly quota) with the campaign goal, clips are detected. POST …/{id}/submissions {clip_id (a clip of that copy), url (full TikTok/YouTube/Instagram post URL)} → 409 duplicate if that post was already submitted. POST /api/partners/submissions/{id}/review {status approved|rejected|flagged, reason?} (creator/admin). POST /api/partners/submissions/{id}/refresh {views?} (YouTube Data API; views = manual, admin). GET …/{id}/earnings → per clipper estimated/validated/paid/due cents. POST …/{id}/payouts → simulated payouts. MCP: partners_list_campaigns, partners_get_campaign, partners_join_campaign, partners_submit, partners_earnings, partners_accounts, partners_disconnect_account, partners_caption_code, partners_submission_views. Brand space: GET …/{id}/dashboard (spend, views curve, effective CPM, top clips, per-platform, fraud alerts), GET …/{id}/review-queue, GET …/{id}/export.csv, POST …/{id}/cpm {platform, cpm_cents} (history; a decrease never applies to earlier submissions), POST /api/partners/submissions/{id}/decision {action approve|reject|correction, reason_code, note?}, POST …/submissions/{id}/corrected (clipper), GET /api/partners/notifications. Rules: cpm_by_platform, min_by_platform (per-post payout floor), max_by_platform, channel_url, caption, countries, forbidden, assets, min_engagement_bps, online_days, max_posts_per_video. Pending submissions without a decision are auto-approved after 7 days.
Verified views (only these are paid): link accounts with GET /api/partners/accounts (list + connect_url per platform; max 3 per platform; one account = one clipper), browser GET /api/partners/accounts/{youtube|instagram}/connect (OAuth; TikTok = /api/tiktok/connect), DELETE /api/partners/accounts/{id}. GET /api/partners/campaigns/{id}/code → {code} to put in each post caption (YouTube: title or description). A job reads every active submission every ≤ 6 h (YouTube Data API v3 videos.list, TikTok Display API video/query, Instagram Graph insights) until publication + 30 days; payable views = last API reading ≤ publication + 7 days, only if the post is on a linked account of the clipper, carries the code, has the clip duration (±2 s) and the paid-partnership flag when the API exposes it; deleted/private afterwards = withheld. Manual admin readings are shown, never paid. Campaign field cpm_youtube_cents (Shorts count replays) converts YouTube views to the campaign CPM. GET /api/partners/submissions/{id}/views → {checks, problem, published_at, window_ends_at, verified_views, payable_views, snapshots[]}.
Money (closed like the rest): POST /api/partners/campaigns accepts currency eur (default) | usd. POST /api/partners/connect/onboarding {country} → {provider simulated|stripe, account_id, url} (Stripe Connect Express onboarding link, test mode only). GET|PUT /api/partners/tax-profile {legal_name, address, birth_date YYYY-MM-DD, tin, tin_country, iban?, vat_number?} (DAC7, required before any payout; tin/iban returned masked). Admin: POST /api/partners/admin/payouts/run {period? YYYY-MM, currency?} → monthly payouts (one per clipper per month, ≥ 20, 2 transfer fee deducted; held if frozen, no payout account or no tax profile); GET /api/partners/admin/dac7?year= → CSV. POST /api/partners/stripe/webhook (Stripe signature). Every submission gets a background fraud score (alert / freeze / reasoned reject).
A creator opens a campaign on his ready videos; clippers are paid per 1,000 views (cpm_cents) from the budget. GET /api/partners/campaigns?scope=open|mine|joined. POST /api/partners/campaigns {title, video_ids[1..5], cpm_cents, budget_cents, min_views?, max_per_clip_cents?, max_per_clipper_cents?, max_submissions?, platforms? [tiktok,youtube,instagram], rules? {hashtags[], mention, min_s, max_s}, goal?, brief?, ends_at?, license_accepted:true} → draft. POST …/{id}/status {status: open|paused|ended|closed} (open = publish; budget funding is simulated). POST …/{id}/join → {video_ids}: the source is copied into the clipper's Smart Clipper (no download, outside the monthly quota) with the campaign goal, clips are detected. POST …/{id}/submissions {clip_id (a clip of that copy), url (full TikTok/YouTube/Instagram post URL)} → 409 duplicate if that post was already submitted. POST /api/partners/submissions/{id}/review {status approved|rejected|flagged, reason?} (creator/admin). POST /api/partners/submissions/{id}/refresh {views?} (YouTube Data API; views = manual, admin). GET …/{id}/earnings → per clipper estimated/validated/paid/due cents. POST …/{id}/payouts → simulated payouts. MCP: partners_list_campaigns, partners_get_campaign, partners_join_campaign, partners_submit, partners_earnings.
Growth: GET /api/partners/waitlist → {open} (public). POST /api/partners/waitlist {email, role: brand|clipper, consent: true, locale?} (public early-access list, idempotent). GET /api/partners/referrals → referral links (/partenaires?ref=CODE), referrals and simulated bonus (5% of validated payouts for 90 days, capped at $50 per referral, only after a first approved clip). GET|PUT /api/partners/email-prefs {niches[] (opt-in new-campaign alerts; a campaign's niche is rules.niche), weekly}. Status e-mails (welcome, campaign live, clip approved/rejected with reason, payment sent, niche alert, weekly brand summary) are sent automatically.
Clipper kit: GET …/{id}/kit (participant) → clipper kit: unique code, rules as sentences, export format, clips with score, ready caption (hook, imposed phrase + @mention, disclosure alone on its line, hashtags, code), compliance checklist checks[{key,label,ok}], export/TikTok/submission state, all my submissions with estimated cents, timer {joined_at, first_submitted_at, elapsed_s}; TikTok posts published through ClipOnIt are submitted automatically. Campaign rules also accept caption, language, formats[], onscreen_texts[], disclosure, max_hashtags, logo_required, brand, niche, examples[].
Live captions (host of a Live session): WebSocket GET /api/live/captions?lang=fr. Send binary PCM s16le mono 16 kHz frames (0.1 to 1 s); receive JSON ready, partial {text}, final {text, words:[{w,start,end,speaker?}]}, error, done {seconds, cost_usd}; send {"type":"stop"} to flush and close. Pro and Business plans when Live is open; ElevenLabs Scribe v2 Realtime, about $0.39 per audio hour.
POST /api/consent {ads:bool} : choix du bandeau cookies publicitaires (navigateur, /assets/consent.js) ; connecté, mémorisé sur le compte ; 204. Pas d'usage agent.