Hook Generator API

When to use it

• Script-writing agents that need ranked openers before generating the full script body.
• A/B testing tools that want multiple hook variants for the same underlying video idea.
• Editors looking for a creative brainstorm tool instead of staring at a blank doc.
• Educational platforms that produce explainer content and need attention-grabbing opens.

Endpoint

POST /api/v1/hooks/generate

Quickstart

curl -X POST https://api.reelsbuilder.ai/api/v1/hooks/generate \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "the hidden cost of free SaaS tiers",
    "audience": "indie hackers",
    "tone": "contrarian",
    "count": 5
  }'

Response shape

{
  "success": true,
  "data": {
    "hooks": [
      {
        "text": "Your \"free\" Notion is costing you $400/month. Here's the math.",
        "score": 0.91,
        "format": "negative_curiosity",
        "estimated_watch_time_sec": 18
      },
      {
        "text": "I switched 6 freemium tools to paid and saved 14 hours a week.",
        "score": 0.87,
        "format": "personal_story",
        "estimated_watch_time_sec": 16
      },
      {
        "text": "The 3 free tools that are quietly burning your runway.",
        "score": 0.84,
        "format": "list_curiosity",
        "estimated_watch_time_sec": 15
      },
      {
        "text": "Free SaaS is the new freemium trap. Here's how to spot it.",
        "score": 0.76,
        "format": "category_redefinition",
        "estimated_watch_time_sec": 14
      },
      {
        "text": "Why I paid for Linear despite the free tier (and don't regret it).",
        "score": 0.71,
        "format": "personal_authority",
        "estimated_watch_time_sec": 13
      }
    ]
  },
  "meta": {
    "request_id": "req_...",
    "credits_used": 1,
    "credits_remaining": 999,
    "processing_time_ms": 412
  }
}

Parameters

Hook formats

Every returned hook carries a format classifier from a fixed taxonomy. Useful for A/B testing across categories or filtering to a specific style.

• negative_curiosity — "Your X is broken. Here's why."
• positive_curiosity — "The 1 thing that changed X for me."
• list_curiosity — "3 X you didn't know about."
• personal_story — "I did X and Y happened."
• personal_authority — "After Y years of X, here's what I learned."
• category_redefinition — "X is the new Y."
• contrarian — "Everyone says X. They're wrong."
• question_open — "Did you know X?"
• data_point — "X% of Y do Z."

How the score works

Each hook is scored 0.0–1.0 by a model fine-tuned on ReelsBuilder's historical video performance data — millions of generated videos with actual watch-time, completion-rate, and engagement signals.

• 0.85+: ship it. These hooks have historical equivalents in the top 10% of completion-rate cohort.
• 0.70-0.85: good. Worth shipping; consider an A/B test against a 0.85+ alternative.
• Below 0.70: only returned if you set count higher than 5 — included for completeness, not because we recommend them.

Examples

TypeScript

const res = await fetch("https://api.reelsbuilder.ai/api/v1/hooks/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REELSBUILDER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    topic: "the hidden cost of free SaaS tiers",
    audience: "indie hackers",
    tone: "contrarian",
    count: 5,
  }),
});
const { data } = await res.json();
const best = data.hooks[0];  // highest score first
console.log(`Use: "${best.text}" (score ${best.score})`);

Python

import os, uuid, requests

r = requests.post(
    "https://api.reelsbuilder.ai/api/v1/hooks/generate",
    headers={
        "Authorization": f"Bearer {os.environ['REELSBUILDER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "topic": "the hidden cost of free SaaS tiers",
        "audience": "indie hackers",
        "tone": "contrarian",
        "count": 5,
    },
)
hooks = r.json()["data"]["hooks"]
best = hooks[0]
print(f"Use: \"{best['text']}\" (score {best['score']})")

Pricing

• 1 credit per call (returns up to 5 hooks).
• +0.2 credits per hook above 5, capped at 10.
• +0.5 credits if brand_id is provided (covers the brand-context lookup).

Free accounts include fixed starter videos, not a hook-call credit balance. API usage starts with paid tokens or the card-verified trial proof render. See pricing.

Latency & caching

Median latency is 412ms. P99 under 1.2s. Responses are not cached server-side — every call generates fresh hooks. Use Idempotency-Key if you need deterministic replay (recommended for production workflows).

Best practices

• Pass a specific topic. "Why React beats Vue" generates better hooks than "frontend frameworks."
• Set platform when you know the destination — TikTok hooks read differently from LinkedIn hooks.
• Use brand_id when available — branded hooks score 8-12% higher on real engagement than generic ones.
• For A/B testing, pull 5 hooks, ship the top 2 with different videos. The hook is the variable; the rest of the content should be identical.

See also

• Viral Trends API — find topics worth writing hooks for
• Brand DNA API — extract a brand_id for tuned hooks
• Generate & Post API — turn a hook into a published video