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
Retrieve the current status and details of a highlight package. Poll this endpoint after creating a package to check processing status. The response includesotio_timeline once clip selection has completed. When render_video is "ffmpeg", video_url is added after rendering completes.
Request
curl -X GET "https://api.narrative-sports.com/v1/highlight-packages/42" \
-H "Authorization: Bearer YOUR_API_KEY"
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
package_id | integer | Yes | The package ID |
Response
{
"id": 42,
"status": "complete",
"project_ids": [1, 2, 3],
"target_duration_seconds": 120,
"render_video": "ffmpeg",
"editorial_prompt": "Focus on goals and dramatic moments",
"event_type_filter": ["goal", "penalty"],
"fight_filter": [
{ "project_id": 1, "fight_numbers": [3] }
],
"video_url": "https://cdn.narrative-sports.com/packages/42/package.mp4?X-Goog-Signature=...",
"otio_timeline": {
"OTIO_SCHEMA": "Timeline.1",
"name": "Multi-game highlight package (5 clips)"
},
"duration": 115.3,
"num_clips": 5,
"selected_edit_ids": ["edit-1", "edit-2", "edit-3", "edit-4", "edit-5"],
"thumbnail_url": "https://cdn.narrative-sports.com/packages/42/thumbnail.jpg?X-Goog-Signature=...",
"created_at": "2025-01-15T12:30:00Z"
}
Response Fields
| Field | Type | Description |
|---|---|---|
id | integer | Package ID |
status | string | "queued", "processing", "complete", or "failed" |
project_ids | integer[] | Project IDs included in this package |
target_duration_seconds | integer | Requested target duration |
render_video | string | "ffmpeg" or "none" |
editorial_prompt | string? | Editorial guidance provided at creation |
team_filter | string[]? | Team filter applied |
player_filter | string[]? | Player filter applied |
event_type_filter | string[]? | Event type filter applied |
fight_filter | object[]? | MMA fight filter applied at creation |
video_url | string? | Signed download URL for the rendered video when render_video is "ffmpeg" and rendering is complete |
otio_timeline | object? | Merged OTIO Timeline.1 EDL built from selected highlights’ otio_edit. Present after clip selection succeeds; null while queued/processing or when creation failed. See OTIO Format. |
duration | float? | Actual duration of the package in seconds |
num_clips | integer? | Number of highlight clips selected |
selected_edit_ids | string[]? | IDs of the highlights selected for the package; each package OTIO clip includes a matching metadata.edit_id |
thumbnail_url | string? | Signed thumbnail image URL |
failure_reason | string? | Error description when status is "failed" |
task_id | string? | Background task ID |
created_at | string? | ISO 8601 creation timestamp |
Errors
| Status | Description |
|---|---|
401 | Invalid or missing API key |
404 | Package not found or does not belong to the authenticated customer |