Videos

Manage video resources. Videos are created automatically when a file is uploaded via S3 and the webhook is triggered.

List Videos

Returns a paginated list of videos for the authenticated user.

GET /api/videos

Query Parameters:

Parameter	Type	Description
page	integer	Page number
per_page	integer	Items per page

Response:

{
  "data": [
    {
      "id": 1,
      "ulid": "01HX...",
      "name": "my-video.mp4",
      "status": "completed",
      "duration": 120.5,
      "aspect_ratio": "16:9",
      "thumbnail_path": "videos/01HX.../thumbnail.jpg",
      "template_id": 1,
      "streams": [...],
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  }
}

Get Video

GET /api/videos/{ulid}

Returns a single video with its streams and outputs.

Response:

{
  "data": {
    "id": 1,
    "ulid": "01HX...",
    "name": "my-video.mp4",
    "status": "completed",
    "duration": 120.5,
    "aspect_ratio": "16:9",
    "thumbnail_path": "videos/01HX.../thumbnail.jpg",
    "template": { ... },
    "streams": [
      {
        "ulid": "01HY...",
        "type": "video",
        "width": 1920,
        "height": 1080,
        "size": 52428800
      }
    ],
    "outputs": [
      {
        "ulid": "01HZ...",
        "format": "hls",
        "status": "completed",
        "progress": 100,
        "streams": [...]
      }
    ]
  }
}

Update Video

PUT /api/videos/{ulid}

Request Body:

{
  "name": "Updated Video Name",
  "template_id": 2
}

Delete Video

Deletes the video, its streams, outputs, and associated S3 files.

DELETE /api/videos/{ulid}

Get Video Sources

Returns signed streaming URLs for the video. Requires an active proxy node.

GET /api/videos/{ulid}/sources

Response:

{
  "sources": [
    {
      "format": "hls",
      "url": "https://proxy.example.com/hls/..."
    },
    {
      "format": "dash",
      "url": "https://proxy.example.com/dash/..."
    },
    {
      "format": "mp4",
      "url": "https://proxy.example.com/proxy/..."
    }
  ]
}

Video Statuses

video.status reflects the ingestion pipeline phase. Check individual outputs[].status to see which encodings succeeded or failed.

Status	Description
pending	Uploaded, waiting to be dispatched
downloading	Source file being fetched
running	Segmentation and encoding in progress
uploading	Encoded chunks being assembled and uploaded to S3
completed	All outputs have reached a terminal state (at least one completed)
failed	Ingestion pipeline failed before any output could be produced

Output Statuses

Each output tracks its own encoding independently. A video can have some outputs completed and others failed at the same time — failed outputs can be deleted by the user while the video continues to function with the remaining completed outputs.

Status	Description
pending	Waiting for the encode batch to start
running	Chunks being encoded and uploaded
completed	Final file assembled and available in S3
failed	Concat or upload failed; output is unusable

Upload Flow

Videos are not created via a direct POST endpoint. Instead:

1. Initiate a multipart upload to S3 (see S3 Upload).
2. S3 triggers a webhook when the upload completes.
3. NukeVideo creates the video record and starts processing.

S3 Multipart Upload

These endpoints coordinate multipart uploads with S3:

Method	Endpoint	Description
GET	/api/s3/params	Get upload parameters
POST	/api/s3/multipart	Create multipart upload
GET	/api/s3/multipart/{uploadId}	Get uploaded parts
GET	/api/s3/multipart/{uploadId}/{partNumber}	Sign a part
POST	/api/s3/multipart/{uploadId}/complete	Complete upload
DELETE	/api/s3/multipart/{uploadId}	Abort upload

Upload Metadata

When creating an upload, you can pass optional metadata to associate the video with external systems:

{
  "filename": "video.mp4",
  "metadata": {
    "template": "01ABC...",
    "externalUserId": "user-123",
    "externalResourceId": "post-456"
  }
}

Field	Type	Description
metadata.template	string	Required. Template ULID to use for processing
metadata.externalUserId	string	Optional. ID of the user in your external system
metadata.externalResourceId	string	Optional. ID of the resource (post, product, etc.) in your external system

These fields are stored on the video record and returned in API responses as externalUserId and externalResourceId. The externalUserId is also recorded in usage tracking, allowing you to query per-user metrics via the Usage API.