Quickstart

Prerequisites

Before you begin, you’ll need:

An API key — create and manage keys in the API Dashboard
An SRT-capable encoder/streaming tool (for SRT ingest), or a reachable HLS manifest
An input stream that meets the Video Input Requirements

Overview

The Narrative Sports API processes live video and generates highlight clips in your dashboard at app.narrative-sports.com. Choose either:

SRT — push your stream to a URL returned by Narrative.
HLS — provide a manifest URL for Narrative to pull.

Step 1: Choose a Transport

Create a task

Narrative returns an srt_url for your encoder.

curl -X POST "https://api.narrative-sports.com/v1/tasks/create-task" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sport": "soccer",
    "source_type": "srt_listener",
    "render_videos": {
      "render_video": "ffmpeg"
    }
  }'

{
  "success": "success",
  "task_id": "YOUR_TASK_ID",
  "srt_url": "YOUR_SRT_URL"
}

Stream to Narrative

Point your encoder at the returned srt_url and send the stream in real-time (1x speed).

Use the complete srt_url exactly as returned. It contains the per-task host and encryption passphrase and is valid only for that task.

With FFmpeg:

ffmpeg -re -i "YOUR_PATH_TO_FILE" -map 0:v:0 -map 0:a:0 -c copy -f mpegts "YOUR_SRT_URL"

-c copy requires H.264 / AVC input. For AV1 or VP9, transcode:

ffmpeg -re -i "YOUR_PATH_TO_FILE" \
  -map 0:v:0 -map 0:a:0 \
  -c:v libx264 -preset veryfast -b:v 6000k -maxrate 6000k -bufsize 12000k \
  -c:a aac -b:a 128k \
  -f mpegts "YOUR_SRT_URL"

With OBS: Add a custom SRT output using the full srt_url.With a hardware encoder: Use TS over SRT in Caller mode, with the host, port, encryption, and passphrase from the returned URL.

Create a task

Provide a reachable manifest. Narrative begins pulling it immediately.

curl -X POST "https://api.narrative-sports.com/v1/tasks/create-task" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sport": "soccer",
    "source_type": "hls_pull",
    "source_url": "https://example.com/live/index.m3u8",
    "source_start": {
      "mode": "live_edge"
    },
    "render_videos": {
      "render_video": "ffmpeg"
    }
  }'

{
  "success": "success",
  "task_id": "YOUR_TASK_ID"
}

Use an offset or program_date_time when you need a specific HLS start position.

Save the task_id to look up the generated project and stop the task later. Pass render_videos.render_video = "ffmpeg" to render and upload clips. OTIO edit data is generated automatically. See Create Task for all options.

The legacy Warmup + Assign Task flow is still supported for backward compatibility, but new integrations should prefer /create-task.

Input requirements for reliable results:

Video must be H.264 / AVC. AV1 and VP9 are not supported — transcode to H.264 first (see above).
Include both video and audio streams (-map 0:v:0 -map 0:a:0). Audio-less streams can fail ingest.
Include clear spoken commentary audio. Commentary is not the same as simply having an audio track.
Crowd/noise-only audio may ingest, but won’t produce highlights.
For portrait cropping, use a minimum source bitrate of 3000 kb/s.

Step 2: Watch Highlights Appear

Head to app.narrative-sports.com and log in to the account associated with the API key. As the stream is processed, highlight clips will appear in your project in real time. You can review, play back, and download clips directly from the dashboard.

Not seeing any highlights? Check the common causes — including missing commentary, unsupported languages, and audio level issues.

Step 3: Get the Project ID

Use the task info endpoint to retrieve the generated project_id:

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

Response:

{
  "success": "success",
  "task": {
    "task_id": "YOUR_TASK_ID",
    "project_id": 1234,
    "task_status": "running"
  }
}

Use task.project_id when creating a game recap or highlight package. If project_id is null, the worker has not linked the project yet; retry GET /tasks/{task_id}/info after the task has started producing project data.

Step 4: Stop the Task

When you’re done, kill the task to stop processing and release the worker. By default this is graceful (the task enters stopping and drains already-submitted renders):

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

If you need an immediate hard stop, disable render draining:

curl -X POST "https://api.narrative-sports.com/v1/tasks/YOUR_TASK_ID/kill" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wait_for_renders": false
  }'

Next Steps

OTIO Format

Get frame-accurate edit points with OpenTimelineIO output

Dashboard

Learn more about the dashboard and project management

Create Highlight Packages

Create packages from project IDs, filters, and selected highlights

API Reference

Full endpoint documentation

Introduction

Concepts

Prerequisites

Overview

Step 1: Choose a Transport

Create a task

Stream to Narrative

Create a task

Step 2: Watch Highlights Appear

Step 3: Get the Project ID

Step 4: Stop the Task

Next Steps

OTIO Format

Dashboard

Create Highlight Packages

API Reference

​Prerequisites

​Overview

​Step 1: Choose a Transport

​Create a task

​Stream to Narrative

​Create a task

​Step 2: Watch Highlights Appear

​Step 3: Get the Project ID

​Step 4: Stop the Task

​Next Steps

OTIO Format

Dashboard

Create Highlight Packages

API Reference

Prerequisites

Overview

Step 1: Choose a Transport

Create a task

Stream to Narrative

Create a task

Step 2: Watch Highlights Appear

Step 3: Get the Project ID

Step 4: Stop the Task

Next Steps