Generate Highlights

curl --request POST \
  --url https://api.usenarrative.ai/api/v1/sports/highlights \
  --header 'Content-Type: multipart/form-data' \
  --form video='@example-file' \
  --form metadata='@example-file' \
  --form 'editorial_instructions=Focus on touchdowns and big plays' \
  --form duration=600

import requests

url = "https://api.usenarrative.ai/api/v1/sports/highlights"

files = {
    "video": ("example-file", open("example-file", "rb")),
    "metadata": ("example-file", open("example-file", "rb"))
}
payload = {
    "editorial_instructions": "Focus on touchdowns and big plays",
    "duration": "600"
}

response = requests.post(url, data=payload, files=files)

print(response.text)

const form = new FormData();
form.append('video', '<string>');
form.append('metadata', '<string>');
form.append('editorial_instructions', 'Focus on touchdowns and big plays');
form.append('duration', '600');

const options = {method: 'POST'};

options.body = form;

fetch('https://api.usenarrative.ai/api/v1/sports/highlights', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usenarrative.ai/api/v1/sports/highlights",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"editorial_instructions\"\r\n\r\nFocus on touchdowns and big plays\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration\"\r\n\r\n600\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usenarrative.ai/api/v1/sports/highlights"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"editorial_instructions\"\r\n\r\nFocus on touchdowns and big plays\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration\"\r\n\r\n600\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usenarrative.ai/api/v1/sports/highlights")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"editorial_instructions\"\r\n\r\nFocus on touchdowns and big plays\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration\"\r\n\r\n600\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usenarrative.ai/api/v1/sports/highlights")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"editorial_instructions\"\r\n\r\nFocus on touchdowns and big plays\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration\"\r\n\r\n600\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "task_id": "task_abc123xyz",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

POST

api

sports

highlights

Generate Highlights

curl --request POST \
  --url https://api.usenarrative.ai/api/v1/sports/highlights \
  --header 'Content-Type: multipart/form-data' \
  --form video='@example-file' \
  --form metadata='@example-file' \
  --form 'editorial_instructions=Focus on touchdowns and big plays' \
  --form duration=600

import requests

url = "https://api.usenarrative.ai/api/v1/sports/highlights"

files = {
    "video": ("example-file", open("example-file", "rb")),
    "metadata": ("example-file", open("example-file", "rb"))
}
payload = {
    "editorial_instructions": "Focus on touchdowns and big plays",
    "duration": "600"
}

response = requests.post(url, data=payload, files=files)

print(response.text)

const form = new FormData();
form.append('video', '<string>');
form.append('metadata', '<string>');
form.append('editorial_instructions', 'Focus on touchdowns and big plays');
form.append('duration', '600');

const options = {method: 'POST'};

options.body = form;

fetch('https://api.usenarrative.ai/api/v1/sports/highlights', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usenarrative.ai/api/v1/sports/highlights",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"editorial_instructions\"\r\n\r\nFocus on touchdowns and big plays\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration\"\r\n\r\n600\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usenarrative.ai/api/v1/sports/highlights"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"editorial_instructions\"\r\n\r\nFocus on touchdowns and big plays\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration\"\r\n\r\n600\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usenarrative.ai/api/v1/sports/highlights")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"editorial_instructions\"\r\n\r\nFocus on touchdowns and big plays\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration\"\r\n\r\n600\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usenarrative.ai/api/v1/sports/highlights")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"video\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"editorial_instructions\"\r\n\r\nFocus on touchdowns and big plays\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"duration\"\r\n\r\n600\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "task_id": "task_abc123xyz",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

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

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)

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

{
  "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}:

curl https://api.usenarrative.ai/api/v1/sports/highlights/task_def456xyz

Get Highlights Task

Poll task status and retrieve results

Body

multipart/form-data

video

file

required

Video file (1-2 hours, e.g., full football game)

metadata

file

Optional play metadata JSON file for enhanced accuracy

editorial_instructions

string

Custom instructions for highlight selection

Example:

"Focus on touchdowns and big plays"

duration

integer

default:600

Target duration of the highlight reel in seconds

Example:

600

Response

Task created successfully

task_id

string

required

Unique identifier for the task

Example:

"task_abc123xyz"

status

enum<string>

required

Initial task status

Available options:

pending

Example:

"pending"

created_at

string<date-time>

required

When the task was created

Example:

"2024-01-15T10:30:00Z"

Overview

Metadata Extraction

Highlights

Generate Highlights

POST /api/v1/sports/highlights

Parameters

Response

Example Request

Example Request (with metadata)

Example Response

How It Works

Next Step

Get Highlights Task

Body

Response

​POST /api/v1/sports/highlights

​Parameters

​Response

​Example Request

​Example Request (with metadata)

​Example Response

​How It Works

​Next Step

Get Highlights Task

Body

Response

POST /api/v1/sports/highlights

Parameters

Response

Example Request

Example Request (with metadata)

Example Response

How It Works

Next Step