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

# Summarize Video

> Generate AI-powered video summaries

## POST /api/v1/summarize

Generate an AI-powered summary of video content. Supports multiple output formats including bullet points, paragraphs, and timestamped chapters.

### Parameters

| Parameter  | Type | Required | Description                                                                       |
| ---------- | ---- | -------- | --------------------------------------------------------------------------------- |
| video\_url | URL  | Yes      | URL to the video to summarize                                                     |
| format     | enum | No       | Output format: `bullet_points`, `paragraph`, or `chapters` (default: `paragraph`) |

### Response

| Field         | Description                                   |
| ------------- | --------------------------------------------- |
| summary       | Generated summary text                        |
| chapters      | Chapter breakdown (only when format=chapters) |
| duration\_sec | Duration of the video in seconds              |

### Chapter Object (when format=chapters)

| Field            | Description                          |
| ---------------- | ------------------------------------ |
| title            | Chapter title                        |
| start\_time\_sec | Start time of the chapter in seconds |
| end\_time\_sec   | End time of the chapter in seconds   |

### Example Request

```bash theme={null}
curl -X POST https://api.usenarrative.ai/api/v1/summarize \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://example.com/game.mp4",
    "format": "chapters"
  }'
```

### Example Response (Chapters Format)

```json theme={null}
{
  "summary": "This video covers the championship game between the Eagles and Giants, featuring key plays and dramatic moments throughout all four quarters.",
  "chapters": [
    {
      "title": "First Quarter - Opening Drives",
      "start_time_sec": 0,
      "end_time_sec": 900
    },
    {
      "title": "Second Quarter - Eagles Take the Lead",
      "start_time_sec": 900,
      "end_time_sec": 1800
    },
    {
      "title": "Halftime Analysis",
      "start_time_sec": 1800,
      "end_time_sec": 2100
    },
    {
      "title": "Third Quarter - Giants Fight Back",
      "start_time_sec": 2100,
      "end_time_sec": 3000
    },
    {
      "title": "Fourth Quarter - Dramatic Finish",
      "start_time_sec": 3000,
      "end_time_sec": 3600
    }
  ],
  "duration_sec": 3600
}
```

### Example Response (Bullet Points Format)

```json theme={null}
{
  "summary": "- Eagles won the championship game 28-24\n- Key touchdown by Smith in the 4th quarter\n- Giants mounted a comeback in the 3rd quarter\n- Over 50,000 fans in attendance",
  "duration_sec": 3600
}
```

### Notes

* Processing time varies based on video length
* The AI analyzes both audio and visual content
* Chapters format is ideal for creating video navigation
* Bullet points format is concise and scannable
* Paragraph format provides a narrative summary


## OpenAPI

````yaml POST /api/v1/summarize
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/summarize:
    post:
      tags:
        - Analysis
      summary: Summarize Video
      description: >-
        Generate an AI-powered summary of video content. Supports multiple
        output formats including bullet points, paragraphs, and chapters.
      operationId: summarizeVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SummarizeVideoRequest'
      responses:
        '200':
          description: Video summarized successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummarizeVideoResponse'
        '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:
    SummarizeVideoRequest:
      type: object
      properties:
        video_url:
          type: string
          format: uri
          description: URL to the video to summarize
          example: https://example.com/video.mp4
        format:
          type: string
          enum:
            - bullet_points
            - paragraph
            - chapters
          description: Output format for the summary
          default: paragraph
          example: chapters
      required:
        - video_url
    SummarizeVideoResponse:
      type: object
      properties:
        summary:
          type: string
          description: Generated summary text
          example: This video covers the key moments from the championship game...
        chapters:
          type: array
          items:
            $ref: '#/components/schemas/Chapter'
          description: Chapter breakdown (only present when format=chapters)
        duration_sec:
          type: number
          description: Duration of the video in seconds
          example: 3600
      required:
        - summary
        - duration_sec
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
          example: Invalid video URL provided
    Chapter:
      type: object
      properties:
        title:
          type: string
          description: Chapter title
          example: Opening Kickoff
        start_time_sec:
          type: number
          description: Start time of the chapter in seconds
          example: 0
        end_time_sec:
          type: number
          description: End time of the chapter in seconds
          example: 420
      required:
        - title
        - start_time_sec
        - end_time_sec

````