API resource
Variations
Turn one finished video into up to 20 distinct versions, one for every account in a posting network, so no two accounts post the same file. Each version keeps the content and voice and changes the look: colour grade, zoom and framing, the on-screen hook (written fresh for each version by default), an overlay (grain, vignette, accent bar), GIF cutaways from GIPHY picked to match what is said, a slightly shorter length and a faint sound bed. A uniqueness check holds back any version that comes out identical to another. Every version is a 1080x1920 MP4 with its own caption and hashtags. Nothing is posted: post the versions you want with POST /v1/posts. Paid plans are unlimited; a plan in its free trial gets one run.
Make variations
/v1/variationsQueues a run; it takes a few minutes. Up to 2 runs in progress at once. Returns 402 trial_used when a trial plan has already had its run, 402 plan_required without a plan.
Body
video_urlstringrequiredThe finished video: an https URL, a med_ id from POST /v1/media, or a TikTok / Reels / YouTube / X link. Up to 10 minutes.
countintegerHow many versions, 1 to 20. Default 20.
hook_mode"auto" | "custom" | "none"auto (default): a different on-screen hook per version, written from the video. custom: your hook on every version. none: no on-screen text.
hookstringThe hook for hook_mode custom.
notesstringWhat the video is about, the offer, words to avoid. Steers hooks, captions and GIFs.
use_giphybooleanCut in matching GIFs as b-roll. Default true.
broll_urlsstring[]Your own b-roll clips (https URLs or med_ ids, up to 24), mixed in with the GIFs.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/variations" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0",
"count": 20,
"hook_mode": "auto",
"notes": "Free guide for new creators, link in bio"
}'{
"job": {
"id": "7f3a1c2e-5b8d-4e9f-a1c3-2d4e6f8a0b1c",
"count": 20,
"hook_mode": "auto",
"status": "queued",
"step": null,
"ready": 0,
"renders": []
}
}Get a run
/v1/variations/{jobId}status: queued, working, done, failed or cancelled. One entry in renders per version, with its look, hook, caption, hashtags and video_url once it's ready (or error). ready counts finished versions; a run is done when at least one rendered.
Path parameters
jobIdstringrequiredThe run id.
curl "https://creatoros-production-5658.up.railway.app/v1/variations/7f3a1c2e-5b8d-4e9f-a1c3-2d4e6f8a0b1c" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"job": {
"id": "7f3a1c2e-5b8d-4e9f-a1c3-2d4e6f8a0b1c",
"status": "done",
"ready": 20,
"count": 20,
"renders": [
{
"look": "warm-tall",
"index": 1,
"status": "done",
"hook": "POV: you stop filming new videos",
"caption": "You do not need new content every day. Remix the one you already made.",
"hashtags": [
"contentcreation",
"creatorlife"
],
"video_url": "https://api.creatoros.ca/v1/media/med_...",
"cover_url": "https://api.creatoros.ca/v1/media/med_...",
"duration_s": 21.7,
"error": null
}
]
}
}List runs
/v1/variationsNewest first, with access: plan (paid, trial or none), trial_used and can_create.
curl "https://creatoros-production-5658.up.railway.app/v1/variations" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"jobs": [
{
"id": "7f3a1c2e-5b8d-4e9f-a1c3-2d4e6f8a0b1c",
"status": "working",
"step": "Rendering 4 of 20",
"ready": 3,
"count": 20
}
],
"access": {
"plan": "paid",
"trial_used": false,
"can_create": true,
"reason": null
},
"max_count": 20
}Cancel a run
/v1/variations/{jobId}/cancelStops a queued or running run; finished versions stay. Delete one with DELETE /v1/variations/{jobId}.
Path parameters
jobIdstringrequiredThe run id.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/variations/7f3a1c2e-5b8d-4e9f-a1c3-2d4e6f8a0b1c/cancel" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"ok": true
}Post versions, one per account
/v1/variations/{jobId}/postSends finished versions out through Agent Posts, each to ONE account with its own caption, so no two accounts post the same file. schedule.mode is spread (default: one every gap_minutes, 30 by default), now or at (from start). Each version then carries post: the account, status and time.
Path parameters
jobIdstringrequiredThe run id.
Body
assignmentsarrayrequiredWhich version goes where: [{ look, account_id }]. Each look and each account at most once.
scheduleobject{ mode: "spread" | "now" | "at", start?, gap_minutes? }.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/variations/7f3a1c2e-5b8d-4e9f-a1c3-2d4e6f8a0b1c/post" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assignments": [
{
"look": "teal-punch",
"account_id": "acc_9Qe2Lw"
},
{
"look": "warm-film",
"account_id": "acc_3Hk8Zp"
}
],
"schedule": {
"mode": "spread",
"gap_minutes": 30
}
}'{
"job": {
"id": "7f3a1c2e-5b8d-4e9f-a1c3-2d4e6f8a0b1c",
"renders": [
{
"look": "teal-punch",
"post": {
"account_id": "acc_9Qe2Lw",
"platform": "tiktok",
"status": "queued",
"scheduled_for": "2026-11-18T15:03:00Z"
}
}
]
}
}