Hook Validator

POST/youtube/v1/hook-validator

What it does

You provide three things: a thumbnail, a title, and the first 60–90 seconds of your video script. The API focuses on the first 30 seconds (the hook window) but uses the extra text to detect delayed payoffs. It returns a risk score (0–100), specific mismatches found, and a prediction of early viewer drop-off.

What the API analyzes

The API performs four parallel analyses and then cross-validates the results:

🖼️ Thumbnail Analysis

Emotion, energy level, stakes (low/medium/high), clickbait score, and key visual elements detected via AI vision.

📝 Title Analysis

Promise extraction, tone classification (dramatic/urgent/mysterious/exciting/neutral), and clickbait score.

🎤 Script Hook Analysis

Speaking pace (WPM), info density, opening energy, payoff delay, and whether the script delivers on the title's promise.

🔀 Cross-Validation

Detects mismatches between all three elements. Returns risk score, risk level, and retention prediction.

The four mismatch types

Type	What it catches	Example
Emotion	Thumbnail emotion vs. script tone	Shocked face thumbnail, but the intro is calm and analytical
Energy	Visual energy vs. opening energy	High-energy action thumbnail, but intro is a slow monologue
Pacing	Title urgency vs. delivery speed	"You WON'T BELIEVE…" title, but payoff doesn't come until 45s in
Content	Title promise vs. actual script content	Title promises a tutorial, but intro is a personal story

Each mismatch is rated by severity: minor (usually fine), moderate (worth fixing), or severe (likely causing drop-off).

Why use it?

The #1 reason viewers leave isn't bad content — it's broken promises. A dramatic thumbnail with a calm, slow intro feels like clickbait. Even if unintentional, the mismatch kills retention.
You can't see your own mismatches. As the creator, you know what's coming. Your viewers don't. The API analyzes the experience from a first-time viewer's perspective.
Test before you record. Run your script through the validator before filming. If the intro doesn't match the thumbnail promise, you can fix it while it's still free.
Quantified predictions. Instead of guessing whether your hook is good, get a concrete prediction: "42% of viewers will leave in the first 30 seconds."
Specific, fixable feedback. Not "make it better" but "your thumbnail promises high energy, and your intro doesn't match. Start with the exciting moment instead of a greeting."

Examples

Request example

curl -X POST https://api.creatornode.io/youtube/v1/hook-validator \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{
    "thumbnail": {
      "imageBase64": "dGh1bWJuYWlsLWJhc2U2NA=="
    },
    "title": "I Built a SaaS in 48 Hours — From Zero to $1k MRR",
    "scriptIntro": "What\'s up everyone! So, a couple of months ago I was sitting in my apartment, kind of bored, scrolling through Twitter, and I saw this thread about building micro-SaaS products...",
    "options": { "scriptDurationSeconds": 75 }
  }'

Response example

{
  "validation": {
    "riskLevel": "high",
    "riskScore": 72,
    "primaryIssue": "Pacing mismatch: title promises fast results, intro delays payoff",
    "mismatches": [
      {
        "type": "pacing",
        "severity": "severe",
        "description": "Title promises '48 Hours' urgency, but intro spends 45+ seconds on backstory"
      },
      {
        "type": "energy",
        "severity": "moderate",
        "description": "Thumbnail suggests high-energy hustle, intro is relaxed and conversational"
      }
    ],
    "prediction": {
      "earlyDropoffPercent": 50,
      "retention30s": 50
    }
  },
  "thumbnail": {
    "emotion": "Determination",
    "stakes": "high",
    "keyElements": ["person", "laptop", "code editor"],
    "energyLevel": "high",
    "clickbaitScore": 45
  },
  "title": {
    "promise": "Build a profitable SaaS in 48 hours",
    "tone": "exciting",
    "clickbaitScore": 65
  },
  "scriptHook": {
    "wpm": 125,
    "infoDensity": 35,
    "openingEnergy": "low",
    "payoffDelay": 45,
    "actualContent": "Personal backstory about scrolling Twitter",
    "deliversPromise": false
  },
  "recommendations": [
    {
      "type": "tip",
      "title": "Front-load the payoff",
      "message": "Start with the result: 'I built this app in 48 hours and it's making $1k/month. Let me show you how.' Then go into the backstory.",
      "priority": "high"
    }
  ],
  "metadata": {
    "requestId": "req_abc123",
    "processingTimeMs": 1250,
    "aiUsed": true
  }
}

Risk levels explained

Level	Score range	What it means
🟢 Low	0–25	Great alignment. Thumbnail, title, and intro tell the same story. Low early drop-off expected.
🟡 Medium	26–50	Minor issues. May cause some drop-off with demanding audiences. Usually worth a quick fix.
🟠 High	51–75	Significant mismatch. Likely causing viewer frustration. Fix before publishing.
🔴 Critical	76–100	Complete disconnect between what you promise and what you deliver. High early drop-off. Rewrite the intro or change the thumbnail.

Tips & tricks

Write the script first, then test. Don't wait until after filming. Run your draft script through the validator and iterate. Changing text is free; re-shooting video is not.
Front-load your payoff. The API calculates a dynamic payoff threshold based on your thumbnail stakes, title clickbait score, and opening energy. If a "Payoff comes too late" recommendation appears, consider a cold open — start with the most exciting moment, then rewind.
Match thumbnail energy to intro energy. If your thumbnail is dramatic and high-energy, your first sentence should match that intensity. Don't open with "Hey guys, welcome back" after a thumbnail that promises chaos.
Clickbait isn't the problem — broken promises are. A high clickbaitScore is fine if deliversPromise is true. The API doesn't penalize clickbait; it penalizes clickbait that doesn't deliver.
Watch your speaking pace (WPM). Below 120 WPM feels sluggish in an internet video. The API measures this and flags slow intros. If you provide scriptDurationSeconds, the API calculates WPM and flags slow delivery. Aim for 140–170 WPM in the first 30 seconds.
Use it as an editing tool. After recording, transcribe your first 90 seconds and run it through the validator. If it flags a pacing mismatch, you can fix it in editing by rearranging the intro, adding a teaser clip, or cutting the greeting.
Iterate until you hit "low" risk. The best creators run 2–3 iterations: draft script → validate → fix mismatches → validate again. Each round the risk score drops.

💡 Pro workflow: Use Thumbnail Ranking first to pick your best thumbnail, then run Hook Validator with the winning thumbnail + your title + script. This way, you're validating alignment against the thumbnail you'll actually use.

Cost & Limits

Feature	Detail
Credit cost	10 credits per request
Max image size	2 MB
Supported formats	JPEG, PNG, WebP
Includes	AI analysis (thumbnail + title + script)

Tier Limits

Limit	Free	Premium
Max script length	3,000 chars	10,000 chars
AI models	Previous generation	Latest models

💡 Formula: total = 10 credits — flat rate, AI analysis of thumbnail + title + script is always included.

Other Endpoints

POST/youtube/v1/thumbnail-ranking

Thumbnail Ranking

AI-powered ranking of 2–10 thumbnail variants by predicted click-through rate.