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

> Start async task to generate highlight reel from video

## POST /api/v1/sports/highlights

Start an async task to generate an AI-powered highlight reel from a full-length sports video. Returns a task ID for polling.

This is an **asynchronous** endpoint - use the task ID to poll for results.

**Note:** The system automatically extracts play-by-play metadata from the video unless you supply your own metadata file.

### Parameters

| Parameter               | Type    | Required | Description                                      |
| ----------------------- | ------- | -------- | ------------------------------------------------ |
| video                   | File    | Yes      | Video file (1-2 hours, e.g., full football game) |
| metadata                | File    | No       | Play metadata JSON for enhanced accuracy         |
| editorial\_instructions | string  | No       | Custom instructions for highlight selection      |
| duration                | integer | No       | Target duration in seconds (default: 600)        |

### Response

| Field       | Description                   |
| ----------- | ----------------------------- |
| task\_id    | Unique identifier for polling |
| status      | Initial status (`pending`)    |
| created\_at | When the task was created     |

### Example Request

```bash theme={null}
curl -X POST https://api.usenarrative.ai/api/v1/sports/highlights \
  -H "Content-Type: multipart/form-data" \
  -F "video=@football_game.mp4" \
  -F "duration=900" \
  -F "editorial_instructions=Focus on touchdowns and big plays"
```

### Example Request (with metadata)

```bash theme={null}
curl -X POST https://api.usenarrative.ai/api/v1/sports/highlights \
  -H "Content-Type: multipart/form-data" \
  -F "video=@football_game.mp4" \
  -F "metadata=@play_metadata.json" \
  -F "editorial_instructions=Include crowd reactions"
```

### Example Response

```json theme={null}
{
  "task_id": "task_def456xyz",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}
```

### How It Works

The system automatically extracts metadata from the video to identify key moments:

* **Scoring plays** with precise timestamps
* **Turnovers** and possession changes
* **Big plays** and exciting moments
* **Crowd reactions** and commentary peaks

If you supply your own metadata file, the system will use it instead for even greater accuracy.

### Next Step

Poll the task status using `GET /api/v1/sports/highlights/{task_id}`:

```bash theme={null}
curl https://api.usenarrative.ai/api/v1/sports/highlights/task_def456xyz
```

<Card title="Get Highlights Task" icon="clock" href="/api-reference/sports/get-highlights-task">
  Poll task status and retrieve results
</Card>


## OpenAPI

````yaml POST /api/v1/sports/highlights
openapi: 3.0.3
info:
  title: Sports API
  description: >-
    Sports video analysis and highlight generation API with async task
    processing
  version: 1.0.0
servers:
  - url: https://api.usenarrative.ai
    description: Production
security: []
paths:
  /api/v1/sports/highlights:
    post:
      tags:
        - Highlights
      summary: Generate Highlights
      description: >-
        Start an async task to generate a highlight reel from video. Returns a
        task ID for polling.
      operationId: createHighlightsTask
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/HighlightsRequest'
      responses:
        '202':
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCreatedResponse'
        '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:
    HighlightsRequest:
      type: object
      properties:
        video:
          type: string
          format: binary
          description: Video file (1-2 hours, e.g., full football game)
        metadata:
          type: string
          format: binary
          description: Optional play metadata JSON file for enhanced accuracy
        editorial_instructions:
          type: string
          description: Custom instructions for highlight selection
          example: Focus on touchdowns and big plays
        duration:
          type: integer
          description: Target duration of the highlight reel in seconds
          default: 600
          example: 600
      required:
        - video
    TaskCreatedResponse:
      type: object
      properties:
        task_id:
          type: string
          description: Unique identifier for the task
          example: task_abc123xyz
        status:
          type: string
          enum:
            - pending
          description: Initial task status
          example: pending
        created_at:
          type: string
          format: date-time
          description: When the task was created
          example: '2024-01-15T10:30:00Z'
      required:
        - task_id
        - status
        - created_at
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message

````