# Video segment service

Upon ingestion, every video is split into smaller segments. The Video Segment Service manages operations on videos at the segment-level.

OpenAPI file: [`VideoSegmentService.json`](https://dev.nominal.io/api/_downloads/f0bf943cbc14b696c1633dcb03dd2009/VideoSegmentService.json)

## Endpoints

### Create video file segments

POST `/video/v1/videos/{videoRid}/{videoFileRid}/create-segments`

Path parameters

`videoRid` string (RID) required
:   ​

`videoFileRid` string (RID) required
:   ​

Body

`requests` array of [`CreateSegment`](https://dev.nominal.io/api/rest/video-segment-service.md#createsegment)
:   ​

    Fields of `CreateSegment`

    `dataHandle` [`Handle`](https://dev.nominal.io/api/rest/video-segment-service.md#handle) required
    :   ​

        **s3**

        Set `type` to `"s3"`.

        `s3` string
        :   ​

    `frameRate` number required
    :   The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

    `durationSeconds` number required
    :   ​

    `timestamps` [`SegmentTimestamps`](https://dev.nominal.io/api/rest/video-segment-service.md#segmenttimestamps) required
    :   ​

        **timestampMappings**

        Set `type` to `"timestampMappings"`.

        `timestampMappings` [`TimestampMappings`](https://dev.nominal.io/api/rest/video-segment-service.md#timestampmappings)
        :   ​

            Fields of `TimestampMappings`

            `mediaTimestamps` array of number
            :   ​

            `absoluteTimestamps` array of [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp)
            :   ​

                Fields of `Timestamp`

                `seconds` integer (int64) required
                :   ​

                `nanos` integer (int64) required
                :   ​

    `segmentEndTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp) required
    :   ​

`seriesUuid` string (UUID)
:   ​

`overWriteSegments` boolean
:   If true, overlapping segments from other video files within the same video will be deleted before inserting new segments. The cached segment metadata for affected files will be recomputed.

Response

`segments` array of [`Segment`](https://dev.nominal.io/api/rest/video-segment-service.md#segment)
:   ​

    Fields of `Segment`

    `rid` string (RID)
    :   ​

    `videoRid` string (RID)
    :   ​

    `dataHandle` [`Handle`](https://dev.nominal.io/api/rest/video-segment-service.md#handle)
    :   ​

        **s3**

        Set `type` to `"s3"`.

        `s3` string
        :   ​

    `frameRate` number
    :   The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

    `durationSeconds` number
    :   The duration of a segment in media time.

    `timestamps` [`SegmentTimestamps`](https://dev.nominal.io/api/rest/video-segment-service.md#segmenttimestamps)
    :   for videos with frame-level timestamps, we provide mappings, otherwise we just include a single list of timestamps.

        **timestampMappings**

        Set `type` to `"timestampMappings"`.

        `timestampMappings` [`TimestampMappings`](https://dev.nominal.io/api/rest/video-segment-service.md#timestampmappings)
        :   ​

            Fields of `TimestampMappings`

            `mediaTimestamps` array of number
            :   ​

            `absoluteTimestamps` array of [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp)
            :   ​

                Fields of `Timestamp`

                `seconds` integer (int64)
                :   ​

                `nanos` integer (int64)
                :   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/<video file rid>/create-segments" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "requests": [
    {
      "dataHandle": {
        "type": "s3",
        "s3": "<s3 path>"
      },
      "frameRate": 1,
      "durationSeconds": 1,
      "timestamps": {
        "type": "timestampMappings",
        "timestampMappings": {
          "mediaTimestamps": [
            1
          ],
          "absoluteTimestamps": [
            {
              "seconds": 1,
              "nanos": 1
            }
          ]
        }
      },
      "segmentEndTimestamp": {
        "seconds": 1,
        "nanos": 1
      }
    }
  ],
  "seriesUuid": "<series uuid>",
  "overWriteSegments": true
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/<video file rid>/create-segments",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "requests": [
            {
                "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                "frameRate": 1,
                "durationSeconds": 1,
                "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                        "mediaTimestamps": [1],
                        "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                    },
                },
                "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
            },
        ],
        "seriesUuid": "<series uuid>",
        "overWriteSegments": True,
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/<video file rid>/create-segments",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "requests": [
            {
                "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                "frameRate": 1,
                "durationSeconds": 1,
                "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                        "mediaTimestamps": [1],
                        "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                    },
                },
                "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
            },
        ],
        "seriesUuid": "<series uuid>",
        "overWriteSegments": True,
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/<video file rid>/create-segments",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "requests": [
                    {
                        "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                        "frameRate": 1,
                        "durationSeconds": 1,
                        "timestamps": {
                            "type": "timestampMappings",
                            "timestampMappings": {
                                "mediaTimestamps": [1],
                                "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                            },
                        },
                        "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
                    },
                ],
                "seriesUuid": "<series uuid>",
                "overWriteSegments": True,
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "segments": [
    {
      "rid": "<segment rid>",
      "videoRid": "<video rid>",
      "dataHandle": {
        "type": "s3",
        "s3": "<s3 path>"
      },
      "frameRate": 1,
      "durationSeconds": 1,
      "timestamps": {
        "type": "timestampMappings",
        "timestampMappings": {
          "mediaTimestamps": [
            1
          ],
          "absoluteTimestamps": [
            {
              "seconds": 1,
              "nanos": 1
            }
          ]
        }
      }
    }
  ]
}
```

### Create video stream segments

POST `/video/v1/videos/{videoRid}/streams/{streamUuid}/create-segments`

Creates segments for a video stream. Similar to createVideoFileSegments but for streaming video.

Path parameters

`videoRid` string (RID) required
:   ​

`streamUuid` string (UUID) required
:   ​

Body

`requests` array of [`CreateSegment`](https://dev.nominal.io/api/rest/video-segment-service.md#createsegment)
:   ​

    Fields of `CreateSegment`

    `dataHandle` [`Handle`](https://dev.nominal.io/api/rest/video-segment-service.md#handle) required
    :   ​

        **s3**

        Set `type` to `"s3"`.

        `s3` string
        :   ​

    `frameRate` number required
    :   The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

    `durationSeconds` number required
    :   ​

    `timestamps` [`SegmentTimestamps`](https://dev.nominal.io/api/rest/video-segment-service.md#segmenttimestamps) required
    :   ​

        **timestampMappings**

        Set `type` to `"timestampMappings"`.

        `timestampMappings` [`TimestampMappings`](https://dev.nominal.io/api/rest/video-segment-service.md#timestampmappings)
        :   ​

            Fields of `TimestampMappings`

            `mediaTimestamps` array of number
            :   ​

            `absoluteTimestamps` array of [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp)
            :   ​

                Fields of `Timestamp`

                `seconds` integer (int64) required
                :   ​

                `nanos` integer (int64) required
                :   ​

    `segmentEndTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp) required
    :   ​

`seriesUuid` string (UUID)
:   ​

`overWriteSegments` boolean
:   If true, overlapping segments from other video files within the same video will be deleted before inserting new segments. The cached segment metadata for affected files will be recomputed.

Response

`segments` array of [`Segment`](https://dev.nominal.io/api/rest/video-segment-service.md#segment)
:   ​

    Fields of `Segment`

    `rid` string (RID)
    :   ​

    `videoRid` string (RID)
    :   ​

    `dataHandle` [`Handle`](https://dev.nominal.io/api/rest/video-segment-service.md#handle)
    :   ​

        **s3**

        Set `type` to `"s3"`.

        `s3` string
        :   ​

    `frameRate` number
    :   The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

    `durationSeconds` number
    :   The duration of a segment in media time.

    `timestamps` [`SegmentTimestamps`](https://dev.nominal.io/api/rest/video-segment-service.md#segmenttimestamps)
    :   for videos with frame-level timestamps, we provide mappings, otherwise we just include a single list of timestamps.

        **timestampMappings**

        Set `type` to `"timestampMappings"`.

        `timestampMappings` [`TimestampMappings`](https://dev.nominal.io/api/rest/video-segment-service.md#timestampmappings)
        :   ​

            Fields of `TimestampMappings`

            `mediaTimestamps` array of number
            :   ​

            `absoluteTimestamps` array of [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp)
            :   ​

                Fields of `Timestamp`

                `seconds` integer (int64)
                :   ​

                `nanos` integer (int64)
                :   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/streams/<stream uuid>/create-segments" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "requests": [
    {
      "dataHandle": {
        "type": "s3",
        "s3": "<s3 path>"
      },
      "frameRate": 1,
      "durationSeconds": 1,
      "timestamps": {
        "type": "timestampMappings",
        "timestampMappings": {
          "mediaTimestamps": [
            1
          ],
          "absoluteTimestamps": [
            {
              "seconds": 1,
              "nanos": 1
            }
          ]
        }
      },
      "segmentEndTimestamp": {
        "seconds": 1,
        "nanos": 1
      }
    }
  ],
  "seriesUuid": "<series uuid>",
  "overWriteSegments": true
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/streams/<stream uuid>/create-segments",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "requests": [
            {
                "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                "frameRate": 1,
                "durationSeconds": 1,
                "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                        "mediaTimestamps": [1],
                        "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                    },
                },
                "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
            },
        ],
        "seriesUuid": "<series uuid>",
        "overWriteSegments": True,
    },
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/streams/<stream uuid>/create-segments",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "requests": [
            {
                "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                "frameRate": 1,
                "durationSeconds": 1,
                "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                        "mediaTimestamps": [1],
                        "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                    },
                },
                "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
            },
        ],
        "seriesUuid": "<series uuid>",
        "overWriteSegments": True,
    },
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/streams/<stream uuid>/create-segments",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "requests": [
                    {
                        "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                        "frameRate": 1,
                        "durationSeconds": 1,
                        "timestamps": {
                            "type": "timestampMappings",
                            "timestampMappings": {
                                "mediaTimestamps": [1],
                                "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                            },
                        },
                        "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
                    },
                ],
                "seriesUuid": "<series uuid>",
                "overWriteSegments": True,
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "segments": [
    {
      "rid": "<segment rid>",
      "videoRid": "<video rid>",
      "dataHandle": {
        "type": "s3",
        "s3": "<s3 path>"
      },
      "frameRate": 1,
      "durationSeconds": 1,
      "timestamps": {
        "type": "timestampMappings",
        "timestampMappings": {
          "mediaTimestamps": [
            1
          ],
          "absoluteTimestamps": [
            {
              "seconds": 1,
              "nanos": 1
            }
          ]
        }
      }
    }
  ]
}
```

### Get segment by timestamp

POST `/video/v1/videos/{videoRid}/get-segment-by-timestamp`

**Deprecated:** Replaced by VideoService#getSegmentByTimestampV2, which addresses the video channel series (channel + tags) instead of a Video rid.

Returns metadata for the segment within a video containing the requested absolute timestamp.

Path parameters

`videoRid` string (RID) required
:   ​

Body

`timestamp` [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp) required
:   ​

    Fields of `Timestamp`

    `seconds` integer (int64) required
    :   ​

    `nanos` integer (int64) required
    :   ​

`viewRangeStart` [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp)
:   The start of the view range used to dynamically calculate media timestamps. The first segment with an overlap with the time bounds will have its minimum media timestamp set to 0, with every subsequent segment building media time cumulatively from that offset. This will determine the starting media timestamp of the returned segment. The view range should be the same as the one requested to get the playlist and segment summaries.

Response

`rid` string (RID)
:   ​

`videoRid` string (RID)
:   ​

`dataHandle` [`Handle`](https://dev.nominal.io/api/rest/video-segment-service.md#handle)
:   ​

    **s3**

    Set `type` to `"s3"`.

    `s3` string
    :   ​

`frameRate` number
:   The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

`durationSeconds` number
:   The duration of a segment in media time.

`timestamps` [`SegmentTimestamps`](https://dev.nominal.io/api/rest/video-segment-service.md#segmenttimestamps)
:   for videos with frame-level timestamps, we provide mappings, otherwise we just include a single list of timestamps.

    **timestampMappings**

    Set `type` to `"timestampMappings"`.

    `timestampMappings` [`TimestampMappings`](https://dev.nominal.io/api/rest/video-segment-service.md#timestampmappings)
    :   ​

        Fields of `TimestampMappings`

        `mediaTimestamps` array of number
        :   ​

        `absoluteTimestamps` array of [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp)
        :   ​

            Fields of `Timestamp`

            `seconds` integer (int64)
            :   ​

            `nanos` integer (int64)
            :   ​

When there is nothing to return, the response is HTTP 204 with no body.

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/get-segment-by-timestamp" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "timestamp": {
    "seconds": 1,
    "nanos": 1
  }
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/get-segment-by-timestamp",
    headers={"Authorization": "Bearer <api key>"},
    json={"timestamp": {"seconds": 1, "nanos": 1}},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/get-segment-by-timestamp",
    headers={"Authorization": "Bearer <api key>"},
    json={"timestamp": {"seconds": 1, "nanos": 1}},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/get-segment-by-timestamp",
            headers={"Authorization": "Bearer <api key>"},
            json={"timestamp": {"seconds": 1, "nanos": 1}},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<segment rid>",
  "videoRid": "<video rid>",
  "dataHandle": {
    "type": "s3",
    "s3": "<s3 path>"
  },
  "frameRate": 1,
  "durationSeconds": 1,
  "timestamps": {
    "type": "timestampMappings",
    "timestampMappings": {
      "mediaTimestamps": [
        1
      ],
      "absoluteTimestamps": [
        {
          "seconds": 1,
          "nanos": 1
        }
      ]
    }
  }
}
```

## Types

### CreateSegment

`dataHandle` [`Handle`](https://dev.nominal.io/api/rest/video-segment-service.md#handle) required
:   ​

`frameRate` number required
:   The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

`durationSeconds` number required
:   ​

`timestamps` [`SegmentTimestamps`](https://dev.nominal.io/api/rest/video-segment-service.md#segmenttimestamps) required
:   ​

`segmentEndTimestamp` [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp) required
:   ​

### Handle

Set `type` to the name of one of the other fields, and set only that field.

`s3` string
:   ​

### Segment

`rid` string (RID) required
:   ​

`videoRid` string (RID) required
:   ​

`dataHandle` [`Handle`](https://dev.nominal.io/api/rest/video-segment-service.md#handle) required
:   ​

`frameRate` number required
:   The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

`durationSeconds` number required
:   The duration of a segment in media time.

`timestamps` [`SegmentTimestamps`](https://dev.nominal.io/api/rest/video-segment-service.md#segmenttimestamps) required
:   for videos with frame-level timestamps, we provide mappings, otherwise we just include a single list of timestamps.

### SegmentTimestamps

A video segment will either contain timestamps or timestamp mappings depending on whether it is intended to be frame-mapped. Without a frame-timestamp mapping manifest file, a list of absolute timestamps will be automatically assigned to each segment based on media timestamps.. Otherwise, media timestamps will be extracted and mapped to those in the provided manifest.

Set `type` to the name of one of the other fields, and set only that field.

`timestampMappings` [`TimestampMappings`](https://dev.nominal.io/api/rest/video-segment-service.md#timestampmappings)
:   ​

### Timestamp

Deprecated for new APIs. Use google.protobuf.Timestamp for absolute instants in proto APIs.

This legacy nanosecond precision timestamp type is represented by an epoch time in seconds and a nanosecond offset. The nanosecond offset is from the start of the epoch second, so must be less than 1 billion.

`seconds` integer (int64) required
:   ​

`nanos` integer (int64) required
:   ​

### TimestampMappings

contains 2 equal-length lists, which contain the video media time and user-provided absolute time for the frame at each index. Enables frame-mapping on the front-end.

`mediaTimestamps` array of number
:   ​

`absoluteTimestamps` array of [`Timestamp`](https://dev.nominal.io/api/rest/video-segment-service.md#timestamp)
:   ​

Page design based on [Scalar](https://scalar.com), MIT License.