{ "openapi": "3.1.0", "info": { "title": "ClipOnIt API", "version": "1.0.0", "summary": "Turn long videos into short, subtitled, reframed clips.", "description": "ClipOnIt imports a long video (file upload or public URL), transcribes it, detects the most viral moments as clips, then lets you edit each clip (layout/reframing keyframes, cuts, subtitles, B-roll, music, emojis) and render it as a vertical (9:16) or horizontal (16:9) MP4. It also generates **explainer videos** (vertical, voice-over + pixel-art or low-poly 3D scenes) from a topic, a JSON script or the user's own voice-over: `/api/explainer*`, `/api/agent/produce`, `/api/jobs*` (contract in https://cliponit.app/llms-api.txt). Integration guide with copy-paste examples (curl, JavaScript, Python, MCP clients, webhooks): https://cliponit.app/integrations.\n\n**MCP**: the same features are exposed as 70 tools at `POST https://cliponit.app/mcp` (Streamable HTTP, OAuth 2.1 or the same API key; discovery at `/.well-known/mcp.json`).\n\n**Typical agent flow**: `importVideoUrl` or `uploadVideo` → poll `getVideo` until `status == \"ready\"` → pick a clip (highest `score`) → optionally `autoReframeClip`, `detectSilences` + `updateClipEdit`, `describeClip` → `exportClip` → poll `getExport` until `status == \"done\"` → download `url`.\n\n**Units**: all times are seconds (float). `start_s`/`end_s` of a clip, `cuts`, B-roll and emoji ranges are **absolute seconds in the source video**; keyframe `t` is **relative to the clip start**. Zones and emoji positions are **fractions 0..1** of the source/output frame.\n\n**Auth**: `Authorization: Bearer ck_…` (API key, Starter plan and above, created with `createApiKey`) or the `session` cookie / session token returned by `login`.\n\n**Errors**: every error is `{\"error\": \"message\"}`. `401` missing/invalid credentials, `402` plan quota reached (monthly videos, daily searches on free), `403` feature not in plan (API/MCP, translation, B-roll/music, Premiere XML, demo export on free), `404` resource not yours, `400` validation.", "contact": { "name": "ClipOnIt", "url": "https://cliponit.app" }, "license": { "name": "Proprietary", "url": "https://cliponit.app" } }, "externalDocs": { "description": "Agent guide (llms-api.txt)", "url": "https://cliponit.app/llms-api.txt" }, "servers": [ { "url": "https://cliponit.app", "description": "Production" }, { "url": "http://localhost:3000", "description": "Local dev (cargo run)" } ], "security": [ { "ApiKey": [] }, { "SessionCookie": [] }, { "OAuth2": [ "clips" ] } ], "tags": [ { "name": "auth", "description": "Register, login, current user, password reset, Google OAuth." }, { "name": "account", "description": "Onboarding, profile, API key, custom logo, feedback." }, { "name": "videos", "description": "Import videos (file or URL), processing status, detected clips." }, { "name": "clips", "description": "Edit state per orientation (layout, keyframes, cuts, subtitles, B-roll, music, emojis), transcript, exports." }, { "name": "smart", "description": "AI/vision helpers: auto-reframe on faces, silences, auto-zoom, descriptions, B-roll and emoji suggestions." }, { "name": "enrich", "description": "B-roll (Pexels/upload) and music library. Starter plan and above." }, { "name": "billing", "description": "Plans catalogue, Stripe checkout/portal, subscription, invoices." }, { "name": "explainer", "description": "Fully generated vertical explainer videos (voice-over, subtitles, pixel-art scenes) from a JSON script that references catalogue elements by name. Contract: docs/explainer.md." }, { "name": "agents", "description": "Autonomous production: one call composes, checks and renders a video; jobs, live progress, templates." }, { "name": "tiktok", "description": "Connexion, publication consentie, programmation et statistiques TikTok. Session utilisateur uniquement ; aucun outil MCP." }, { "name": "live", "description": "ClipOnIt Live : podcast en direct (hôte + invités par lien + sources OBS/RTMP), enregistrement par morceaux, marqueurs, manifeste post-live." }, { "name": "agent-tools", "description": "Composable creation tools and server-run execution plans (docs/outils-creation.md)." }, { "name": "montage", "description": "Montage by reference / house formats" } ], "paths": { "/api/consent": { "post": { "tags": [ "consent" ], "operationId": "setAdsConsent", "summary": "Choix du bandeau cookies publicitaires", "description": "Appelé par /assets/consent.js à chaque choix. Connecté : mémorise le choix sur le compte (événement ads_consent) ; anonyme : sans effet. Les conversions publicitaires serveur (inscription, 1re vidéo, abonnement) ne partent que si le dernier choix est accordé. Voir README « Pixels publicitaires ».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ads" ], "properties": { "ads": { "type": "boolean" } } } } } }, "responses": { "204": { "description": "Enregistré (ou ignoré si non connecté)" } } } }, "/api/auth/register": { "post": { "tags": [ "auth" ], "operationId": "register", "security": [], "summary": "Create an account", "description": "Creates a user (free plan), opens a 30-day session and seeds a demo video. Returns the session token (also set as the `session` cookie).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "name", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "password": { "type": "string", "minLength": 8 } } }, "example": { "email": "a@b.c", "name": "Ana", "password": "secret12" } } } }, "responses": { "200": { "$ref": "#/components/responses/Session" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/auth/login": { "post": { "tags": [ "auth" ], "operationId": "login", "security": [], "summary": "Log in with email and password", "description": "Returns `{user, token}`; use `token` as `Authorization: Bearer ` (session, 30 days). Accounts created with Google OAuth get 400 « Connecte-toi avec Google ».", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Session" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/auth/logout": { "post": { "tags": [ "auth" ], "operationId": "logout", "summary": "Log out (delete the session)", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/api/auth/providers": { "get": { "tags": [ "auth" ], "operationId": "getAuthProviders", "security": [], "summary": "Which OAuth providers are configured", "responses": { "200": { "description": "Providers", "content": { "application/json": { "schema": { "type": "object", "properties": { "google": { "type": "boolean" } } } } } } } } }, "/api/auth/google": { "get": { "tags": [ "auth" ], "operationId": "googleAuthStart", "security": [], "summary": "Start Google OAuth (browser only)", "description": "302 to Google's consent screen. Not usable by agents; use an API key instead.", "responses": { "302": { "description": "Redirect to Google" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/auth/google/callback": { "get": { "tags": [ "auth" ], "operationId": "googleAuthCallback", "security": [], "summary": "Google OAuth callback (browser only)", "parameters": [ { "name": "code", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to `/` or `/onboarding` with the session cookie, or `/login?error=google`" } } } }, "/api/auth/forgot": { "post": { "tags": [ "auth" ], "operationId": "forgotPassword", "security": [], "summary": "Send a password reset email", "description": "Always returns `{ok:true}` (does not reveal whether the email exists). Link valid 1 hour.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/api/auth/reset": { "post": { "tags": [ "auth" ], "operationId": "resetPassword", "security": [], "summary": "Set a new password from a reset token", "description": "Invalidates all sessions of the user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "password" ], "properties": { "token": { "type": "string" }, "password": { "type": "string", "minLength": 8 } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/me": { "get": { "tags": [ "auth" ], "operationId": "getMe", "summary": "Current user and quota", "description": "Call this first to know the plan and remaining quota (`quota.videos_used` vs `quota.videos_limit`) and which features are unlocked (`api_mcp`, `translate`, `broll_music`, `premiere_xml`…).", "responses": { "200": { "description": "User + quota", "content": { "application/json": { "schema": { "type": "object", "required": [ "user", "quota" ], "properties": { "user": { "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "properties": { "delete_after": { "type": [ "string", "null" ], "description": "Scheduled account deletion date, null if none" }, "notify_ready": { "type": "boolean", "description": "E-mail when a video finishes processing (settable with PATCH /api/me)" }, "live": { "type": "boolean", "description": "Live studio open for this account (admins, or LIVE_ENABLED and a paid plan)" } } } ] }, "quota": { "$ref": "#/components/schemas/Quota" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "tags": [ "account" ], "operationId": "updateMe", "summary": "Update profile (name, locale, e-mail notifications)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "locale": { "type": "string", "description": "UI locale, e.g. `fr` or `en`" }, "notify_ready": { "type": "boolean", "description": "E-mail me when a video finishes processing (clips ready, or processing failed). Default true." } } } } } }, "responses": { "200": { "description": "Updated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/onboarding": { "post": { "tags": [ "account" ], "operationId": "completeOnboarding", "summary": "Save onboarding answers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role", "videos_per_month", "source" ], "properties": { "role": { "type": "string" }, "role_other": { "type": "string" }, "videos_per_month": { "type": "string" }, "source": { "type": "string" } } } } } }, "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "onboarded": { "type": "integer", "const": 1 } } } } } } } } }, "/api/onboarding/skip": { "post": { "tags": [ "account" ], "operationId": "skipOnboarding", "summary": "Skip onboarding", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/api/feedback": { "post": { "tags": [ "account" ], "operationId": "sendFeedback", "summary": "Rate the clips detected for a video", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "video_id", "rating" ], "properties": { "video_id": { "$ref": "#/components/schemas/Uuid" }, "rating": { "type": "integer", "enum": [ 1, 2, 3 ], "description": "1 = bad, 2 = ok, 3 = great" } } } } } }, "responses": { "200": { "description": "Stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "rating": { "type": "integer" } } } } } } } } }, "/api/me/api-key": { "get": { "tags": [ "account" ], "operationId": "getApiKey", "summary": "Whether an API key exists (prefix only)", "responses": { "200": { "description": "Key status", "content": { "application/json": { "schema": { "type": "object", "properties": { "has_key": { "type": "boolean" }, "prefix": { "type": [ "string", "null" ], "example": "ck_ab12…" } } } } } } } }, "post": { "tags": [ "account" ], "operationId": "createApiKey", "summary": "Create (or regenerate) the API key", "description": "Returns the full key **once** (`ck_` + 64 hex). Use it as `Authorization: Bearer ck_…` on every `/api/*` route and on `POST /mcp`. Requires a plan with `api_mcp` (Starter and above) → 403 otherwise. Regenerating revokes the previous key.", "responses": { "200": { "description": "New key", "content": { "application/json": { "schema": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "pattern": "^ck_[0-9a-f]{64}$" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "account" ], "operationId": "deleteApiKey", "summary": "Revoke the API key", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/api/me/subtitle-preset": { "get": { "tags": [ "account" ], "operationId": "getSubtitlePreset", "summary": "Account subtitle preset (built-in defaults if none)", "responses": { "200": { "description": "Preset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subtitles" } } } } } }, "put": { "tags": [ "account" ], "operationId": "setSubtitlePreset", "summary": "Set the subtitle preset applied to every new clip edit", "description": "Fields are merged over the built-in defaults (`{}` resets), validated like `updateClipEdit`, then stored. Applied when a `clip_edits` row is created (first `getClip`/`updateClipEdit`/export of a clip+orientation); existing edits are not changed. Same plan gating as `updateClipEdit` for `lang`/`overrides`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubtitlesPatch" }, "example": { "style": "karaoke", "color": "yellow", "size": 3, "words_per_line": 3 } } } }, "responses": { "200": { "description": "Stored preset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subtitles" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/me/logo": { "get": { "tags": [ "account" ], "operationId": "getLogo", "summary": "Custom logo URL (replaces the watermark on exports)", "responses": { "200": { "description": "Logo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Logo" } } } } } }, "post": { "tags": [ "account" ], "operationId": "uploadLogo", "summary": "Upload a logo (png/jpg ≤ 2 MB)", "description": "Converted to PNG ≤ 400 px wide. Rendered bottom-right of exports instead of the watermark (Starter plan and above).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Logo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Logo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "account" ], "operationId": "deleteLogo", "summary": "Remove the logo", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } }, "/api/videos": { "get": { "tags": [ "videos" ], "operationId": "listVideos", "summary": "List my videos (newest first)", "description": "Each item includes `status`, `progress`, `duration_s`, `clips_count`. Poll this or `getVideo` every ~10 s while `status == \"processing\"`.", "responses": { "200": { "description": "Videos", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "videos" ], "operationId": "uploadVideo", "summary": "Upload a video file (multipart)", "description": "Field `file`: mp4/mov/webm, streamed to disk, ≤ `quota.max_bytes` of the plan (3 GB free … 20 GB pro). Checks **before** receiving the body: 402 if the monthly video quota is reached or `Content-Length` exceeds the plan; free plan also refuses videos longer than 1200 s (20 min). Returns the video with `status: processing`; processing = probing → transcribing → detecting, usually 1-5 min for a 20 min video. Then call `getVideo` to read the clips. The plan byte limit is also checked before writing each received chunk, including requests without Content-Length. Video insertion, quota check and job enqueue commit atomically; a queue failure leaves no new video or consumed quota. Optional text fields `goal`, `brief`, `resources` (JSON) set the clip objective (see `setVideoObjective`).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "goal": { "type": "string", "enum": [ "views", "clients", "comments", "followers" ] }, "brief": { "type": "string", "maxLength": 1000 }, "resources": { "type": "string", "description": "JSON array of Resource, e.g. [{\"kind\":\"site\",\"url\":\"https://…\"}]" } } } } } }, "responses": { "200": { "description": "Created video (processing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/videos/url": { "post": { "tags": [ "videos" ], "operationId": "importVideoUrl", "summary": "Import a video from a public URL (YouTube, etc.)", "description": "Downloads with yt-dlp (≤ 1080p). Same quota checks as upload (402). Returns the video immediately with `status: processing`, `progress: downloading`, `title` = the URL until metadata is known. Duration/size limits are enforced after download: the video becomes `failed` with a clear `error`. Poll `getVideo` until `status` is `ready` or `failed`. URLs with credentials, local hostnames or literal private/reserved IPs are rejected. Downloads have a one-hour deadline, a 30-second socket timeout and partial-file size monitoring. Initial URL validation does not replace egress protection against redirects or DNS rebinding. Video insertion, quota check and job enqueue commit atomically. Optional `goal`, `brief`, `resources`: the clip objective (see `setVideoObjective`), stored with the video in the same transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "example": "https://www.youtube.com/watch?v=e7Zl5VWejQc" }, "goal": { "type": [ "string", "null" ], "enum": [ "views", "clients", "comments", "followers", null ], "description": "What the clips are for. Changes the moments picked, the score (sub-score `goal_fit`, 30 % of the score), the titles, and adds a caption CTA per clip (`cta`)." }, "brief": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Free text: what you want" }, "resources": { "type": [ "array", "null" ], "maxItems": 5, "items": { "$ref": "#/components/schemas/Resource" } } } } } } }, "responses": { "200": { "description": "Created video (processing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/videos/{id}": { "parameters": [ { "$ref": "#/components/parameters/VideoId" } ], "get": { "tags": [ "videos" ], "operationId": "getVideo", "summary": "Video with its detected clips", "description": "`state` (queued|running|ready|failed), `queue_position` and `eta_s` tell how long to wait (poll every ~10 s, or use the MCP `wait_video` tool). Clips are sorted chronologically (`position`). Pick by `score` (0-100, estimated viral potential) and read `reason`. `description`/`hashtags` are null until `describeClip` is called. `thumbnail_url` may be null while thumbnails are generated.", "responses": { "200": { "description": "Video + clips", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoDetail" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "videos" ], "operationId": "deleteVideo", "summary": "Delete a video, its clips, exports and B-roll files", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/videos/{id}/export-all": { "parameters": [ { "$ref": "#/components/parameters/VideoId" }, { "$ref": "#/components/parameters/Orientation" } ], "post": { "tags": [ "clips" ], "operationId": "exportAllClips", "summary": "Render every clip of a video (one export per clip)", "description": "Same rules as `exportClip` for each clip, in chronological order; untouched clips get the account subtitle preset. Exports render one at a time: poll `getExport` on each id. 400 if the video has no clips yet.", "responses": { "200": { "description": "Created exports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "parameters": [ { "name": "tics", "in": "query", "schema": { "type": "string", "enum": [ "light", "normal", "aggressive" ] }, "description": "Remove ums, hesitations, repeats and dead air just before rendering (same as `/tics?apply=true`; manual cuts kept). A detection failure does not fail the export." }, { "name": "style", "in": "query", "schema": { "type": "string", "enum": [ "standard", "premium" ], "default": "standard" }, "description": "`standard` (default) = the edit as is. `premium` (paid plans, 403 on free) = edited for the scroll at render time, the stored edit is untouched: white hook card on the first 3 s quoting a 3-8 word phrase actually said in the clip (verified word for word, else the clip title), lead-in and tail trimmed to the speech, dark clips brightened, big uppercase captions of up to 3 words with keywords (picked by the model among the clip's words) as the only yellow accent, no caption when nobody speaks, ums and silences cut (`tics=normal`), illustration shots from the video (`/broll/illustrate`), light punch-ins on keywords (one every 5 s at most, single-zone layouts), audio normalized to -14 LUFS. Any premium step that fails is skipped, never the export." }, { "name": "montage", "in": "query", "schema": { "type": "string", "enum": [ "auto", "entrepreneur", "podcasteur", "formateur", "ecole", "marque" ] }, "description": "Montage pro (paid plans; 404 while the feature is not open to the account, see GET /api/montage). Forces the Premium render, then edits it like an ad by recipe: cold open on the strongest verified line, TikTok loop with rewind, musical beat (a wordless moment of the source chosen by loudness/motion), interlude shot from the video's shot index, boxed title, rhythm (ums/silences cut). `auto` = recipe and options read from `brief`. The export gains `montage` (request) and `montage_report` (what was applied or skipped, hook check score 0-3, ms)." }, { "name": "brief", "in": "query", "schema": { "type": "string", "maxLength": 300 }, "description": "With montage=auto: the request in plain words (« façon pub avec une boucle »)." }, { "name": "cold_open", "in": "query", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] }, "description": "Montage pro: force `cold_open` on/off (default: the recipe's)." }, { "name": "loop", "in": "query", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] }, "description": "Montage pro: force `loop` on/off (default: the recipe's)." }, { "name": "moment", "in": "query", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] }, "description": "Montage pro: force `moment` on/off (default: the recipe's)." }, { "name": "intermede", "in": "query", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] }, "description": "Montage pro: force `intermede` on/off (default: the recipe's)." }, { "name": "title", "in": "query", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] }, "description": "Montage pro: force `title` on/off (default: the recipe's)." }, { "name": "n", "in": "query", "schema": { "type": "string", "pattern": "^[0-9]+$" }, "description": "1..20: only the n best clips (score), e.g. « make me 3 shorts edited like ads » with `montage`." }, { "name": "music", "in": "query", "schema": { "type": "string", "enum": [ "1", "0" ] }, "description": "`0` = « Sans musique »: no music added by ClipOnIt in this render (the edit's music bed, the Montage pro library track); the clip's own sound and voice are kept and the loudness target is unchanged. Meant for posting first, then picking a trending licensed sound inside TikTok / Instagram. Remembered with the clip edit (`no_music`, per orientation) for later renders; `1` puts the music back; absent = unchanged." } ] } }, "/api/videos/{id}/retry": { "post": { "tags": [ "videos" ], "operationId": "retryVideo", "summary": "Re-run processing of a failed video", "description": "Only for `status: failed` (400 otherwise). Re-downloads if the source came from a URL and the file is gone. 402 if the user is above quota.", "parameters": [ { "$ref": "#/components/parameters/VideoId" } ], "responses": { "200": { "description": "Video (processing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/videos/{id}/regenerate": { "post": { "tags": [ "videos" ], "operationId": "regenerateClips", "summary": "Delete the clips and re-run clip detection", "description": "Reuses the existing transcript and queues detection atomically with the status change. Existing clips, edits and files remain available until the new detection replaces them successfully in one transaction. Concurrent requeues cannot create duplicate active jobs. 400 when already processing; 402 when above the plan quota.", "parameters": [ { "$ref": "#/components/parameters/VideoId" } ], "responses": { "200": { "description": "Video (processing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/videos/{id}/search": { "post": { "tags": [ "smart" ], "operationId": "findMoment", "summary": "Find a moment from a natural-language query (creates a clip)", "description": "AI search over the transcript; creates a new clip appended to the list and returns it. Requires a transcript (video `ready`). Free plan: 5 searches/day → 402 beyond.", "parameters": [ { "$ref": "#/components/parameters/VideoId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "example": "the part about pricing" } } } } } }, "responses": { "200": { "description": "New clip", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Clip" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/videos/{id}/clips/{clip_id}/description": { "post": { "tags": [ "smart" ], "operationId": "describeClip", "summary": "Generate a ready-to-post description and hashtags for a clip", "description": "2-3 sentences with a hook on the first line, in the transcript language, plus 5-8 hashtags without `#`. Cached on the clip: a second call returns the same result without AI.", "parameters": [ { "$ref": "#/components/parameters/VideoId" }, { "name": "clip_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "responses": { "200": { "description": "Description", "content": { "application/json": { "schema": { "type": "object", "required": [ "description", "hashtags" ], "properties": { "description": { "type": "string" }, "hashtags": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/videos/{id}/filmstrip": { "get": { "tags": [ "videos" ], "operationId": "getVideoFilmstrip", "summary": "Thumbnail sheet of the whole video (timeline)", "description": "One JPEG with ~120 frames tiled in `cols` columns. Frame n is at column `n % cols`, row `n / cols`, time `n * interval_s`. 400 while the duration is unknown.", "parameters": [ { "$ref": "#/components/parameters/VideoId" } ], "responses": { "200": { "description": "Filmstrip", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Filmstrip" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/videos/{id}/clips.csv": { "get": { "tags": [ "videos" ], "operationId": "exportClipsCsv", "summary": "Clips list as CSV", "description": "Columns: position,title,start,end,duration_s (start/end as m:ss).", "parameters": [ { "$ref": "#/components/parameters/VideoId" } ], "responses": { "200": { "description": "CSV file", "content": { "text/csv": { "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/clips/{id}": { "parameters": [ { "$ref": "#/components/parameters/ClipId" } ], "get": { "tags": [ "clips" ], "operationId": "getClip", "summary": "Clip, its video and the edit state for an orientation", "description": "Creates the default edit for the orientation if missing (layout = orientation, one full-frame keyframe, subtitles = account preset). `updateClipEdit` is a partial patch, so reading first is optional.", "parameters": [ { "$ref": "#/components/parameters/Orientation" } ], "responses": { "200": { "description": "Clip + video + edit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipDetail" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "clips" ], "operationId": "updateClipBounds", "summary": "Rename the clip and/or move its bounds (start_s / end_s)", "description": "`title` is cleaned (first line, 80 chars max) and must not be empty. Bounds: absolute seconds within the video, duration ≥ 3 s; keyframes are shifted, cuts/B-roll/emojis outside the new range are dropped, the clip filmstrip is invalidated. Unknown fields are rejected (400).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start_s": { "type": "number", "minimum": 0 }, "end_s": { "type": "number" }, "title": { "type": "string" } }, "additionalProperties": false }, "example": { "start_s": 120.5, "end_s": 165 } } } }, "responses": { "200": { "description": "Updated clip", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipBase" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "clips" ], "operationId": "deleteClip", "summary": "Delete a clip (edits, exports, files); running exports are canceled", "responses": { "200": { "$ref": "#/components/responses/Ok" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/clips/{id}/edit": { "put": { "tags": [ "clips" ], "operationId": "updateClipEdit", "summary": "Patch the edit state for an orientation", "description": "Partial update: only the given fields change (`subtitles` merged field by field, lists replaced, `music: null` = removed); the edit row is created with the account subtitle preset if missing. Plan gating (403): `subtitles.overrides` non-empty needs `edit_captions`; `subtitles.lang != \"original\"` needs `translate`; non-empty `broll`/`music` needs `broll_music`. Validation (400, the message names the field): zones inside 0..1, keyframe zone count must match the layout (vertical/spotlight/centered 1, split 2, trio 3, horizontal 0), cuts `end > start`, B-roll/emojis inside the clip bounds. Returns the full stored edit. B-roll id/path pairs must be registered for this clip and account, independently of the active edit list. Removed segments can be restored by Undo or another orientation. Client-supplied paths alone are not proof of ownership; render validates the same registry.", "parameters": [ { "$ref": "#/components/parameters/ClipId" }, { "$ref": "#/components/parameters/Orientation" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditInput" } } } }, "responses": { "200": { "description": "Stored edit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edit" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/clips/{id}/export": { "post": { "tags": [ "clips" ], "operationId": "exportClip", "summary": "Render the clip (MP4) with its current edit", "description": "The edit row is created with the account subtitle preset if the clip was never edited; the export carries `eta_s`. Enqueues a render job and returns the export with `status: queued`. Poll `getExport` every ~5 s until `done` (then `url`) or `failed` (`error`). A 60 s clip renders in ~30-90 s. 403 on the free plan for the demo video. Required subtitle/watermark filters missing from FFmpeg cause an explicit failed export. Overlapping cuts are merged when computing duration and progress. At most 512 retained audio ranges are allowed after merging cuts; a larger fragmented edit fails explicitly before FFmpeg starts. Export creation and render-job enqueue commit atomically.", "parameters": [ { "$ref": "#/components/parameters/ClipId" }, { "$ref": "#/components/parameters/Orientation" }, { "name": "tics", "in": "query", "schema": { "type": "string", "enum": [ "light", "normal", "aggressive" ] }, "description": "Remove ums, hesitations, repeats and dead air just before rendering (same as `/tics?apply=true`; manual cuts kept). A detection failure does not fail the export." }, { "name": "style", "in": "query", "schema": { "type": "string", "enum": [ "standard", "premium" ], "default": "standard" }, "description": "`standard` (default) = the edit as is. `premium` (paid plans, 403 on free) = edited for the scroll at render time, the stored edit is untouched: white hook card on the first 3 s quoting a 3-8 word phrase actually said in the clip (verified word for word, else the clip title), lead-in and tail trimmed to the speech, dark clips brightened, big uppercase captions of up to 3 words with keywords (picked by the model among the clip's words) as the only yellow accent, no caption when nobody speaks, ums and silences cut (`tics=normal`), illustration shots from the video (`/broll/illustrate`), light punch-ins on keywords (one every 5 s at most, single-zone layouts), audio normalized to -14 LUFS. Any premium step that fails is skipped, never the export." }, { "name": "montage", "in": "query", "schema": { "type": "string", "enum": [ "auto", "entrepreneur", "podcasteur", "formateur", "ecole", "marque" ] }, "description": "Montage pro (paid plans; 404 while the feature is not open to the account, see GET /api/montage). Forces the Premium render, then edits it like an ad by recipe: cold open on the strongest verified line, TikTok loop with rewind, musical beat (a wordless moment of the source chosen by loudness/motion), interlude shot from the video's shot index, boxed title, rhythm (ums/silences cut). `auto` = recipe and options read from `brief`. The export gains `montage` (request) and `montage_report` (what was applied or skipped, hook check score 0-3, ms)." }, { "name": "brief", "in": "query", "schema": { "type": "string", "maxLength": 300 }, "description": "With montage=auto: the request in plain words (« façon pub avec une boucle »)." }, { "name": "cold_open", "in": "query", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] }, "description": "Montage pro: force `cold_open` on/off (default: the recipe's)." }, { "name": "loop", "in": "query", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] }, "description": "Montage pro: force `loop` on/off (default: the recipe's)." }, { "name": "moment", "in": "query", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] }, "description": "Montage pro: force `moment` on/off (default: the recipe's)." }, { "name": "intermede", "in": "query", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] }, "description": "Montage pro: force `intermede` on/off (default: the recipe's)." }, { "name": "title", "in": "query", "schema": { "type": "string", "enum": [ "1", "0", "true", "false" ] }, "description": "Montage pro: force `title` on/off (default: the recipe's)." }, { "name": "music", "in": "query", "schema": { "type": "string", "enum": [ "1", "0" ] }, "description": "`0` = « Sans musique »: no music added by ClipOnIt in this render (the edit's music bed, the Montage pro library track); the clip's own sound and voice are kept and the loudness target is unchanged. Meant for posting first, then picking a trending licensed sound inside TikTok / Instagram. Remembered with the clip edit (`no_music`, per orientation) for later renders; `1` puts the music back; absent = unchanged." } ], "responses": { "200": { "description": "Export (queued)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "object", "description": "Edited montage plan from montagePlan, rendered as is" } } } } } } } }, "/api/exports/{id}": { "get": { "tags": [ "clips" ], "operationId": "getExport", "summary": "Export status, progress, eta_s and download URL", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Export id returned by `exportClip`", "schema": { "$ref": "#/components/schemas/Uuid" } } ], "responses": { "200": { "description": "Export", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "clips" ], "operationId": "cancelExport", "summary": "Cancel a queued or running export", "description": "Queued: removed from the render queue. Running: the ffmpeg process is killed within ~2 s and the partial file deleted. Either way the export stays readable with `status: canceled`. 400 if already done/failed/canceled. Cancellation committed before final render publication wins; retries and worker restart do not resurrect canceled exports. If completion commits first, the finished export remains available.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Export id returned by `exportClip`", "schema": { "$ref": "#/components/schemas/Uuid" } } ], "responses": { "200": { "description": "Canceled export", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/exports/{id}/frame": { "get": { "tags": [ "clips" ], "operationId": "getExportFrame", "summary": "One JPEG frame of a finished export", "description": "Extracts the frame at `t` seconds from the start of the rendered clip (longest side 360 px) so an agent can check framing and subtitles. 400 if the export is not `done` or `t` is past the end.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Export id returned by `exportClip`", "schema": { "$ref": "#/components/schemas/Uuid" } }, { "name": "t", "in": "query", "required": false, "description": "Seconds from the start of the export", "schema": { "type": "number", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "JPEG", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/clips/{id}/transcript": { "get": { "tags": [ "clips" ], "operationId": "getClipTranscript", "summary": "Transcript segments overlapping the clip", "description": "Absolute source seconds. `words` carries word-level timings when available (used for karaoke subtitles).", "parameters": [ { "$ref": "#/components/parameters/ClipId" } ], "responses": { "200": { "description": "Segments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/clips/{id}/filmstrip": { "get": { "tags": [ "clips" ], "operationId": "getClipFilmstrip", "summary": "Dense thumbnail sheet of the clip (~160 frames)", "description": "Frame n is at time `start_s + n * interval_s`. Cached per (clip, bounds).", "parameters": [ { "$ref": "#/components/parameters/ClipId" } ], "responses": { "200": { "description": "Filmstrip", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Filmstrip" }, { "type": "object", "properties": { "start_s": { "type": "number", "description": "Absolute time of frame 0" } } } ] } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/clips/{id}/premiere.xml": { "get": { "tags": [ "clips" ], "operationId": "getPremiereXml", "summary": "Premiere Pro / FCP7 XMEML sequence of the clip", "description": "Source path plus in/out points (cuts become segments). Requires `premiere_xml` in the plan (Pro) → 403 otherwise.", "parameters": [ { "$ref": "#/components/parameters/ClipId" }, { "$ref": "#/components/parameters/Orientation" } ], "responses": { "200": { "description": "XML file", "content": { "application/xml": { "schema": { "type": "string" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/clips/{id}/auto-reframe": { "post": { "tags": [ "smart" ], "operationId": "autoReframeClip", "summary": "Detect faces, active speaker, slides and camera cuts, write layout + keyframes", "description": "Synchronous (~5 s per 30 s of clip in release). The clip is split into segments at camera cuts (ffmpeg scene > 0.3) and at face-less gaps >= 4 s; a shorter gap inside a shot keeps the last zone. Face-less segment -> `spotlight` 1x1 (whole source on blurred background). mode=auto (default, also applied in 9:16 to every clip detected after import): keynote if a slide + a speaker are detected, else speaker_tracking. mode=speaker_tracking: `vertical` on whoever is TALKING (audio speech level x mouth movement at 10 fps), clean cut at the start of each turn, turns < 1.4 s ignored, `split` during rapid exchanges (>= 3 speaker changes in 6 s). mode=keynote_split: layout `keynote` (whole slide on top in 16:9 + speaker below); mode=keynote_speaker: `vertical` on the speaker, slide cropped out; without a detected slide both fall back to speaker_tracking. mode=follow (legacy): `split` while the clip's stable duo is on screen in that segment, otherwise `vertical` following the active speaker. mode=mix (vertical only): 1 face -> `vertical`; 2 -> `split` (left person on top), or `vertical` on someone talking alone >= 4 s; 3 -> `trio`; 4+ -> wide shot. Segment changes are `ease: cut` keyframes on the camera cut; moves inside a segment are `smooth`; a segment < 2 s after a `vertical` stays `vertical` when it has a face. framing: tight (zone >= 40 % of source height), medium (default, face + shoulders, >= 55 %), wide (full source height); face centre at ~38 % from the top of the zone. Overwrites `layout` and `keyframes` of the edit for this orientation. square (1:1) and portrait45 (4:5) get the same plan as vertical, zones cut at their own cell ratio; horizontal = full frame. Results are cached per clip bounds. 400 on unknown mode/framing. 500 if the face model is missing on the server.", "parameters": [ { "$ref": "#/components/parameters/ClipId" }, { "$ref": "#/components/parameters/Orientation" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "speaker_tracking", "keynote_split", "keynote_speaker", "follow", "mix" ], "default": "auto" }, "description": "auto = keynote if slides detected else speaker_tracking; speaker_tracking = frame whoever talks; keynote_split = slide on top + speaker; keynote_speaker = speaker only; follow = legacy; mix = mixed auto layout shot by shot (vertical only)" }, { "name": "framing", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tight", "medium", "wide" ], "default": "medium" }, "description": "Crop closeness; zoom is capped to avoid grain" } ], "responses": { "200": { "description": "Reframe result", "content": { "application/json": { "schema": { "type": "object", "required": [ "layout", "keyframes", "faces", "speakers" ], "properties": { "layout": { "$ref": "#/components/schemas/Layout" }, "keyframes": { "type": "array", "items": { "$ref": "#/components/schemas/Keyframe" } }, "faces": { "type": "integer", "description": "Number of face tracks found" }, "speakers": { "type": "integer", "description": "Number of stable speakers" }, "shots": { "type": "integer", "description": "Number of camera shots detected in the clip" }, "mode": { "type": "string", "description": "mode actually applied" }, "slides": { "type": "boolean", "description": "a presentation slide + speaker was detected" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/clips/{id}/faces": { "get": { "tags": [ "smart" ], "operationId": "getClipFaces", "summary": "Face tracks of the clip", "description": "Boxes as `[t, x, y, w, h]` (t relative to the clip, x/y/w/h fractions 0..1 of the source); `activity` as `[t, v]` (mouth-motion variance, higher = speaking).", "parameters": [ { "$ref": "#/components/parameters/ClipId" } ], "responses": { "200": { "description": "Tracks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FaceTrack" } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/clips/{id}/silences": { "post": { "tags": [ "smart" ], "operationId": "detectSilences", "summary": "Detect silences (returns cuts, does not apply them)", "description": "Audio energy on the clip (150 Hz high-pass, 10 ms frames). Without `threshold_db` the threshold adapts to the background noise (noise floor + max(6 dB, 30 % of the floor-to-speech range)), so it also works in a car or a street. Each silence trimmed by 80 ms on both sides, those shorter than `min_ms` dropped. Returns `{cuts, threshold_db}` in absolute source seconds — merge them into `cuts` of `updateClipEdit` to apply.", "parameters": [ { "$ref": "#/components/parameters/ClipId" }, { "name": "min_ms", "in": "query", "schema": { "type": "integer", "default": 400, "minimum": 0 }, "description": "Minimum silence length (ms) after trimming" }, { "name": "threshold_db", "in": "query", "schema": { "type": "number" }, "description": "Fixed level under which audio counts as silence (dBFS). Omit for the adaptive threshold." } ], "responses": { "200": { "description": "Silences", "content": { "application/json": { "schema": { "type": "object", "required": [ "cuts" ], "properties": { "cuts": { "type": "array", "items": { "$ref": "#/components/schemas/Cut" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/clips/{id}/auto-zoom": { "post": { "tags": [ "smart" ], "operationId": "autoZoomClip", "summary": "Add punch-in zoom keyframes at sentence starts (saved)", "description": "Alternates current framing / punch-in (zone shrunk by `strength` around the same centre) on every `every`-th sentence start. Single-zone layouts only (vertical, spotlight, centered) → 400 for split/trio/horizontal. Writes `keyframes` of the edit.", "parameters": [ { "$ref": "#/components/parameters/ClipId" }, { "$ref": "#/components/parameters/Orientation" }, { "name": "strength", "in": "query", "schema": { "type": "number", "default": 0.15, "minimum": 0, "maximum": 1 }, "description": "Zoom amount as a fraction of the zone (0.15 = 15 % tighter)" }, { "name": "every", "in": "query", "schema": { "type": "integer", "default": 2, "minimum": 1 }, "description": "Zoom on every Nth sentence" } ], "responses": { "200": { "description": "Keyframes written", "content": { "application/json": { "schema": { "type": "object", "required": [ "keyframes" ], "properties": { "keyframes": { "type": "array", "items": { "$ref": "#/components/schemas/Keyframe" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/broll/search": { "get": { "tags": [ "enrich" ], "operationId": "searchBroll", "summary": "Search stock B-roll videos (Pexels)", "description": "12 results, portrait for `vertical`, landscape for `horizontal`. Pass `pexels_id` (or `video_url`) to `addBroll`. Starter plan and above (403).", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "city skyline night" }, { "$ref": "#/components/parameters/Orientation" } ], "responses": { "200": { "description": "Results", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BrollResult" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/clips/{id}/broll/suggest": { "post": { "tags": [ "smart" ], "operationId": "suggestBroll", "summary": "AI suggestions of B-roll moments for the clip", "description": "≤ 3 moments `{start, end, query}` (2-5 s each, absolute seconds, English 2-4 word query). Nothing is applied: call `searchBroll` then `addBroll`.", "parameters": [ { "$ref": "#/components/parameters/ClipId" } ], "responses": { "200": { "description": "Suggestions", "content": { "application/json": { "schema": { "type": "object", "required": [ "suggestions" ], "properties": { "suggestions": { "type": "array", "items": { "type": "object", "required": [ "start", "end", "query" ], "properties": { "start": { "type": "number" }, "end": { "type": "number" }, "query": { "type": "string" } } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/clips/{id}/broll": { "post": { "tags": [ "enrich" ], "operationId": "addBroll", "summary": "Add a B-roll segment (Pexels id or https URL)", "description": "Downloads the clip to the server (`-an`, short side 720) and appends it to `edit.broll` of the orientation. `start`/`end` absolute seconds inside the clip. Returns the full B-roll list.", "parameters": [ { "$ref": "#/components/parameters/ClipId" }, { "$ref": "#/components/parameters/Orientation" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "number" }, "end": { "type": "number" }, "pexels_id": { "type": "integer" }, "video_url": { "type": "string", "format": "uri", "description": "https only; alternative to `pexels_id`" }, "query": { "type": "string", "description": "Search query to remember (informational)" } } } } } }, "responses": { "200": { "description": "B-roll list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Broll" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/clips/{id}/broll/upload": { "post": { "tags": [ "enrich" ], "operationId": "uploadBroll", "summary": "Upload your own B-roll file (≤ 200 MB)", "parameters": [ { "$ref": "#/components/parameters/ClipId" }, { "$ref": "#/components/parameters/Orientation" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "start", "end" ], "properties": { "file": { "type": "string", "format": "binary" }, "start": { "type": "number" }, "end": { "type": "number" } } } } } }, "responses": { "200": { "description": "B-roll list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Broll" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/clips/{id}/broll/{broll_id}": { "delete": { "tags": [ "enrich" ], "operationId": "deleteBroll", "summary": "Remove a B-roll segment from the edit", "parameters": [ { "$ref": "#/components/parameters/ClipId" }, { "name": "broll_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Orientation" } ], "responses": { "200": { "description": "B-roll list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Broll" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Detaches the segment from the requested orientation. The source and ownership record remain available for Undo and other orientations, until clip/video/account deletion or retention. A file shared between clips of the same account is removed after its last reference." } }, "/api/clips/{id}/emojis/suggest": { "post": { "tags": [ "smart" ], "operationId": "suggestEmojis", "summary": "AI emoji reactions for the clip (not applied)", "description": "≤ 1 emoji per ~6 s, 1.5-2.5 s each, absolute seconds. Add `x`, `y`, `size` and pass them as `emojis` to `updateClipEdit`.", "parameters": [ { "$ref": "#/components/parameters/ClipId" } ], "responses": { "200": { "description": "Suggestions", "content": { "application/json": { "schema": { "type": "object", "required": [ "emojis" ], "properties": { "emojis": { "type": "array", "items": { "type": "object", "required": [ "start", "end", "emoji" ], "properties": { "start": { "type": "number" }, "end": { "type": "number" }, "emoji": { "type": "string" } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/music": { "get": { "tags": [ "enrich" ], "operationId": "listMusic", "summary": "My music library", "responses": { "200": { "description": "Tracks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MusicTrack" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "enrich" ], "operationId": "uploadMusic", "summary": "Upload a music track (mp3/wav/m4a ≤ 20 MB)", "description": "Stored as mp3. Use the returned `id` as `music.music_id` in `updateClipEdit`.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Track", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MusicTrack" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/music/{id}": { "delete": { "tags": [ "enrich" ], "operationId": "deleteMusic", "summary": "Delete a music track", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/Ok" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/billing/plans": { "get": { "tags": [ "billing" ], "operationId": "listPlans", "security": [], "summary": "Plans catalogue with limits and prices (USD)", "responses": { "200": { "description": "Plans", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } } } } } } } }, "/api/billing/checkout": { "post": { "tags": [ "billing" ], "operationId": "createCheckout", "summary": "Stripe Checkout URL for a plan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plan", "interval" ], "properties": { "plan": { "type": "string", "enum": [ "starter", "pro", "business" ] }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Url" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/billing/subscription": { "get": { "tags": [ "billing" ], "operationId": "getSubscription", "summary": "Current subscription", "responses": { "200": { "description": "Subscription", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "$ref": "#/components/schemas/PlanId" }, "interval": { "type": [ "string", "null" ], "enum": [ "monthly", "yearly", null ] }, "status": { "type": [ "string", "null" ], "description": "Stripe status (active, past_due, canceled…)" }, "current_period_end": { "type": [ "string", "null" ] }, "cancel_at_period_end": { "type": "boolean" } } } } } } } } }, "/api/billing/invoices": { "get": { "tags": [ "billing" ], "operationId": "listInvoices", "summary": "Stripe invoices of the customer", "responses": { "200": { "description": "Invoices", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string" }, "amount_cents": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string" }, "pdf_url": { "type": [ "string", "null" ] }, "hosted_url": { "type": [ "string", "null" ] } } } } } } } } } }, "/api/billing/portal": { "post": { "tags": [ "billing" ], "operationId": "createBillingPortal", "summary": "Stripe customer portal URL", "responses": { "200": { "$ref": "#/components/responses/Url" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/billing/webhook": { "post": { "tags": [ "billing" ], "operationId": "stripeWebhook", "security": [], "summary": "Stripe webhook (server-to-server, not for agents)", "description": "Signed with `Stripe-Signature`. Handles `checkout.session.completed`, `customer.subscription.*`, `invoice.paid`.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Acknowledged", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/me/usage": { "get": { "tags": [ "Account" ], "summary": "AI usage & cost of the account", "description": "One row per (kind, model) over the last `days` days: calls, tokens, audio seconds and estimated USD cost (Claude list prices, Whisper 0.006 $/min). `all=1` returns a per-user breakdown and is restricted to the ADMIN_EMAIL account.", "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 } }, { "name": "all", "in": "query", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "integer" }, "total_usd": { "type": "number" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "calls": { "type": "integer" }, "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" }, "seconds": { "type": "number" }, "cost_usd": { "type": "number" } } } } } } } } }, "403": { "description": "`all=1` from a non-admin account" } } } }, "/api/me/affiliate": { "get": { "tags": [ "account" ], "operationId": "getAffiliate", "summary": "Affiliate link and stats of the account (30% for life)", "description": "Creates the `ref_code` on first call. `link` = `PUBLIC_URL/?ref=CODE`; a visitor who signs up (email or Google) within 60 days of clicking it is attributed to this account. Every Stripe `invoice.paid` of a referred user adds a payout of 30% of `amount_paid`. If the affiliate is a Stripe customer the amount is credited to their balance automatically (`credited`, deducted from their next invoices); otherwise it stays `pending` and the founder pays monthly (PayPal/bank transfer) and marks it `paid` via `PATCH /api/admin/payouts/{id}`.", "responses": { "200": { "description": "Affiliate info", "content": { "application/json": { "schema": { "type": "object", "properties": { "ref_code": { "type": "string", "example": "K7QM2XJ4" }, "link": { "type": "string" }, "signups": { "type": "integer" }, "paying": { "type": "integer" }, "pending_cents": { "type": "integer", "description": "cents" }, "paid_cents": { "type": "integer", "description": "cents" }, "rate_percent": { "type": "integer", "example": 30 }, "payouts": { "type": "array", "description": "20 most recent", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "amount_cents": { "type": "integer", "description": "cents" }, "commission_cents": { "type": "integer", "description": "cents" }, "currency": { "type": "string", "example": "usd" }, "status": { "type": "string", "enum": [ "pending", "credited", "paid" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "stripe_balance_txn_id": { "type": [ "string", "null" ] } } } }, "credited_cents": { "type": "integer", "description": "cents" } } } } } } } } }, "/api/admin/payouts": { "get": { "tags": [ "account" ], "operationId": "listPayouts", "summary": "Admin: referral payouts by status (ADMIN_EMAIL only)", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "credited", "paid" ], "default": "pending" } } ], "responses": { "200": { "description": "Payouts, ordered by affiliate email", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "amount_cents": { "type": "integer", "description": "cents" }, "commission_cents": { "type": "integer", "description": "cents" }, "currency": { "type": "string", "example": "usd" }, "status": { "type": "string", "enum": [ "pending", "credited", "paid" ] }, "created_at": { "type": "string" }, "paid_at": { "type": [ "string", "null" ] }, "affiliate_email": { "type": "string" }, "referred_email": { "type": "string" } } } } } } }, "403": { "description": "Not the admin account" } } } }, "/api/admin/payouts/{id}": { "patch": { "tags": [ "account" ], "operationId": "updatePayout", "summary": "Admin: mark a referral payout paid (or back to pending)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "paid", "pending" ] } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" } } } } } }, "403": { "description": "Not the admin account" }, "404": { "description": "Unknown payout" } } } }, "/.well-known/oauth-protected-resource": { "get": { "tags": [ "auth" ], "operationId": "oauthProtectedResourceMetadata", "summary": "OAuth protected resource metadata (RFC 9728) for the MCP server", "description": "Also served at `/.well-known/oauth-protected-resource/mcp`. Referenced by the `WWW-Authenticate: Bearer resource_metadata=\"…\"` header on every 401 from `POST /mcp`.", "security": [], "responses": { "200": { "description": "Metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string", "example": "https://cliponit.app/mcp" }, "authorization_servers": { "type": "array", "items": { "type": "string" }, "example": [ "https://cliponit.app" ] }, "scopes_supported": { "type": "array", "items": { "type": "string" }, "example": [ "clips" ] }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "tags": [ "auth" ], "operationId": "oauthAuthorizationServerMetadata", "summary": "OAuth authorization server metadata (RFC 8414)", "security": [], "responses": { "200": { "description": "Metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "registration_endpoint": { "type": "string" }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "response_types_supported": { "type": "array", "items": { "type": "string" }, "example": [ "code" ] }, "grant_types_supported": { "type": "array", "items": { "type": "string" }, "example": [ "authorization_code", "refresh_token" ] }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" }, "example": [ "S256" ] }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" }, "example": [ "none" ] } } } } } } } } }, "/oauth/register": { "post": { "tags": [ "auth" ], "operationId": "oauthRegisterClient", "summary": "Dynamic client registration (RFC 7591), public clients only", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "redirect_uris" ], "properties": { "client_name": { "type": "string", "example": "Claude" }, "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "https URLs, or http on localhost/127.0.0.1 (port ignored at authorization time).", "example": [ "https://claude.ai/api/mcp/auth_callback" ] }, "token_endpoint_auth_method": { "type": "string", "enum": [ "none" ] } } } } } }, "responses": { "201": { "description": "Registered client", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "format": "uuid" }, "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_method": { "type": "string", "example": "none" }, "grant_types": { "type": "array", "items": { "type": "string" } }, "response_types": { "type": "array", "items": { "type": "string" } }, "client_id_issued_at": { "type": "integer" } } } } } }, "400": { "description": "`invalid_redirect_uri` or `invalid_client_metadata`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_grant" }, "error_description": { "type": "string" } } } } } } } } }, "/oauth/authorize": { "get": { "tags": [ "auth" ], "operationId": "oauthAuthorize", "summary": "Authorization endpoint (code + PKCE S256): consent page, or redirect to /login?next=…", "description": "Browser endpoint. Without a web session → `303 /login?next=/oauth/authorize?…`. With a session → HTML consent page (FR/EN) naming the client and the redirect host. Unknown `client_id` or unregistered `redirect_uri` → 400 page (no redirect). Other errors are returned to `redirect_uri` as `?error=…&state=…` (RFC 6749).", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string", "minLength": 43 } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "S256" ] } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "schema": { "type": "string", "example": "clips" } }, { "name": "resource", "in": "query", "schema": { "type": "string", "example": "https://cliponit.app/mcp" }, "description": "RFC 8707; must be the MCP server URL if present." } ], "responses": { "200": { "description": "Consent page", "content": { "text/html": {} } }, "303": { "description": "Redirect to /login (no session)" }, "400": { "description": "Unknown client or unregistered redirect_uri", "content": { "text/html": {} } } } }, "post": { "tags": [ "auth" ], "operationId": "oauthConsent", "summary": "Consent form submit → `redirect_uri?code=…&state=…` (code: 10 min, single use)", "security": [ { "SessionCookie": [] } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "client_id", "redirect_uri", "code_challenge", "code_challenge_method", "decision" ], "properties": { "response_type": { "type": "string", "enum": [ "code" ] }, "client_id": { "type": "string" }, "redirect_uri": { "type": "string" }, "code_challenge": { "type": "string" }, "code_challenge_method": { "type": "string", "enum": [ "S256" ] }, "state": { "type": "string" }, "scope": { "type": "string" }, "resource": { "type": "string" }, "decision": { "type": "string", "enum": [ "allow", "deny" ], "description": "`deny` → `redirect_uri?error=access_denied&state=…`" } } } } } }, "responses": { "303": { "description": "Redirect to redirect_uri with `code` (or `error`)" }, "401": { "description": "No session" } } } }, "/oauth/token": { "post": { "tags": [ "auth" ], "operationId": "oauthToken", "summary": "Token endpoint: authorization_code + code_verifier, or refresh_token (rotation)", "description": "Form-encoded (RFC 6749). Returns `{access_token:\"cko_…\", token_type:\"Bearer\", expires_in:3600, refresh_token:\"ckr_…\", scope}` with `Cache-Control: no-store`. Codes are single use (consumed even on failure). Refresh tokens rotate: the previous one is invalidated in the same call. Errors: `invalid_request`, `invalid_grant`, `invalid_client` (401), `unsupported_grant_type`.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "code": { "type": "string" }, "code_verifier": { "type": "string" }, "redirect_uri": { "type": "string" }, "client_id": { "type": "string" }, "refresh_token": { "type": "string" }, "resource": { "type": "string" } } } } } }, "responses": { "200": { "description": "Tokens", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "example": "cko_…" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_in": { "type": "integer", "example": 3600 }, "refresh_token": { "type": "string", "example": "ckr_…" }, "scope": { "type": "string", "example": "clips" } } } } } }, "400": { "description": "`invalid_grant` (bad/used/expired code, PKCE mismatch, bad refresh token), `invalid_request`, `unsupported_grant_type`", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_grant" }, "error_description": { "type": "string" } } } } } }, "401": { "description": "`invalid_client` (client_id mismatch)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_grant" }, "error_description": { "type": "string" } } } } } } } } }, "/api/me/oauth": { "get": { "tags": [ "account" ], "operationId": "listOauthGrants", "summary": "Connectors (OAuth clients) authorized on this account", "responses": { "200": { "description": "One row per client with live tokens", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "client_id": { "type": "string" }, "name": { "type": "string", "example": "Claude" }, "since": { "type": "string", "example": "2026-10-03 16:46:51" }, "until": { "type": "string", "description": "Latest refresh-token expiry" } } } } } } } } } }, "/api/me/oauth/{client_id}": { "delete": { "tags": [ "account" ], "operationId": "revokeOauthGrant", "summary": "Revoke a connector: deletes all its tokens and pending codes for this account", "parameters": [ { "name": "client_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "integer", "description": "token rows deleted" } } } } } } } } }, "/api/extension/token": { "post": { "tags": [ "account" ], "operationId": "createExtensionToken", "summary": "Create a Chrome extension token (`cke_…`)", "description": "Returns an opaque token **once** (`cke_` + 64 hex), stored SHA-256 only. **Requires the web `session` cookie**: a Bearer (session token, `ck_…` API key or OAuth `cko_…`) is rejected with 401, so a stolen token cannot mint more. The token replaces the session cookie inside the Chrome extension (`Authorization: Bearer cke_…`) and therefore works on **every plan, free included** — unlike the `ck_…` API key, which unlocks the public API and MCP and needs a paid plan. Sliding expiry: 180 days, pushed back on every authenticated call. Max 5 live tokens per account (the oldest is revoked beyond that); rate-limited to 10/h per account and 30/h per IP.", "security": [ { "SessionCookie": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 60, "description": "Optional name shown in `GET /api/me/extensions`", "example": "Chrome · macOS" } } } } } }, "responses": { "200": { "description": "New token (shown once)", "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "pattern": "^cke_[0-9a-f]{64}$" }, "expires_in_days": { "type": "integer", "example": 180 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Too many tokens created, retry later" } } } }, "/api/me/extensions": { "get": { "tags": [ "account" ], "operationId": "listExtensionTokens", "summary": "Chrome extensions connected to this account", "description": "Live tokens only. The token itself is never returned (only its SHA-256 is stored).", "responses": { "200": { "description": "Connected extensions", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": [ "string", "null" ], "example": "Chrome · macOS" }, "created_at": { "type": "string", "example": "2026-10-16 09:12:00" }, "last_used_at": { "type": [ "string", "null" ], "description": "null until the extension has made one call" }, "expires_at": { "type": "string", "description": "sliding: +180 days on every authenticated call" } } } } } } } } } }, "/api/me/extensions/{id}": { "delete": { "tags": [ "account" ], "operationId": "revokeExtensionToken", "summary": "Revoke one extension token", "description": "Only tokens of the calling account; an unknown id returns `{revoked: 0}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "integer", "description": "rows deleted (0 or 1)" } } } } } } } } }, "/api/explainer/library": { "get": { "tags": [ "explainer" ], "operationId": "getExplainerLibrary", "summary": "Element catalogue", "description": "Catalogue of one style as JSON (`?style=`, default pixel-news), `&compact=1` → `{style, text}` (~2-3k tokens, for an LLM), or `?all=1` → merged catalogue `{styles, families, entries:[{concept, family, style (null when shared), shared, variants:[{style, el, kind (2d|3d), description, params, parts, preview}]}], animations, camera_presets, rule}`: a concept present in several styles is one entry (same family) with one variant per style. A variant identical to the first one (same element redrawn by another style) has `same: