---
updatedAt: 2025-10-08T18:29:39.000Z
agentTools:
  projectIndex: https://docs.uplynk.com/llms.txt
---

# Live Slicer

v2

The **Live Slicer API** allows you to:

* Mark ads, replacement content, or content boundaries.
* Set metadata on an asset.
* Retrieve detailed Live Slicer status information.

The API is exposed via an internal web server in the [Live Slicer](https://docs.uplynk.com/reference/on-prem-slicer) and can be called from any programming language with an HTTP client interface.

### Choosing Between Live Slicer API and Slicer API

| API                 | Use Case                                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Live Slicer API** | Use when you need to control stream behavior (e.g., marking ads, setting metadata, retrieving slicer status). |
| **Slicer API**      | Use when retrieving the last known status of one or more Live Slicers or updating slicing schedules.          |

***

## API Conventions

* Uses `POST` or `GET` HTTP methods.
* Most endpoints do not require query string parameters.
* Request body must be a serialized JSON object.
* Responses include a JSON object with an `error` field:
  * `0` indicates success.
  * Non-zero values indicate errors, often accompanied by a `msg` field.

***

## Authentication

Authentication is required for **Live Slicer version 15091000 or higher**. By default, authentication is disabled but can be enabled via the [authenticated\_api\_port configuration parameter](https://docs.uplynk.com/reference/on-prem-slicer#configuration-file-settings). Requests over this port are **unencrypted**.

### Authentication Parameters

| Parameter   | Description                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| `timestamp` | 10-second authentication window (Unix time).                                    |
| `cnonce`    | Unique integer value.                                                           |
| `sig`       | Base-64-encoded SHA-1 hash of `Endpoint:Timestamp:cnonce:Authentication Token`. |

### Finding Your API Key

1. Navigate to [Integration Keys](https://cms.uplynk.com/static/cms2/index.html#/settings/integration-keys).
2. API keys are listed under the **API Keys** section.

***

## Authentication Example

### Sample Request (HTTP)

```
POST /content_start HTTP/1.1
Content-Type: application/json
Host: localhost:65009
Content-Length: 108

{
  "timestamp": 1438101883,
  "cnonce": 123,
  "sig": "49bQGXKTRYPQ5b22m89zKe1zcKk=",
  "start_timecode": "11:22:33;04"
}
```

### Sample Request (Python)

```python
import urllib2, hashlib, time, json, base64

secret = hashlib.sha1('XH7HtD8tR3993IxfbcqX0uhKnc-mYksmPxqM2z1a').hexdigest()
timestamp = int(time.time())
endpoint = '/content_start'
cnonce = 123
sig_input = f"{endpoint}:{timestamp}:{cnonce}:{secret}"
sig = base64.b64encode(hashlib.sha1(sig_input).digest())
body = json.dumps({"timestamp": timestamp, "cnonce": cnonce, "sig": sig })
request = urllib2.urlopen('http://localhost:65009/' + endpoint, body)
response = json.loads(request.read())

assert response['error'] == 0
```

<br />

## Port Configuration

By default, the Live Slicer listens for API requests on **port 65009**. You can modify this by updating the [api\_port configuration setting](https://docs.uplynk.com/reference/on-prem-slicer#configuration-file-settings).

***

## Scheduling Actions

You can schedule when an API request takes effect using one of the following parameters:

| Parameter            | Description                                                                    |
| -------------------- | ------------------------------------------------------------------------------ |
| `start_timecode`     | Identifies the video frame when an operation will take effect.                 |
| `offset_time_ms`     | Identifies a time relative to now (local system time), in milliseconds.        |
| `offset_from_now_ms` | Identifies a time relative to the start of the current asset, in milliseconds. |

Most Live Slicer API endpoints accept these parameters.

### Timecode

`start_timecode` specifies the exact video frame where an action should occur. The format follows:

* **Drop frame:** `hh:mm:ss;vf`
* **Non-drop frame:** `hh:mm:ss:vf`

Example: `00:15:02;01` marks the second frame at 15 minutes and two seconds after midnight.

For UDP and RTMP sources, enable the [useSystemClockAsTimecode setting](https://docs.uplynk.com/reference/on-prem-slicer#configuration-file-settings).

### Resolving Timecodes

* If the requested timecode exists in the capture delay buffer, the Live Slicer applies the action at that frame's **presentation timestamp (PTS)**.
* If not, the Live Slicer applies the action at the **oldest frame** in the buffer.
* Configure the buffer duration via [capture\_delay](https://docs.uplynk.com/reference/on-prem-slicer#configuration-file-settings).

#### Future Timecodes

Enable [future\_timecodes](https://docs.uplynk.com/reference/on-prem-slicer#configuration-file-settings) to schedule actions up to **12 hours in the future**.

| Condition                                    | Behavior                                                                    |
| -------------------------------------------- | --------------------------------------------------------------------------- |
| Timecode exists in buffer                    | Action occurs at the specified frame.                                       |
| Future timecode (<12 hours)                  | API returns an `id` response; action occurs at the specified time.          |
| Future timecode (>12 hours) or missing frame | Action takes effect immediately.                                            |
| Past timecode                                | SDI: Action occurs immediately. UDP/RTMP: Action occurs **24 hours later**. |

#### Scheduled Break Expiration

Configure the expiration of future breaks using [future\_break\_expiration\_minutes](https://docs.uplynk.com/reference/on-prem-slicer#configuration-file-settings).

| `drop_expired_breaks` Setting | Behavior                                                          |
| ----------------------------- | ----------------------------------------------------------------- |
| `On`                          | Expired API requests are ignored.                                 |
| `Off` or missing              | Expired requests are processed regardless of timecode expiration. |

View or delete scheduled breaks via remove\_break and list\_breaks.

***

## Relative Time Scheduling

An alternative to `start_timecode` is specifying relative time using:

| Parameter            | Description                                                           |
| -------------------- | --------------------------------------------------------------------- |
| `offset_from_now_ms` | Time relative to **now**, in milliseconds.                            |
| `offset_time_ms`     | Time relative to the **start of the current asset**, in milliseconds. |

**Precedence Order:** `offset_time_ms > offset_from_now_ms > start_timecode`

If none of these parameters are included, the action takes effect **immediately**.

***

## Examples

### Sample Request (HTTP)

```
POST /blackout HTTP/1.1
Content-Type: application/json
Host: localhost:65009
Content-Length: 33

{
  "start_timecode": "11:22:33;04"
}
```

### Sample Response (HTTP)

```
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 12

{
  "error": 0
}
```

### Sample Request (Python)

```python
import urllib2, json

body = json.dumps({"start_timecode": "11:22:33;04"})
request = urllib2.urlopen('http://localhost:65009/blackout', body)
response = json.loads(request.read())

assert response['error'] == 0
```

### Sample Request (cURL)

```
curl --data '{"start_timecode":"11:22:33;04"}' http://localhost:65009/blackout
```

***

## Endpoints

| Endpoint           | Description                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| `/add_cc608`       | Injects EIA/CEA-608/708 captions into the stream.                                              |
| `/add_imagebug`    | Schedules an image overlay.                                                                    |
| `/add_meta`        | Adds metadata to the currently sliced asset.                                                   |
| `/blackout`        | Ends the current asset and stops capturing until further notice. Resume with `/content_start`. |
| `/boundary`        | Creates and defines a content boundary.                                                        |
| `/content_start`   | Ends the current asset and starts a new one or resumes from blackout.                          |
| `/ignore_schedule` | Enables/disables ignore state for slicing schedules.                                           |
| `/list_breaks`     | Returns a list of scheduled breaks.                                                            |
| `/list_imagebug`   | Lists scheduled image overlays.                                                                |
| `/pod_end`         | Ends an ad pod and resumes capture.                                                            |
| `/pod_start`       | Marks an ad pod for replacement with an unknown duration.                                      |
| `/remove_break`    | Removes a break from the schedule.                                                             |
| `/remove_imagebug` | Removes an image overlay.                                                                      |
| `/replace_content` | Replaces a live stream section with pre-encoded content.                                       |
| `/replace_pod`     | Marks an ad pod for replacement with a specific duration.                                      |
| `/restart_later`   | Restarts the Live Slicer at the next ad break, blackout, or `/content_start`.                  |
| `/server_time`     | Returns the current time for the Live Slicer and CMS.                                          |
| `/state`           | Returns the Live Slicer's operating state.                                                     |
| `/status`          | Provides Live Slicer status details.                                                           |
| `/timedmeta`       | Inserts a timed metadata key/value pair into the stream.                                       |