> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.video/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Hook

> Create engaging social media hooks with cliffhangers

## 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

| Parameter              | Type | Required | Description                                             |
| ---------------------- | ---- | -------- | ------------------------------------------------------- |
| continuous\_video\_url | URL  | Yes      | URL to the prepared continuous video                    |
| transcript\_url        | URL  | Yes      | URL to the transcript JSON file                         |
| hook\_type             | enum | Yes      | Type of hook: `fine_cut`, `compilation`, or `narration` |

### Hook Types

| Type          | Description                                              |
| ------------- | -------------------------------------------------------- |
| `fine_cut`    | Single complete scene (20-40s) with high drama, no edits |
| `compilation` | Flashback structure: Setup → Flashback → Continuation    |
| `narration`   | TikTok-style edit with AI voiceover (3-4 segments)       |

### Response

| Field                       | Description                                   |
| --------------------------- | --------------------------------------------- |
| video\_url                  | URL to the generated hook video               |
| hook\_duration\_sec         | Duration of the hook in seconds               |
| cliffhanger\_timestamp\_sec | Timestamp where the video cuts to cliffhanger |
| hook\_type                  | Type of hook that was generated               |

### Example Request

```bash theme={null}
curl -X POST https://api.usenarrative.ai/api/v1/hooks/generate \
  -H "Content-Type: application/json" \
  -d '{
    "continuous_video_url": "https://cdn.usenarrative.ai/prepared/continuous_abc123.mp4",
    "transcript_url": "https://cdn.usenarrative.ai/prepared/transcript_abc123.json",
    "hook_type": "fine_cut"
  }'
```

### Example Response

```json theme={null}
{
  "video_url": "https://cdn.usenarrative.ai/hooks/hook_abc123.mp4",
  "hook_duration_sec": 35.5,
  "cliffhanger_timestamp_sec": 756.8,
  "hook_type": "fine_cut"
}
```

### 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


## OpenAPI

````yaml POST /api/v1/hooks/generate
openapi: 3.0.3
info:
  title: Hooks API
  description: AI-powered social media hook generation and video analysis
  version: 1.0.0
servers:
  - url: https://api.usenarrative.ai
    description: Production
security: []
paths:
  /api/v1/hooks/generate:
    post:
      tags:
        - Hooks
      summary: Generate Hook
      description: >-
        Generate an engaging hook from prepared video content. Supports multiple
        hook types optimized for social media engagement.
      operationId: generateHook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateHookRequest'
      responses:
        '200':
          description: Hook generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateHookResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    GenerateHookRequest:
      type: object
      properties:
        continuous_video_url:
          type: string
          format: uri
          description: URL to the prepared continuous video
          example: https://cdn.usenarrative.ai/prepared/continuous_abc123.mp4
        transcript_url:
          type: string
          format: uri
          description: URL to the transcript JSON file
          example: https://cdn.usenarrative.ai/prepared/transcript_abc123.json
        hook_type:
          type: string
          enum:
            - fine_cut
            - compilation
            - narration
          description: Type of hook to generate
          example: fine_cut
      required:
        - continuous_video_url
        - transcript_url
        - hook_type
    GenerateHookResponse:
      type: object
      properties:
        video_url:
          type: string
          format: uri
          description: URL to the generated hook video
          example: https://cdn.usenarrative.ai/hooks/hook_abc123.mp4
        hook_duration_sec:
          type: number
          description: Duration of the hook in seconds
          example: 35.5
        cliffhanger_timestamp_sec:
          type: number
          description: Timestamp where the video cuts to cliffhanger
          example: 756.8
        hook_type:
          type: string
          enum:
            - fine_cut
            - compilation
            - narration
          description: Type of hook that was generated
          example: fine_cut
      required:
        - video_url
        - hook_duration_sec
        - cliffhanger_timestamp_sec
        - hook_type
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
          example: Invalid video URL provided

````