Skip to main content
POST
Generate Hook

POST /api/v1/hooks/generate

Generate an engaging hook from prepared video content. Supports multiple hook types optimized for social media engagement, each with automatic cliffhanger detection.

Parameters

Hook Types

Response

Example Request

Example Response

Hook Type Details

Fine Cut

  • Finds one complete, engaging scene from the video
  • 20-40 seconds of continuous playback with no edits
  • Identifies scenes with dramatic arc (beginning, middle, end)

Compilation

  • Creates a three-part narrative structure
  • Setup (8-10s): Characters discussing a past event
  • Flashback (10-15s): The actual scene from earlier
  • Continuation (8-10s): Return to present with reaction

Narration

  • TikTok-style edit with AI-generated voiceover
  • 3-4 video segments from any timestamp, in any order
  • Each segment has 12-18 word narration overlay
  • Builds suspense and intrigue

Notes

  • Requires output from the Prepare Video endpoint
  • Cliffhanger is detected 12-18 minutes after the hook ends
  • Hook is designed to maximize viewer engagement and watch-through

Body

application/json
continuous_video_url
string<uri>
required

URL to the prepared continuous video

Example:

"https://cdn.usenarrative.ai/prepared/continuous_abc123.mp4"

transcript_url
string<uri>
required

URL to the transcript JSON file

Example:

"https://cdn.usenarrative.ai/prepared/transcript_abc123.json"

hook_type
enum<string>
required

Type of hook to generate

Available options:
fine_cut,
compilation,
narration
Example:

"fine_cut"

Response

Hook generated successfully

video_url
string<uri>
required

URL to the generated hook video

Example:

"https://cdn.usenarrative.ai/hooks/hook_abc123.mp4"

hook_duration_sec
number
required

Duration of the hook in seconds

Example:

35.5

cliffhanger_timestamp_sec
number
required

Timestamp where the video cuts to cliffhanger

Example:

756.8

hook_type
enum<string>
required

Type of hook that was generated

Available options:
fine_cut,
compilation,
narration
Example:

"fine_cut"