TikTok Video Hook Analyzer

Apify Actor that downloads TikTok videos, extracts the opening hook (first N seconds), and uses AI vision models to produce a detailed hook quality report with scoring, transcript, strengths/weaknesses, and improvement suggestions.

How it works

1. Parse URL - Extracts the numeric video ID from standard, short, and mobile TikTok URL formats.
2. Fetch metadata - Calls the tikwm.com API to retrieve the video caption, stats, author info, and a no-watermark download link.
3. Download video - Streams the HD video to a temporary file.
4. Trim hook - Uses FFmpeg to cut the first N seconds (hookDuration).
5. Extract frames - Pulls evenly-spaced JPEG keyframes from the hook for visual analysis.
6. Extract audio - Separates the audio track as MP3.
7. Transcribe - Sends the audio to OpenAI Whisper for speech-to-text (OpenAI provider only).
8. AI analysis - Sends frames + transcript + caption + stats to GPT-4o or Claude and receives a structured JSON report.
9. Store result - Pushes the report to the Apify Dataset.

Each video is processed independently - one failure does not abort the batch. Failed videos produce an error record in the dataset.

Input

Field	Type	Required	Default	Description
videoUrls	string[]	Yes	-	TikTok video URLs (1-50)
aiProvider	"openai" | "anthropic"	Yes	-	AI provider for hook analysis
aiApiKey	string	Yes	-	API key for the chosen provider
hookDuration	integer	No	5	Seconds from the start to analyze (1-15)
frameCount	integer	No	4	Keyframes to extract from the hook (1-10)
includeTranscript	boolean	No	true	Transcribe hook audio via OpenAI Whisper

Example input

{
    "videoUrls": [
        "https://www.tiktok.com/@username/video/7234567890123456789",
        "https://vm.tiktok.com/ZMxxxxxxx/"
    ],
    "aiProvider": "openai",
    "aiApiKey": "sk-...",
    "hookDuration": 5,
    "frameCount": 4,
    "includeTranscript": true
}

Note: Whisper transcription requires an OpenAI API key. When using Anthropic as the AI provider, transcription is skipped.

Output

Each dataset item is a Hook Analysis Report with the following structure:

{
    "videoId": "7234567890123456789",
    "videoUrl": "https://www.tiktok.com/@username/video/7234567890123456789",
    "hookDuration": 5,
    "metadata": {
        "caption": "Video caption text...",
        "author": "Display Name",
        "authorId": "username",
        "videoDuration": 32,
        "views": 1500000,
        "likes": 120000,
        "comments": 3400,
        "shares": 8900,
        "saves": 15000,
        "postedAt": "2025-06-15T10:30:00.000Z",
        "musicUrl": "https://...",
        "coverUrl": "https://..."
    },
    "transcript": "Transcribed speech from the hook...",
    "analysis": {
        "hookScore": 8,
        "hookType": "Pattern Interrupt",
        "hookTranscript": "Moment-by-moment breakdown of what happens in the hook...",
        "whatMakesItWork": [
            "Immediately disrupts scroll with unexpected visual",
            "Strong opening line creates curiosity gap"
        ],
        "weaknesses": [
            "Audio could be louder in the first second"
        ],
        "improvementSuggestions": [
            "Add on-screen text in the first frame to reinforce the hook",
            "Start speaking within the first 0.5 seconds"
        ],
        "engagementPrediction": {
            "performanceLevel": "High",
            "estimatedRetention": "70-80% past hook",
            "reasoning": "The pattern interrupt combined with a curiosity gap..."
        },
        "comparableTrendingHooks": [
            "\"Wait for it\" suspense hooks",
            "POV transformation reveals"
        ],
        "visualTechniques": [
            "Jump cut in first frame",
            "High-contrast color grading"
        ],
        "audioTechniques": [
            "Trending sound with beat drop at 0.5s",
            "Direct-to-camera speech"
        ]
    },
    "processedAt": "2025-06-20T14:22:00.000Z"
}

If a video fails to process, the dataset item contains:

{
    "videoUrl": "https://www.tiktok.com/...",
    "error": "Description of what went wrong",
    "processedAt": "2025-06-20T14:22:00.000Z"
}

Dataset views

The Apify Console provides three pre-configured table views:

View	Columns
Hook Analysis Reports	URL, Score, Type, Breakdown, Performance, Retention, Caption, Author, Transcript
Video Metadata	URL, Caption, Author, Duration, Views, Likes, Comments, Shares, Saves, Posted, Cover
Processing Errors	URL, Error, Timestamp

Supported URL formats

• https://www.tiktok.com/@user/video/1234567890123456789
• https://vm.tiktok.com/ZMxxxxxxx/
• https://m.tiktok.com/v/1234567890123456789
• https://www.tiktok.com/t/ZMxxxxxxx/
• Plain numeric video ID

AI providers

Provider	Model	Vision	Transcription
OpenAI	GPT-4o	Yes (keyframes sent as images)	Whisper
Anthropic	Claude Sonnet 4	Yes (keyframes sent as images)	Not available (skipped)

Local development

Prerequisites: Node.js 22+, FFmpeg on PATH, Apify CLI.

npm install
npm run build

Create an apify_storage/key_value_stores/default/INPUT.json with your input, then:

$npx apify-cli run -purge

Built with

• Apify SDK - Actor framework
• OpenAI SDK - GPT-4o + Whisper
• Anthropic SDK - Claude
• fluent-ffmpeg - Video processing
• axios - HTTP client