API resource

Virality agent

Scores any finished short video out of 100 and says what to fix: the hook (the first 3 seconds: what you see, what is said, the text on screen), retention (pacing, dead air, payoff), the topic's pull, emotion, whether it works with the sound off, shareability and fit for the network. Clippy runs the same agent on every clip it makes. Any active plan; up to 5 videos at once and 300 a month.

Score a video

POST/v1/virality

Queues a check; it takes about a minute. Poll GET /v1/virality/{checkId} until status is done (or failed). 429 too_many_in_flight, 429 monthly_limit, 402 plan_required.

Body

video_urlstringrequired

The finished video: an https URL, a med_ id from POST /v1/media, or a TikTok / Reels / Shorts / X link.

platformstring

The network it is meant for: instagram, tiktok, youtube, facebook, twitter (or x), threads, linkedin.

captionstring

The caption it will go out with.

notesstring

Who it is for and what it should do.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/virality" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "med_b0Wq7Yx2Rk9LzT4nVs1Pc8Hf3Jd6Gm5Ea2Uo7Ki9Nr0",
    "platform": "tiktok",
    "caption": "He really thought nobody saw that"
  }'
Response 201
{
  "check": {
    "id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
    "status": "queued",
    "step": null,
    "video_url": "https://api.creatoros.ca/v1/media/med_...",
    "platform": "tiktok",
    "score": null,
    "report": null
  }
}

Get a check

GET/v1/virality/{checkId}

status: queued, working, done or failed. When done: score (0 to 100) and report, the breakdown by part with what works and what to fix. clip_id is set when it scored a Clippy clip.

Path parameters

checkIdstringrequired

The check id.

curl "https://creatoros-production-5658.up.railway.app/v1/virality/7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "check": {
    "id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
    "status": "done",
    "platform": "tiktok",
    "score": 78,
    "clip_id": null,
    "duration_s": 31.4,
    "report": {
      "summary": "Strong visual hook and a clear payoff; the middle drags for 4 seconds."
    }
  }
}

List checks

GET/v1/virality

The 50 latest checks, newest first, with access (used_this_month, monthly_limit). Delete one with DELETE /v1/virality/{checkId}.

curl "https://creatoros-production-5658.up.railway.app/v1/virality" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "checks": [
    {
      "id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "status": "done",
      "score": 78
    }
  ],
  "access": {
    "can_create": true,
    "reason": null,
    "used_this_month": 12,
    "monthly_limit": 300
  }
}