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

# Extract Metadata

> Start async task to extract structured metadata from video

## POST /api/v1/sports/extract-metadata

Start an async task to extract structured metadata from video using ROI configuration. Returns a task ID for polling.

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

### Parameters

| Parameter      | Type    | Required | Description                                         |
| -------------- | ------- | -------- | --------------------------------------------------- |
| video          | File    | No\*     | Video file to process                               |
| video\_url     | URL     | No\*     | URL to video file                                   |
| roi\_config    | object  | Yes      | ROI configuration from detect-rois endpoint         |
| output\_schema | object  | Yes      | JSON Schema defining the event structure to extract |
| skip\_frames   | integer | No       | Process every Nth frame (default: 2)                |

\*Either `video` or `video_url` is required.

### 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/extract-metadata \
  -H "Content-Type: multipart/form-data" \
  -F "video=@football_game.mp4" \
  -F 'roi_config={
    "play_clock": {"y_min": 45, "x_min": 580, "y_max": 75, "x_max": 640},
    "game_clock": {"y_min": 45, "x_min": 480, "y_max": 75, "x_max": 560},
    "home_score": {"y_min": 45, "x_min": 200, "y_max": 75, "x_max": 250},
    "away_score": {"y_min": 45, "x_min": 300, "y_max": 75, "x_max": 350}
  }' \
  -F 'output_schema={
    "type": "object",
    "properties": {
      "event_type": {"type": "string", "enum": ["play_start", "play_end", "score_change"]},
      "timestamp_sec": {"type": "number"},
      "game_clock": {"type": "string"},
      "home_score": {"type": "integer"},
      "away_score": {"type": "integer"}
    }
  }'
```

### Example Response

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

### Next Step

Poll the task status using `GET /api/v1/sports/extract-metadata/{task_id}`:

```bash theme={null}
curl https://api.usenarrative.ai/api/v1/sports/extract-metadata/task_abc123xyz
```

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


## OpenAPI

````yaml POST /api/v1/sports/extract-metadata
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/extract-metadata:
    post:
      tags:
        - Metadata Extraction
      summary: Extract Metadata
      description: >-
        Start an async task to extract structured metadata from video using ROI
        configuration. Returns a task ID for polling.
      operationId: createExtractMetadataTask
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ExtractMetadataRequest'
      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:
    ExtractMetadataRequest:
      type: object
      properties:
        video:
          type: string
          format: binary
          description: Video file to process
        video_url:
          type: string
          format: uri
          description: 'Alternative: URL to video file'
        roi_config:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BoundingBox'
          description: ROI configuration from detect-rois endpoint
        output_schema:
          type: object
          description: JSON Schema defining the structure of events to extract
        skip_frames:
          type: integer
          description: Process every Nth frame for faster processing
          default: 2
          example: 2
      required:
        - roi_config
        - output_schema
    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
    BoundingBox:
      type: object
      properties:
        y_min:
          type: integer
          description: Top edge Y coordinate (pixels from top)
        x_min:
          type: integer
          description: Left edge X coordinate (pixels from left)
        y_max:
          type: integer
          description: Bottom edge Y coordinate
        x_max:
          type: integer
          description: Right edge X coordinate
      required:
        - y_min
        - x_min
        - y_max
        - x_max

````