Create Game Recaps

Prerequisites

Before you begin, you’ll need:

An API key — create and manage keys in the API Dashboard
A completed project with generated highlights
The project ID from GET /v1/tasks/{task_id}/info, your dashboard, or your project management workflow

Current highlights generate otio_edit automatically. Recap creation requires the selected highlights to be OTIO-ready because the recap EDL is merged from those source highlight edits.

Overview

A recap summarizes a single game (project). You give Narrative a project ID and a target duration, and it selects which highlights to include based on event importance and editorial fit. You can steer selection by excluding event types or passing exact highlight IDs. The basic flow is:

Get the project ID for the stream task.
Discover the project’s highlights and event types.
Create a recap from the project ID and a target duration.
Poll the recap through queued and processing until it is complete or failed.
Retrieve the EDL and rendered video URL.

Step 1: Get the Project ID

If you started from a stream task, fetch the generated project ID from task info:

curl "https://api.narrative-sports.com/v1/tasks/YOUR_TASK_ID/info" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use task.project_id in the response. If it is null, retry after the task has started producing project data.

Step 2: Discover Highlight Options

Use your project ID to discover available event types, teams, players, highlight IDs, and OTIO readiness:

curl -X GET "https://api.narrative-sports.com/v1/projects/1234/highlight-options" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "project_id": 1234,
  "project_name": "Cup Final",
  "event_types": [
    { "value": "goal", "count": 4, "otio_ready_count": 4 },
    { "value": "kickoff", "count": 1, "otio_ready_count": 1 }
  ],
  "teams": [
    { "value": "Argentina", "count": 6, "otio_ready_count": 6 }
  ],
  "players": [
    { "value": "Lionel Messi", "count": 3, "otio_ready_count": 3 }
  ],
  "fights": [],
  "highlights": [
    {
      "id": "edit-1",
      "event_type": "goal",
      "event_description": "Opening goal",
      "target_team": "Argentina",
      "target_players": ["Lionel Messi"],
      "otio_ready": true
    }
  ],
  "total_highlights": 1,
  "otio_ready_highlights": 1
}

Use these values directly in recap creation:

Discovery field	Recap request field
`event_types[].value`	`exclude_event_types` to remove event types from selection
`highlights[].id`	`selected_edit_ids` for exact highlight selection
`fights[].highlight_ids`	`selected_edit_ids` to restrict a recap to selected MMA fights

Step 3: Create a Recap

Send the project ID and a target duration. Narrative selects highlights to fit the target; use exclude_event_types to keep ceremony or low-value events out of the recap.

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

Response:

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

Save the returned recap id. Recap creation can take up to about a minute, and status moves through queued, then usually processing, before reaching complete or failed.

Set render_video to "ffmpeg" (default) to receive a rendered video plus the EDL, or "none" to create only the OTIO EDL.

Recap Duration

Every recap is duration-based: set target_duration_seconds (60–3600) and Narrative selects and trims highlights to hit it. When your target is longer than the detected highlights can fill, Narrative pulls in additional source spans from the game so the recap still reaches the target. Pass target_duration_seconds: 0 to let Narrative auto-size the recap from the sport profile.

curl -X POST "https://api.narrative-sports.com/v1/recaps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 1234,
    "target_duration_seconds": 600
  }'

The previous "standard" and "extended" recap modes have been removed; recaps are now always duration-based. recap_mode is deprecated and ignored — it is still accepted for backward compatibility but no longer changes behavior.

Use selected_edit_ids to restrict the highlights Narrative can select from; all matched highlights must be OTIO-ready. Narrative still selects and trims within that set to fit the target duration.

Create a Single-Fight Recap

For an MMA event containing multiple fights, find the desired fight_number in the project’s highlight options and pass that fight’s highlight_ids as selected_edit_ids. For several fights, combine their highlight IDs and remove duplicates.

curl -X POST "https://api.narrative-sports.com/v1/recaps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fight 2 Recap",
    "project_id": 1234,
    "target_duration_seconds": 150,
    "sport": "mma",
    "selected_edit_ids": ["edit-101", "edit-102", "edit-103"],
    "render_video": "ffmpeg"
  }'

Replace the example IDs with the selected fight’s actual highlight IDs. Confirm the list is nonempty before submitting: omitting selected_edit_ids or sending an empty array leaves the entire project eligible.

fight_filter and selected_fights are supported by highlight-package creation, but are ignored by POST /v1/recaps. Use selected_edit_ids for recap fight selection. A recap’s name is only a display label and does not filter its content.

Step 4: Poll the Recap

Highlight selection runs asynchronously after creation. Poll the recap ID returned by the create call:

curl -X GET "https://api.narrative-sports.com/v1/recaps/43" \
  -H "Authorization: Bearer YOUR_API_KEY"

While the recap is running, status may be "queued" or "processing". When status is "complete", the response includes otio_timeline and, if render_video was "ffmpeg", video_url:

{
  "id": 43,
  "status": "complete",
  "project_id": 1234,
  "target_duration_seconds": 60,
  "render_video": "ffmpeg",
  "video_url": "https://cdn.narrative-sports.com/recaps/43/recap.mp4?X-Goog-Signature=...",
  "otio_timeline": {
    "OTIO_SCHEMA": "Timeline.1",
    "name": "Highlight package (3 clips)"
  },
  "duration": 58.2,
  "num_clips": 3,
  "selected_edit_ids": ["edit-1", "edit-2", "edit-3"],
  "thumbnail_url": "https://cdn.narrative-sports.com/recaps/43/thumbnail.jpg?X-Goog-Signature=...",
  "created_at": "2025-01-15T14:00:00Z"
}

If no highlights match your filters, or a matched highlight is missing otio_edit, the recap transitions to status: "failed" with a failure_reason explaining what went wrong.

Step 5: List Recaps for a Dashboard

If you are building a UI that shows all recaps for an account, list them in one call instead of polling each ID:

curl -X GET "https://api.narrative-sports.com/v1/recaps" \
  -H "Authorization: Bearer YOUR_API_KEY"

Recaps are returned newest first; see List Recaps for the response shape.

Next Steps

Create Recap

Full request and response reference

Get Recap

Poll status and retrieve results

Get Project Highlight Options

Discover event types, fights, players, and highlight IDs

OTIO Format

Understand the recap EDL format

Introduction

Concepts

Prerequisites

Overview

Step 1: Get the Project ID

Step 2: Discover Highlight Options

Step 3: Create a Recap

Recap Duration

Create a Single-Fight Recap

Step 4: Poll the Recap

Step 5: List Recaps for a Dashboard

Next Steps

Create Recap

Get Recap

Get Project Highlight Options

OTIO Format

​Prerequisites

​Overview

​Step 1: Get the Project ID

​Step 2: Discover Highlight Options

​Step 3: Create a Recap

​Recap Duration

​Create a Single-Fight Recap

​Step 4: Poll the Recap

​Step 5: List Recaps for a Dashboard

​Next Steps

Create Recap

Get Recap

Get Project Highlight Options

OTIO Format

Prerequisites

Overview

Step 1: Get the Project ID

Step 2: Discover Highlight Options

Step 3: Create a Recap

Recap Duration

Create a Single-Fight Recap

Step 4: Poll the Recap

Step 5: List Recaps for a Dashboard

Next Steps