API resource
Clippy (clipper)
Clippy turns long streams and videos into short clips. Find a creator on Twitch, Kick or YouTube (or send your own upload or any video link), pick a stream, and Clippy scans it, picks the best moments, edits each one (9:16 by default: the person talking kept in frame, facecam over gameplay for gaming, captions in your font and colours, a hook title) and scores it with the Virality agent. Fine-tune any clip (trim, layout, crop boxes, design, or plain-English instructions) and post it through Agent Posts, which writes the captions and books the slot. An autopilot watches creators for new streams and posts the clips that clear its virality threshold, within its posts per day and per network. Account ids are acc_, media are /v1/media URLs. Any active plan; up to 3 manual runs in progress at once and 100 runs a month.
Overview
/v1/clipperEverything the clipper page needs in one call: access (can_create, reason: null, plan_required, trial_limit or monthly_limit, runs_this_month; monthly_limit is always null), pinned creators, autopilots, the 20 latest runs (with a clips_summary), and the styles, layouts, networks and designs catalogs.
curl "https://creatoros-production-5658.up.railway.app/v1/clipper" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"access": {
"plan": "active",
"can_create": true,
"reason": null,
"runs_this_month": 4,
"monthly_limit": null
},
"creators": [
{
"id": "0b6f3a1e-2c4d-4e8f-9a1b-7c5d3e2f1a09",
"network": "twitch",
"handle": "kaicenat",
"display_name": "KaiCenat",
"followers": 21987104
}
],
"autopilots": [],
"runs": [],
"styles": [
{
"id": "podcast",
"label": "Podcast / stream"
},
{
"id": "gaming",
"label": "Gaming split screen"
}
],
"networks": [
"twitch",
"kick",
"youtube"
]
}Designs, styles and layouts
/v1/clipper/designsThe caption fonts (ids like montserrat_bold, poppins_black, anton, bebas_neue, bangers, luckiest_guy, permanent_marker, tiktok_sans_bold), the presets (bold_pop, clean, karaoke_box, comic, gamer, neon, headline, marker, each with its full design), the default design, styles, layouts and aspects. A design anywhere in this API is a preset plus any of these overrides: captions, font, size (40 to 140 px on a 1080-wide frame), text_color, highlight_color (the word being spoken), outline_color, outline (0 to 12), shadow, box (a box behind the spoken word), position (top, middle, bottom), uppercase, words_per_line (1 to 6), animation (pop, none), hook, hook_seconds (1 to 10), hook_font, hook_color, hook_background (#RRGGBB or ""), cut_silence, gifs (reaction GIFs on big moments) and fps (30 or 60). Colours are #RRGGBB.
curl "https://creatoros-production-5658.up.railway.app/v1/clipper/designs" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"fonts": [
{
"id": "montserrat_bold",
"name": "Montserrat Bold"
},
{
"id": "luckiest_guy",
"name": "Luckiest Guy"
}
],
"presets": [
{
"id": "gamer",
"label": "Gamer",
"description": "Chunky rounded letters, green highlight. Made for gaming clips.",
"design": {
"preset": "gamer",
"font": "luckiest_guy",
"size": 84,
"highlight_color": "#39FF14",
"words_per_line": 2
}
}
],
"default": {
"preset": "bold_pop",
"captions": true,
"font": "montserrat_bold",
"size": 78,
"text_color": "#FFFFFF",
"highlight_color": "#FFE500",
"outline_color": "#000000",
"outline": 6,
"shadow": true,
"box": false,
"position": "bottom",
"uppercase": true,
"words_per_line": 3,
"animation": "pop",
"hook": true,
"hook_seconds": 3,
"hook_font": "tiktok_sans_bold",
"hook_color": "#000000",
"hook_background": "#FFFFFF",
"cut_silence": true,
"gifs": false,
"fps": 30
},
"layouts": [
{
"id": "speaker",
"label": "Face detect"
},
{
"id": "split",
"label": "Split screen"
}
],
"aspects": [
"9:16",
"4:5",
"1:1",
"16:9"
]
}Find creators
/v1/clipper/searchSearch creators on one network. A pasted channel link goes straight to that creator. If a network is not answering, creators is empty and note says why.
Query parameters
network"twitch" | "kick" | "youtube"requiredWhere to search.
qstringrequiredA name, @handle or channel link.
curl "https://creatoros-production-5658.up.railway.app/v1/clipper/search?network=twitch&q=kaicenat" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"creators": [
{
"network": "twitch",
"handle": "kaicenat",
"channel_id": "641972806",
"display_name": "KaiCenat",
"avatar_url": "https://static-cdn.jtvnw.net/jtv_user_pictures/...-profile_image-150x150.png",
"followers": 21987104,
"url": "https://www.twitch.tv/kaicenat",
"is_live": false
}
]
}A creator and their streams
/v1/clipper/creators/{network}/{handle}The creator's profile (with pinned_id when you pinned them) and their past streams, newest first: Twitch past broadcasts, Kick VODs, YouTube uploads (no Shorts; YouTube has no duration_s here). live: true means the stream is still recording and can't be clipped yet. Each video lists the runs you already made from it.
Path parameters
network"twitch" | "kick" | "youtube"requiredThe network.
handlestringrequiredTwitch login, Kick slug or YouTube @handle (or UC channel id).
Query parameters
limitintegerHow many streams, 1 to 50 (YouTube up to 15). Default 24.
curl "https://creatoros-production-5658.up.railway.app/v1/clipper/creators/twitch/kaicenat" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"creator": {
"network": "twitch",
"handle": "kaicenat",
"display_name": "KaiCenat",
"followers": 21987104,
"url": "https://www.twitch.tv/kaicenat",
"pinned_id": null
},
"videos": [
{
"network": "twitch",
"video_id": "2924282282",
"url": "https://www.twitch.tv/videos/2924282282",
"title": "PLAYING EVERY GTA UNTIL I BEAT IT: Grand Theft Auto 4",
"thumbnail_url": "https://static-cdn.jtvnw.net/cf_vods/.../thumb0-640x360.jpg",
"published_at": "2026-11-09T19:49:31Z",
"duration_s": 126420,
"views": 7122756,
"live": false,
"runs": []
}
]
}Pinned creators
/v1/clipper/creatorsThe creators this workspace pinned, for quick access and as autopilot sources.
curl "https://creatoros-production-5658.up.railway.app/v1/clipper/creators" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"creators": [
{
"id": "0b6f3a1e-2c4d-4e8f-9a1b-7c5d3e2f1a09",
"network": "kick",
"handle": "xqc",
"channel_id": "668",
"display_name": "xQc",
"avatar_url": "https://files.kick.com/images/user/676/profile_image/...",
"followers": 1616052,
"created_at": "2026-11-14T16:02:11.000Z"
}
]
}Pin a creator
/v1/clipper/creatorsPins a creator (or refreshes their name, picture and followers if already pinned). 404 creator_not_found when there is no such channel. Unpin with DELETE /v1/clipper/creators/{creatorId} (it also leaves any autopilot watching them).
Body
network"twitch" | "kick" | "youtube"With handle.
handlestringLogin, slug or @handle.
urlstringOr the channel link instead of network + handle.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/clipper/creators" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"network": "kick",
"handle": "xqc"
}'{
"creator": {
"id": "0b6f3a1e-2c4d-4e8f-9a1b-7c5d3e2f1a09",
"network": "kick",
"handle": "xqc",
"display_name": "xQc",
"followers": 1616052
}
}Accounts a clip can post to
/v1/clipper/accountsThe workspace's connected accounts that take a vertical video (Instagram, TikTok, YouTube, Facebook, X, Threads, LinkedIn). Use their ids in account_ids when posting a clip or setting up an autopilot.
curl "https://creatoros-production-5658.up.railway.app/v1/clipper/accounts" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"accounts": [
{
"id": "acc_Q2xp...",
"platform": "tiktok",
"username": "clipsdaily",
"followers": 18200
},
{
"id": "acc_Hn4k...",
"platform": "instagram",
"username": "clipsdaily",
"followers": 9400
}
]
}Clip a stream or video
/v1/clipper/runsQueues a run. Send a stream or video link (Twitch past broadcast, Kick VOD, YouTube video), any other video link, your upload (an https URL or a med_ id from POST /v1/media), or network + video_id from the streams list. A channel link is refused with 400 stream_required. Poll GET /v1/clipper/runs/{runId}: the scan comes first (progress 0 to 100), then each clip is edited and scored. 429 too_many_in_flight past 3 runs at once (no monthly limit; up to 10 clips per video), 402 plan_required without a plan.
Body
source_urlstringThe stream / video link, your uploaded file (https URL or med_ id), or another video link.
network"twitch" | "kick" | "youtube"With video_id, instead of source_url.
video_idstringThe network's video id (from the streams list). Kick also takes handle.
style"podcast" | "gaming"podcast (default): podcasts, IRL and just chatting; follows whoever is speaking, splits the screen when two people talk. gaming: facecam on top, gameplay underneath. gaming defaults the design to the gamer preset.
layout"auto" | "speaker" | "split" | "center" | "blur" | "full"auto (default) picks per moment. speaker: one crop that follows the person talking. split: two stacked panels (two speakers, or facecam over gameplay). center: a fixed crop. blur: the whole frame over a blurred copy. full: gameplay only.
goalsstringWhat the clips are for: the audience, the kind of moments you want, what to avoid.
quick_findstringDescribe one moment to find, e.g. "when chat lost it over the 1v3".
window_start_snumberScan only from here (seconds into the stream).
window_end_snumberScan only up to here. At least 30 s after window_start_s. Leave both out to scan it all.
clip_countintegerHow many clips, 1 to 10. Default 5.
min_sintegerShortest clip in seconds, from 5. Default 20.
max_sintegerLongest clip in seconds, up to 180. Default 60.
aspect"9:16" | "4:5" | "1:1" | "16:9"Default 9:16.
designobjectA preset and overrides (see Designs): e.g. { "preset": "gamer", "font": "bangers", "highlight_color": "#FF3B30" }.
titlestringOptional hints shown until the scan fills them in: title, creator_name, thumbnail_url, published_at, duration_s.
creator_idstringA pinned creator this stream belongs to (optional).
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/clipper/runs" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_url": "https://www.twitch.tv/videos/2924282282",
"style": "gaming",
"clip_count": 6,
"max_s": 45,
"window_start_s": 3600,
"window_end_s": 10800,
"design": {
"preset": "gamer",
"highlight_color": "#FF3B30"
}
}'{
"run": {
"id": "5d2a7c1e-3f4b-4a9e-8c6d-1b2e3f4a5c6d",
"network": "twitch",
"source_url": "https://www.twitch.tv/videos/2924282282",
"video_id": "2924282282",
"style": "gaming",
"layout": "auto",
"clip_count": 6,
"min_s": 20,
"max_s": 45,
"aspect": "9:16",
"window": {
"start_s": 3600,
"end_s": 10800
},
"status": "queued",
"step": null,
"progress": 0,
"clips_summary": {
"total": 0,
"ready": 0,
"editing": 0,
"failed": 0,
"best_score": null
},
"clips": []
}
}Get a run
/v1/clipper/runs/{runId}status: queued, working, done, failed or cancelled; step and progress show where it is; scanned is the part of the stream that was read. clips are the clips found so far (see Get a clip).
Path parameters
runIdstringrequiredThe run id.
curl "https://creatoros-production-5658.up.railway.app/v1/clipper/runs/5d2a7c1e-3f4b-4a9e-8c6d-1b2e3f4a5c6d" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"run": {
"id": "5d2a7c1e-3f4b-4a9e-8c6d-1b2e3f4a5c6d",
"title": "PLAYING EVERY GTA UNTIL I BEAT IT: Grand Theft Auto 4",
"creator_name": "KaiCenat",
"duration_s": 126420,
"status": "working",
"step": "Editing clip 3 of 6",
"progress": 100,
"scanned": {
"from_s": 3600,
"to_s": 10800
},
"clips_summary": {
"total": 6,
"ready": 2,
"editing": 4,
"failed": 0,
"best_score": 84
},
"clips": [
{
"id": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
"status": "ready",
"title": "Kai gets wanted by the whole city",
"virality_score": 84
}
]
}
}List runs
/v1/clipper/runsNewest first, with access. Delete one with DELETE /v1/clipper/runs/{runId} (its clips go with it).
Query parameters
autopilot_idstringOnly runs an autopilot started.
limitinteger1 to 100. Default 30.
curl "https://creatoros-production-5658.up.railway.app/v1/clipper/runs" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"runs": [
{
"id": "5d2a7c1e-3f4b-4a9e-8c6d-1b2e3f4a5c6d",
"status": "done",
"clips_summary": {
"total": 6,
"ready": 6,
"editing": 0,
"failed": 0,
"best_score": 84
}
}
],
"access": {
"plan": "active",
"can_create": true,
"reason": null,
"runs_this_month": 4,
"monthly_limit": null
}
}Cancel a run
/v1/clipper/runs/{runId}/cancelStops a queued or running run. Clips not started are dropped; finished ones stay. 409 not_running if it already finished.
Path parameters
runIdstringrequiredThe run id.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/clipper/runs/5d2a7c1e-3f4b-4a9e-8c6d-1b2e3f4a5c6d/cancel" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"ok": true
}List clips
/v1/clipper/clipsClips across runs (discarded ones left out), newest first or best scored first.
Query parameters
run_idstringOnly one run's clips.
statusstringComma-separated: queued, rendering, ready, failed.
min_scoreintegerOnly clips scoring at least this.
posted"true" | "false"Only posted (or scheduled) clips, or only clips not posted yet.
sort"score"Best virality score first (default: newest first).
limitinteger1 to 200. Default 50.
curl "https://creatoros-production-5658.up.railway.app/v1/clipper/clips?min_score=70&posted=false&sort=score" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"clips": [
{
"id": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
"status": "ready",
"title": "Kai gets wanted by the whole city",
"virality_score": 84,
"video_url": "https://api.creatoros.ca/v1/media/med_...",
"post": {
"status": null
}
}
]
}Get a clip
/v1/clipper/clips/{clipId}status: queued, rendering, ready or failed. start_s / end_s are seconds in the source; title, hook (the on-screen hook) and reason (why this moment); transcript; the layout, crop boxes, design and aspect it was edited with; video_url and cover_url; virality_score (0 to 100) and the full virality report; revision and edits (the history of fine-tunes); post (status queued, posted, failed or skipped, the accounts, the Agent Post id); and source with a link to the moment in the original stream.
Path parameters
clipIdstringrequiredThe clip id.
curl "https://creatoros-production-5658.up.railway.app/v1/clipper/clips/9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"clip": {
"id": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
"run_id": "5d2a7c1e-3f4b-4a9e-8c6d-1b2e3f4a5c6d",
"status": "ready",
"title": "Kai gets wanted by the whole city",
"hook": "HE ROBBED THE WRONG STORE",
"reason": "Chaotic chase with a loud payoff at 0:31",
"start_s": 4210.4,
"end_s": 4248.9,
"duration_s": 36.2,
"layout": "split",
"boxes": {},
"aspect": "9:16",
"design": {
"preset": "gamer"
},
"video_url": "https://api.creatoros.ca/v1/media/med_...",
"cover_url": "https://api.creatoros.ca/v1/media/med_...",
"virality_score": 84,
"revision": 0,
"edits": [],
"post": {
"status": null,
"agent_post_id": null,
"accounts": [],
"posted_at": null
},
"source": {
"network": "twitch",
"title": "PLAYING EVERY GTA UNTIL I BEAT IT: Grand Theft Auto 4",
"creator_name": "KaiCenat",
"url": "https://www.twitch.tv/videos/2924282282?t=1h10m10s"
}
}
}Fine-tune a clip
/v1/clipper/clips/{clipId}/reviseRe-edits a finished clip. Say what to change in plain English (instructions) and/or set fields directly; anything left out stays. The clip goes back to queued with revision + 1, then ready with a new video and score. 409 busy while it is being edited; 400 nothing_to_change on an empty body.
Path parameters
clipIdstringrequiredThe clip id.
Body
instructionsstringWhat to change, e.g. "start at the car crash, make the captions green, shorter hook".
start_snumberNew start, seconds in the source.
end_snumberNew end. A clip is 3 to 180 seconds.
titlestringThe clip title (used for the post).
hookstringThe on-screen hook, up to 120 characters.
layout"auto" | "speaker" | "split" | "center" | "blur" | "full"See Clip a stream.
aspect"9:16" | "4:5" | "1:1" | "16:9"Output shape.
boxesobjectCrop boxes as fractions (0 to 1) of the source frame, keyed crop, face, facecam, gameplay, top or bottom: { "facecam": { "x": 0.72, "y": 0.04, "w": 0.26, "h": 0.3 } }.
designobjectOverrides on the clip's design (a new preset starts from that preset).
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/clipper/clips/9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b/revise" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instructions": "Start two seconds later and end right after he laughs",
"design": {
"font": "bangers",
"highlight_color": "#22D3EE"
}
}'{
"clip": {
"id": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
"status": "queued",
"step": "Waiting to re-edit",
"revision": 1,
"pending_instructions": "Start two seconds later and end right after he laughs"
}
}Post a clip
/v1/clipper/clips/{clipId}/postHands a finished clip to Agent Posts: it writes the caption for each network, uses the clip's cover and schedules it. 409 not_ready before the clip is finished, 409 already_posted if it is already scheduled or posted.
Path parameters
clipIdstringrequiredThe clip id.
Body
account_idsstring[]requiredacc_ ids from GET /v1/clipper/accounts.
whenstring"next_slot" (default: the next free slot in your Agent Setup posting hours), "now", or an ISO time at least 3 minutes ahead.
captionstringYour caption to steer the written ones (optional).
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/clipper/clips/9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b/post" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_ids": [
"acc_Q2xp...",
"acc_Hn4k..."
],
"when": "now"
}'{
"ok": true,
"agent_post_id": "2c4e6a8b-1d3f-4a5c-9e7b-0f1a2b3c4d5e",
"scheduled_for": "2026-11-14T18:04:00.000Z"
}Score a clip again
/v1/clipper/clips/{clipId}/scoreRuns the Virality agent on a finished clip again (every clip is scored once when it is made). The clip's virality_score updates when it is done; watch GET /v1/virality/{check_id}. Discard a clip with DELETE /v1/clipper/clips/{clipId}.
Path parameters
clipIdstringrequiredThe clip id.
Body
platformstringScore it for one network (optional).
captionstringThe caption it will go out with (optional; default: the clip title).
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/clipper/clips/9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b/score" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"platform": "tiktok"
}'{
"check_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
"message": "Scoring. The clip's virality_score updates when it is done (GET /virality/:checkId to watch)."
}Create an autopilot
/v1/clipper/autopilotsWatches creators for new streams, clips each one, and (with autopost) posts the clips that score at least virality_threshold, up to posts_per_day in total and max_per_network per network a day, spread across the day. Only streams published after since are clipped. Up to 5 autopilots per workspace (409 autopilot_limit). List them with GET /v1/clipper/autopilots, delete with DELETE /v1/clipper/autopilots/{apId}.
Body
creatorsobject[]{ network, handle } or { url } of channels to watch (pinned on the way).
creator_idsstring[]Or ids of pinned creators. At least one creator either way.
namestringDefault "Autopilot".
enabledbooleanDefault true.
style"podcast" | "gaming"As in Clip a stream; also layout, goals, min_s, max_s, design.
clips_per_videointegerClips per stream, 1 to 10. Default 5.
autopostbooleanPost the winners (default true). false only makes clips.
account_idsstring[]acc_ ids to post to. Required with autopost.
posts_per_dayinteger1 to 24. Default 3.
virality_thresholdinteger0 to 100. Default 67.
max_per_networkobject{ platform: posts per day (0 to 24) }, e.g. { "instagram": 2, "tiktok": 3 }.
sincestringAn ISO time, or "last_week". Default now.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/clipper/autopilots" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"creators": [
{
"network": "twitch",
"handle": "kaicenat"
},
{
"network": "kick",
"handle": "xqc"
}
],
"style": "gaming",
"clips_per_video": 6,
"account_ids": [
"acc_Q2xp...",
"acc_Hn4k..."
],
"posts_per_day": 4,
"virality_threshold": 75,
"max_per_network": {
"instagram": 2,
"tiktok": 4
}
}'{
"autopilot": {
"id": "4b3a2c1d-0e9f-4a8b-7c6d-5e4f3a2b1c0d",
"name": "Autopilot",
"enabled": true,
"creators": [
{
"network": "twitch",
"handle": "kaicenat"
},
{
"network": "kick",
"handle": "xqc"
}
],
"style": "gaming",
"clips_per_video": 6,
"autopost": true,
"posts_per_day": 4,
"virality_threshold": 75,
"max_per_network": {
"instagram": 2,
"tiktok": 4
},
"accounts": [
{
"id": "acc_Q2xp...",
"platform": "tiktok",
"username": "clipsdaily"
}
],
"since": "2026-11-14T16:00:00.000Z",
"last_checked_at": null
}
}Update an autopilot
/v1/clipper/autopilots/{apId}Any field from Create; anything left out stays. { "enabled": false } pauses it.
Path parameters
apIdstringrequiredThe autopilot id.
curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/clipper/autopilots/4b3a2c1d-0e9f-4a8b-7c6d-5e4f3a2b1c0d" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"virality_threshold": 80,
"posts_per_day": 6
}'{
"autopilot": {
"id": "4b3a2c1d-0e9f-4a8b-7c6d-5e4f3a2b1c0d",
"enabled": true,
"posts_per_day": 6,
"virality_threshold": 80
}
}