Create Recap

Create Recap

curl --request POST \
  --url https://api.narrative-sports.com/v1/recaps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": 123,
  "target_duration_seconds": 1800,
  "name": "<string>",
  "exclude_event_types": [
    "<string>"
  ],
  "selected_edit_ids": [
    "<string>"
  ],
  "recap_mode": "custom",
  "fight_ceremony_config": [
    {
      "fight_number": 123,
      "include_walkon": false,
      "include_decision": false
    }
  ],
  "render_video": "ffmpeg",
  "sport": "<string>",
  "recap_options": {
    "editorial_prompt": "<string>",
    "target_duration_min_seconds": 1830,
    "target_duration_max_seconds": 1830
  }
}
'

import requests

url = "https://api.narrative-sports.com/v1/recaps"

payload = {
    "project_id": 123,
    "target_duration_seconds": 1800,
    "name": "<string>",
    "exclude_event_types": ["<string>"],
    "selected_edit_ids": ["<string>"],
    "recap_mode": "custom",
    "fight_ceremony_config": [
        {
            "fight_number": 123,
            "include_walkon": False,
            "include_decision": False
        }
    ],
    "render_video": "ffmpeg",
    "sport": "<string>",
    "recap_options": {
        "editorial_prompt": "<string>",
        "target_duration_min_seconds": 1830,
        "target_duration_max_seconds": 1830
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    project_id: 123,
    target_duration_seconds: 1800,
    name: '<string>',
    exclude_event_types: ['<string>'],
    selected_edit_ids: ['<string>'],
    recap_mode: 'custom',
    fight_ceremony_config: [{fight_number: 123, include_walkon: false, include_decision: false}],
    render_video: 'ffmpeg',
    sport: '<string>',
    recap_options: {
      editorial_prompt: '<string>',
      target_duration_min_seconds: 1830,
      target_duration_max_seconds: 1830
    }
  })
};

fetch('https://api.narrative-sports.com/v1/recaps', 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.narrative-sports.com/v1/recaps",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'project_id' => 123,
    'target_duration_seconds' => 1800,
    'name' => '<string>',
    'exclude_event_types' => [
        '<string>'
    ],
    'selected_edit_ids' => [
        '<string>'
    ],
    'recap_mode' => 'custom',
    'fight_ceremony_config' => [
        [
                'fight_number' => 123,
                'include_walkon' => false,
                'include_decision' => false
        ]
    ],
    'render_video' => 'ffmpeg',
    'sport' => '<string>',
    'recap_options' => [
        'editorial_prompt' => '<string>',
        'target_duration_min_seconds' => 1830,
        'target_duration_max_seconds' => 1830
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.narrative-sports.com/v1/recaps"

	payload := strings.NewReader("{\n  \"project_id\": 123,\n  \"target_duration_seconds\": 1800,\n  \"name\": \"<string>\",\n  \"exclude_event_types\": [\n    \"<string>\"\n  ],\n  \"selected_edit_ids\": [\n    \"<string>\"\n  ],\n  \"recap_mode\": \"custom\",\n  \"fight_ceremony_config\": [\n    {\n      \"fight_number\": 123,\n      \"include_walkon\": false,\n      \"include_decision\": false\n    }\n  ],\n  \"render_video\": \"ffmpeg\",\n  \"sport\": \"<string>\",\n  \"recap_options\": {\n    \"editorial_prompt\": \"<string>\",\n    \"target_duration_min_seconds\": 1830,\n    \"target_duration_max_seconds\": 1830\n  }\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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.narrative-sports.com/v1/recaps")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"project_id\": 123,\n  \"target_duration_seconds\": 1800,\n  \"name\": \"<string>\",\n  \"exclude_event_types\": [\n    \"<string>\"\n  ],\n  \"selected_edit_ids\": [\n    \"<string>\"\n  ],\n  \"recap_mode\": \"custom\",\n  \"fight_ceremony_config\": [\n    {\n      \"fight_number\": 123,\n      \"include_walkon\": false,\n      \"include_decision\": false\n    }\n  ],\n  \"render_video\": \"ffmpeg\",\n  \"sport\": \"<string>\",\n  \"recap_options\": {\n    \"editorial_prompt\": \"<string>\",\n    \"target_duration_min_seconds\": 1830,\n    \"target_duration_max_seconds\": 1830\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.narrative-sports.com/v1/recaps")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"project_id\": 123,\n  \"target_duration_seconds\": 1800,\n  \"name\": \"<string>\",\n  \"exclude_event_types\": [\n    \"<string>\"\n  ],\n  \"selected_edit_ids\": [\n    \"<string>\"\n  ],\n  \"recap_mode\": \"custom\",\n  \"fight_ceremony_config\": [\n    {\n      \"fight_number\": 123,\n      \"include_walkon\": false,\n      \"include_decision\": false\n    }\n  ],\n  \"render_video\": \"ffmpeg\",\n  \"sport\": \"<string>\",\n  \"recap_options\": {\n    \"editorial_prompt\": \"<string>\",\n    \"target_duration_min_seconds\": 1830,\n    \"target_duration_max_seconds\": 1830\n  }\n}"

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

{
  "id": 123,
  "status": "queued",
  "task_id": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

recaps

Create Recap

curl --request POST \
  --url https://api.narrative-sports.com/v1/recaps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": 123,
  "target_duration_seconds": 1800,
  "name": "<string>",
  "exclude_event_types": [
    "<string>"
  ],
  "selected_edit_ids": [
    "<string>"
  ],
  "recap_mode": "custom",
  "fight_ceremony_config": [
    {
      "fight_number": 123,
      "include_walkon": false,
      "include_decision": false
    }
  ],
  "render_video": "ffmpeg",
  "sport": "<string>",
  "recap_options": {
    "editorial_prompt": "<string>",
    "target_duration_min_seconds": 1830,
    "target_duration_max_seconds": 1830
  }
}
'

import requests

url = "https://api.narrative-sports.com/v1/recaps"

payload = {
    "project_id": 123,
    "target_duration_seconds": 1800,
    "name": "<string>",
    "exclude_event_types": ["<string>"],
    "selected_edit_ids": ["<string>"],
    "recap_mode": "custom",
    "fight_ceremony_config": [
        {
            "fight_number": 123,
            "include_walkon": False,
            "include_decision": False
        }
    ],
    "render_video": "ffmpeg",
    "sport": "<string>",
    "recap_options": {
        "editorial_prompt": "<string>",
        "target_duration_min_seconds": 1830,
        "target_duration_max_seconds": 1830
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    project_id: 123,
    target_duration_seconds: 1800,
    name: '<string>',
    exclude_event_types: ['<string>'],
    selected_edit_ids: ['<string>'],
    recap_mode: 'custom',
    fight_ceremony_config: [{fight_number: 123, include_walkon: false, include_decision: false}],
    render_video: 'ffmpeg',
    sport: '<string>',
    recap_options: {
      editorial_prompt: '<string>',
      target_duration_min_seconds: 1830,
      target_duration_max_seconds: 1830
    }
  })
};

fetch('https://api.narrative-sports.com/v1/recaps', 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.narrative-sports.com/v1/recaps",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'project_id' => 123,
    'target_duration_seconds' => 1800,
    'name' => '<string>',
    'exclude_event_types' => [
        '<string>'
    ],
    'selected_edit_ids' => [
        '<string>'
    ],
    'recap_mode' => 'custom',
    'fight_ceremony_config' => [
        [
                'fight_number' => 123,
                'include_walkon' => false,
                'include_decision' => false
        ]
    ],
    'render_video' => 'ffmpeg',
    'sport' => '<string>',
    'recap_options' => [
        'editorial_prompt' => '<string>',
        'target_duration_min_seconds' => 1830,
        'target_duration_max_seconds' => 1830
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.narrative-sports.com/v1/recaps"

	payload := strings.NewReader("{\n  \"project_id\": 123,\n  \"target_duration_seconds\": 1800,\n  \"name\": \"<string>\",\n  \"exclude_event_types\": [\n    \"<string>\"\n  ],\n  \"selected_edit_ids\": [\n    \"<string>\"\n  ],\n  \"recap_mode\": \"custom\",\n  \"fight_ceremony_config\": [\n    {\n      \"fight_number\": 123,\n      \"include_walkon\": false,\n      \"include_decision\": false\n    }\n  ],\n  \"render_video\": \"ffmpeg\",\n  \"sport\": \"<string>\",\n  \"recap_options\": {\n    \"editorial_prompt\": \"<string>\",\n    \"target_duration_min_seconds\": 1830,\n    \"target_duration_max_seconds\": 1830\n  }\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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.narrative-sports.com/v1/recaps")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"project_id\": 123,\n  \"target_duration_seconds\": 1800,\n  \"name\": \"<string>\",\n  \"exclude_event_types\": [\n    \"<string>\"\n  ],\n  \"selected_edit_ids\": [\n    \"<string>\"\n  ],\n  \"recap_mode\": \"custom\",\n  \"fight_ceremony_config\": [\n    {\n      \"fight_number\": 123,\n      \"include_walkon\": false,\n      \"include_decision\": false\n    }\n  ],\n  \"render_video\": \"ffmpeg\",\n  \"sport\": \"<string>\",\n  \"recap_options\": {\n    \"editorial_prompt\": \"<string>\",\n    \"target_duration_min_seconds\": 1830,\n    \"target_duration_max_seconds\": 1830\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.narrative-sports.com/v1/recaps")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"project_id\": 123,\n  \"target_duration_seconds\": 1800,\n  \"name\": \"<string>\",\n  \"exclude_event_types\": [\n    \"<string>\"\n  ],\n  \"selected_edit_ids\": [\n    \"<string>\"\n  ],\n  \"recap_mode\": \"custom\",\n  \"fight_ceremony_config\": [\n    {\n      \"fight_number\": 123,\n      \"include_walkon\": false,\n      \"include_decision\": false\n    }\n  ],\n  \"render_video\": \"ffmpeg\",\n  \"sport\": \"<string>\",\n  \"recap_options\": {\n    \"editorial_prompt\": \"<string>\",\n    \"target_duration_min_seconds\": 1830,\n    \"target_duration_max_seconds\": 1830\n  }\n}"

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

{
  "id": 123,
  "status": "queued",
  "task_id": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Overview

Create a recap that summarizes a single game (project) by selecting highlights to fit a target duration. Narrative selects which clips to include based on event importance and editorial fit. Every matched highlight must be OTIO-ready because the public contract is OTIO EDL-first. Current highlights generate otio_edit automatically. 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, or a matched highlight is missing otio_edit, the recap transitions to status: "failed" with a failure_reason.

Request

curl -X POST "https://api.narrative-sports.com/v1/recaps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 1,
    "target_duration_seconds": 60,
    "exclude_event_types": ["kickoff", "final_whistle", "player_walk_on"],
    "render_video": "ffmpeg"
  }'

Request Body

Parameter	Type	Required	Description
`project_id`	integer	Yes	Project ID to create a recap from
`target_duration_seconds`	integer	Yes	Target duration in seconds (min: 60, max: 3600). Use `0` to auto-size from the sport profile.
`exclude_event_types`	string[]	No	Event types to exclude from selection (e.g. `player_walk_on`, `kickoff`, `final_whistle`). Non-excluded ceremony types are force-included rather than left to Narrative selection.
`selected_edit_ids`	string[]	No	Restrict the eligible highlights to these IDs. For MMA fight selection, use the chosen fights’ `highlight_ids` from project highlight options. Narrative selects and trims within this set. Omitted or empty means no ID restriction. All matched highlights must be OTIO-ready.
`recap_mode`	string	No	Deprecated and ignored. Recaps are duration-based; the former `"standard"` / `"extended"` modes were removed. Accepted for backward compatibility.
`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	Recap tuning: editorial instructions, duration mode, and sport-specific style — see Recap Options below
`fight_ceremony_config`	object[]	No	MMA per-fight walk-on / decision selections
`render_video`	string	No	`"ffmpeg"` (default) to render a video, or `"none"` for OTIO timeline EDL only

Selecting Specific Fights

For a single-fight recap, fetch project highlight options, select the desired entry in fights, and send its nonempty highlight_ids list as selected_edit_ids. For multiple fights, combine their IDs and remove duplicates. See the single-fight recap example. fight_filter and selected_fights belong to the highlight-package API and are ignored by this endpoint. Setting name to a fighter pairing does not restrict the recap to that fight. Fight selection must be expressed through selected_edit_ids.

Recap Options

The recap_options object accepts free-form editorial instructions and a duration mode, alongside sport-specific style knobs:

Parameter	Type	Required	Description
`editorial_prompt`	string	No	Free-form guidance for Narrative selection (max 2000 chars), e.g. `"focus on the home team, keep it tight"`
`duration_mode`	string	No	`"exact"` (default) to target `target_duration_seconds`, or `"range"` to let the recap land anywhere between the min/max bounds below
`target_duration_min_seconds`	integer	No	Lower bound of the duration range in seconds (min: 60). Required when `duration_mode` is `"range"`
`target_duration_max_seconds`	integer	No	Upper bound of the duration range in seconds (max: 3600, must be ≥ the min). Required when `duration_mode` is `"range"`
`start_style`	string	No	MMA only: `"none"`, `"short_walkout"`, or `"full_walkout"`
`ending_style`	string	No	MMA only: `"auto"` or `"decision_or_ending"`
`pacing`	string	No	`"balanced"` or `"action_sprint"`

When duration_mode is "range", Narrative selection lands the total recap duration inside [target_duration_min_seconds, target_duration_max_seconds] instead of within ±10% of a single target:

curl -X POST "https://api.narrative-sports.com/v1/recaps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 1,
    "target_duration_seconds": 240,
    "recap_options": {
      "editorial_prompt": "focus on the home team, keep it tight",
      "duration_mode": "range",
      "target_duration_min_seconds": 180,
      "target_duration_max_seconds": 300
    }
  }'

Response

{
  "id": 43,
  "status": "queued",
  "task_id": "def789-ghi012"
}

Response Fields

Field	Type	Description
`id`	integer	Recap ID — use with `GET /recaps/{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 /recaps/{id} until status is "complete" or "failed".

EDL Contract

The recap otio_timeline is a merged OTIO Timeline.1 composed from selected highlights’ stored otio_edit payloads. Use Get Project Highlight Options to inspect readiness. Creation stores an OTIO EDL in otio_timeline; the API does not synthesize recap EDLs from editor-project JSON.

Errors

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

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

American Football

American-football recaps use the sport-specific selection profile and preserve the complete worker-tagged live-play original_moment for every selected highlight. Replay/reaction footage outside that segment is excluded.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

project_id

integer

required

target_duration_seconds

integer

required

Required range: 0 <= x <= 3600

name

string | null

exclude_event_types

string[] | null

selected_edit_ids

string[] | null

recap_mode

string

default:custom

fight_ceremony_config

FightCeremonyConfig · object[] | null

Show child attributes

render_video

enum<string>

default:ffmpeg

Available options:

ffmpeg,

none

sport

string | null

recap_options

RecapOptions · object | null

Show child attributes

Response

Success

integer

required

status

string

default:queued

task_id

string | null

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Overview

Request

Request Body

Selecting Specific Fights

Recap Options

Response

Response Fields

Polling for Results

EDL Contract

Errors

American Football

Authorizations

Body

Response

​Overview

​Request

​Request Body

​Selecting Specific Fights

​Recap Options

​Response

​Response Fields

​Polling for Results

​EDL Contract

​Errors

​American Football

Authorizations

Body

Response

Overview

Request

Request Body

Selecting Specific Fights

Recap Options

Response

Response Fields

Polling for Results

EDL Contract

Errors

American Football