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

POST/v1/variations

Queues 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_urlstringrequired

The finished video: an https URL, a med_ id from POST /v1/media, or a TikTok / Reels / YouTube / X link. Up to 10 minutes.

countinteger

How 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.

hookstring

The hook for hook_mode custom.

notesstring

What the video is about, the offer, words to avoid. Steers hooks, captions and GIFs.

use_giphyboolean

Cut 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"
  }'
Response 201
{
  "job": {
    "id": "7f3a1c2e-5b8d-4e9f-a1c3-2d4e6f8a0b1c",
    "count": 20,
    "hook_mode": "auto",
    "status": "queued",
    "step": null,
    "ready": 0,
    "renders": []
  }
}

Get a run

GET/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

jobIdstringrequired

The run id.

curl "https://creatoros-production-5658.up.railway.app/v1/variations/7f3a1c2e-5b8d-4e9f-a1c3-2d4e6f8a0b1c" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "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

GET/v1/variations

Newest 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"
Response 200
{
  "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

POST/v1/variations/{jobId}/cancel

Stops a queued or running run; finished versions stay. Delete one with DELETE /v1/variations/{jobId}.

Path parameters

jobIdstringrequired

The 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"
Response 200
{
  "ok": true
}

Post versions, one per account

POST/v1/variations/{jobId}/post

Sends 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

jobIdstringrequired

The run id.

Body

assignmentsarrayrequired

Which 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
    }
  }'
Response 200
{
  "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"
        }
      }
    ]
  }
}