Create Highlight Package

Early Beta — Highlight Packages is in early beta. Behavior, request/response shapes, and error semantics may change without notice. Not recommended for production use.

Overview

Create a highlight package that aggregates highlights across multiple projects (games). Narrative selects clips to fit the target duration, optionally guided by your editorial prompt and filters. Every matched highlight must have otio_edit because the public contract is OTIO EDL-first. Current highlights generate otio_edit automatically; use Get Project Highlight Options before creating a package to discover event types, fights, highlight IDs, and OTIO readiness. Set render_video to "ffmpeg" (default) to receive a rendered concatenated video plus the EDL, or "none" to receive only the merged OTIO timeline EDL without rendering. Highlight selection runs asynchronously after creation: if no highlights match the given filters, or a matched highlight is missing otio_edit, the package transitions to status: "failed" with a failure_reason instead of creating a non-OTIO package EDL.

New to packages? Start with Create Highlight Packages, which walks through discovery, creation, polling, and dashboard sync.

Request

curl -X POST "https://api.narrative-sports.com/v1/highlight-packages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_ids": [1, 2, 3],
    "target_duration_seconds": 120,
    "editorial_prompt": "Focus on goals and dramatic moments",
    "event_type_filter": ["goal", "penalty"],
    "fight_filter": [
      { "project_id": 1, "fight_numbers": [3] }
    ],
    "render_video": "ffmpeg"
  }'

Request Body

Parameter	Type	Required	Description
`name`	string	No	Optional display name for the package
`project_ids`	integer[]	Yes	List of project IDs to pull highlights from (minimum 1)
`target_duration_seconds`	integer	Yes	Target duration in seconds (min: 60, max: 3600)
`editorial_prompt`	string	No	Editorial guidance for Narrative selection (e.g. “focus on goals and dramatic moments”)
`team_filter`	string[]	No	Only include highlights involving these teams
`player_filter`	string[]	No	Only include highlights involving these players
`event_type_filter`	string[]	No	Only include highlights of these event types (e.g. `goal`, `penalty`, `missed_opportunity`)
`fight_filter`	object[]	No	For MMA projects, include only highlights from these project-scoped fight numbers. Shape: `{ "project_id": 1234, "fight_numbers": [1, 3] }`
`selected_fights`	object[]	No	Alias for `fight_filter` for clients that expose selected fights in the UI
`selected_edit_ids`	string[]	No	Restrict the package to exact highlight IDs discovered from project highlight options. Applied after team, player, event type, and fight filters
`sport`	string	No	Optional sport hint: `soccer`, `mma`, `baseball`, `american_football`, or `squash`. New stream highlights also carry sport metadata for automatic profile selection.
`recap_options`	object	No	Optional sport-specific selector tuning
`render_video`	string	No	`"ffmpeg"` (default) to render a video, or `"none"` for OTIO timeline EDL only

Response

{
  "id": 42,
  "status": "queued",
  "task_id": "abc123-def456"
}

Response Fields

Field	Type	Description
`id`	integer	Package ID — use with `GET /highlight-packages/{id}` to poll for results
`status`	string	Initial public status, always `"queued"`
`task_id`	string	Background task ID

Polling for Results

After creation, poll GET /highlight-packages/{id}. Public statuses are "queued", "processing", "complete", and "failed"; keep polling until "complete" or "failed".

EDL Contract

The package otio_timeline is a merged OTIO Timeline.1 composed from the selected highlights’ stored otio_edit payloads. Each OTIO clip includes provenance metadata such as edit_id, project_id, event_type, event_description, package_id, and package sequence index. Creation stores an OTIO EDL in otio_timeline; the API does not synthesize package EDLs from editor-project JSON. The response also includes selected_edit_ids, which are the stable references back to the source highlight records.

Errors

Status	Description
`401`	Invalid or missing API key
`403`	You do not own one or more of the specified projects
`422`	Invalid request body
`500`	Server error

Highlight selection runs asynchronously after the package is created. If no highlights match the given filters, or a matched highlight is missing otio_edit, the package transitions to status: "failed" with a failure_reason — retrieve it via Get Highlight Package.

American Football

For american_football, each selected highlight preserves the complete worker-tagged original_moment (the live play) and excludes replay/reaction footage from that source highlight. The selector prioritizes scoring plays, turnovers, explosive plays, sacks, fourth-down swings, returns, and decisive late-game moments.

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Overview

Request

Request Body

Response

Response Fields

Polling for Results

EDL Contract

Errors

American Football

​Overview

​Request

​Request Body

​Response

​Response Fields

​Polling for Results

​EDL Contract

​Errors

​American Football

Overview

Request

Request Body

Response

Response Fields

Polling for Results

EDL Contract

Errors

American Football