Mux.comDashboard
GuidesAPI Reference

Assets

An asset refers to a piece of media content that is stored or is being live streamed through the Mux system. An asset always has a duration and one or more tracks (audio, video, and text data).

The media content of an asset cannot be updated once created, however an asset can be used to create another asset, and can be modified within that process.

Properties
id.
string

Unique identifier for the Asset. Max 255 characters.

created_at.
string

Time the Asset was created, defined as a Unix timestamp (seconds since epoch).

status.
string
Possible values: "preparing" "ready" "errored"

The status of the asset.

duration.
number

The duration of the asset in seconds (max duration for a single asset is 24 hours).

max_stored_resolution.
string
Possible values: "Audio only" "SD" "HD" "FHD" "UHD"

The maximum resolution that has been stored for the asset. The asset may be delivered at lower resolutions depending on the device and bandwidth, however it cannot be delivered at a higher value than is stored.

max_stored_frame_rate.
number

The maximum frame rate that has been stored for the asset. The asset may be delivered at lower frame rates depending on the device and bandwidth, however it cannot be delivered at a higher value than is stored. This field may return -1 if the frame rate of the input cannot be reliably determined.

aspect_ratio.
string

The aspect ratio of the asset in the form of width:height, for example 16:9.

playback_ids.
array

An array of Playback ID objects. Use these to create HLS playback URLs. See Play your videos for more details.

playback_ids[].id.
string

Unique identifier for the PlaybackID

playback_ids[].policy.
string
Possible values: "public" "signed"

  • public playback IDs are accessible by constructing an HLS url like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDS should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

tracks.
array

The individual media tracks that make up an asset.

tracks[].id.
string

Unique identifier for the Track

tracks[].type.
string
Possible values: "video" "audio" "text"

The type of track

tracks[].duration.
number

The duration in seconds of the track media. This parameter is not set for the text type track. This field is optional and may not be set. The top level duration field of an asset will always be set.

tracks[].max_width.
integer

The maximum width in pixels available for the track. Only set for the video type track.

tracks[].max_height.
integer

The maximum height in pixels available for the track. Only set for the video type track.

tracks[].max_frame_rate.
number

The maximum frame rate available for the track. Only set for the video type track. This field may return -1 if the frame rate of the input cannot be reliably determined.

tracks[].max_channels.
integer

The maximum number of audio channels the track supports. Only set for the audio type track.

tracks[].max_channel_layout.
string
Possible values: "mono" "stereo" "5.2" "7.1"

Only set for the audio type track.

tracks[].text_type.
string
Possible values: "subtitles"

This parameter is set only for the text type track.

tracks[].language_code.
string

The language code value represents BCP 47 specification compliant value. For example, en for English or en-US for the US version of English. This parameter is set for text type and subtitles text type track.

tracks[].name.
string

The name of the track containing a human-readable description. The hls manifest will associate a subtitle text track with this value. For example, the value is "English" for subtitles text track for the language_code value of en-US. This parameter is set for the text type and subtitles text type track.

tracks[].closed_captions.
boolean

Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH). This parameter is set for the text type and subtitles text type track.

tracks[].passthrough.
string

Arbitrary metadata set for the track either when creating the asset or track. This parameter is set for text type and subtitles text type track. Max 255 characters.

errors.
object

Object that describes any errors that happened when processing this asset.

errors.type.
string

The type of error that occurred for this asset.

errors.messages.
array

Error messages with more details.

per_title_encode.
boolean
is_live.
boolean

Whether the asset is created from a live stream and the live stream is currently active and not in idle state.

passthrough.
string

Arbitrary metadata set for the asset. Max 255 characters.

live_stream_id.
string

Unique identifier for the live stream. This is an optional parameter added when the asset is created from a live stream.

master.
object

An object containing the current status of Master Access and the link to the Master MP4 file when ready. This object does not exist if master_acess is set to none and when the temporary URL expires.

master.status.
string
Possible values: "ready" "preparing" "errored"
master.url.
string

The temporary URL to the master version of the video, as an MP4 file. This URL will expire after 24 hours.

master_access.
string (default: none)
Possible values: "temporary" "none"
mp4_support.
string (default: none)
Possible values: "standard" "none"
source_asset_id.
string

Asset Identifier of the video used as the source for creating the clip.

normalize_audio.
boolean

Normalize the audio track loudness level. This parameter is only applicable to on-demand (not live) assets.

static_renditions.
object

An object containing the current status of any static renditions (mp4s). The object does not exist if no static renditions have been requested. See Download your videos for more information.

static_renditions.status.
string (default: disabled)
Possible values: "ready" "preparing" "disabled" "errored"

Indicates the status of downloadable MP4 versions of this asset.

static_renditions.files.
array

Array of file objects.

static_renditions.files[].name.
string
Possible values: "low.mp4" "medium.mp4" "high.mp4" "audio.m4a"
static_renditions.files[].ext.
string
Possible values: "mp4" "m4a"

Extension of the static rendition file

static_renditions.files[].height.
integer

The height of the static rendition's file in pixels

static_renditions.files[].width.
integer

The width of the static rendition's file in pixels

static_renditions.files[].bitrate.
integer

The bitrate in bits per second

static_renditions.files[].filesize.
string

The file size in bytes

recording_times.
array

An array of individual live stream recording sessions. A recording session is created on each encoder connection during the live stream

recording_times[].started_at.
string

The time at which the recording for the live stream started. The time value is Unix epoch time represented in ISO 8601 format.

recording_times[].duration.
number

The duration of the live stream recorded. The time value is in seconds.

non_standard_input_reasons.
object

An object containing one or more reasons the input file is non-standard. See the guide on minimizing processing time for more information on what a standard input is defined as. This object only exists on on-demand assets that have non-standard inputs, so if missing you can assume the input qualifies as standard.

non_standard_input_reasons.video_codec.
string

The video codec used on the input file. For example, the input file encoded with hevc video codec is non-standard and the value of this parameter is hevc.

non_standard_input_reasons.audio_codec.
string

The audio codec used on the input file. Non-AAC audio codecs are non-standard.

non_standard_input_reasons.video_gop_size.
string
Possible values: "high"

The video key frame Interval (also called as Group of Picture or GOP) of the input file is high. This parameter is present when the gop is greater than 10 seconds.

non_standard_input_reasons.video_frame_rate.
string

The video frame rate of the input file. Video with average frames per second (fps) less than 10 or greater than 120 is non-standard. A -1 frame rate value indicates Mux could not determine the frame rate of the video track.

non_standard_input_reasons.video_resolution.
string

The video resolution of the input file. Video resolution higher than 2048 pixels on any one dimension (height or width) is considered non-standard, The resolution value is presented as width x height in pixels.

non_standard_input_reasons.pixel_aspect_ratio.
string

The video pixel aspect ratio of the input file.

non_standard_input_reasons.video_edit_list.
string
Possible values: "non-standard"

Video Edit List reason indicates that the input file's video track contains a complex Edit Decision List.

non_standard_input_reasons.audio_edit_list.
string
Possible values: "non-standard"

Audio Edit List reason indicates that the input file's audio track contains a complex Edit Decision List.

non_standard_input_reasons.unexpected_media_file_parameters.
string
Possible values: "non-standard"

A catch-all reason when the input file in created with non-standard encoding parameters.

test.
boolean

True means this live stream is a test asset. A test asset can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test assets created. Test assets are watermarked with the Mux logo, limited to 10 seconds, and deleted after 24 hrs.

Create an asset
post

Create a new Mux Video asset.

curl https://api.mux.com/video/v1/assets \
  -X POST \
  -d '{ "input": "https://muxed.s3.amazonaws.com/leds.mp4", "playback_policy": ["public"] }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
input
array

An array of objects that each describe an input file to be used to create the asset. As a shortcut, input can also be a string URL for a file when only one input file is used. See input[].url for requirements.

url
string

The web address of the file that Mux should download and use.

  • For subtitles text tracks, the url is the location of subtitle/captions file. Mux supports SubRip Text (SRT) and Web Video Text Tracks format for ingesting Subtitles and Closed Captions.
  • For Watermarking or Overlay, the url is the location of the watermark image.
  • When creating clips from existing Mux assets, the url is defined with mux://assets/{asset_id} template where asset_id is the Asset Identifier for creating the clip from.
overlay_settings
object

An object that describes how the image file referenced in url should be placed over the video (i.e. watermarking).

vertical_align
string
Possible values: "top" "middle" "bottom"

Where the vertical positioning of the overlay/watermark should begin from. Defaults to "top"

vertical_margin
string

The distance from the vertical_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'middle', a positive value will shift the overlay towards the bottom and and a negative value will shift it towards the top.

horizontal_align
string
Possible values: "left" "center" "right"

Where the horizontal positioning of the overlay/watermark should begin from.

horizontal_margin
string

The distance from the horizontal_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'center', a positive value will shift the image towards the right and and a negative value will shift it towards the left.

width
string

How wide the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the width will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If height is supplied with no width, the width will scale proportionally to the height.

height
string

How tall the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the height will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If width is supplied with no height, the height will scale proportionally to the width.

opacity
string

How opaque the overlay should appear, expressed as a percent. (Default 100%)

start_time
number

The time offset in seconds from the beginning of the video indicating the clip's starting marker. The default value is 0 when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

end_time
number

The time offset in seconds from the beginning of the video, indicating the clip's ending marker. The default value is the duration of the video when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

type
string
Possible values: "video" "audio" "text"

This parameter is required for the text track type.

text_type
string
Possible values: "subtitles"

Type of text track. This parameter only supports subtitles value. For more information on Subtitles / Closed Captions, see this blog post. This parameter is required for text track type.

language_code
string

The language code value must be a valid BCP 47 specification compliant value. For example, en for English or en-US for the US version of English. This parameter is required for text type and subtitles text type track.

name
string

The name of the track containing a human-readable description. This value must be unique across all text type and subtitles text type tracks. The hls manifest will associate a subtitle text track with this value. For example, the value should be "English" for subtitles text track with language_code as en. This optional parameter should be used only for text type and subtitles text type track. If this parameter is not included, Mux will auto-populate based on the input[].language_code value.

closed_captions
boolean

Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH). This optional parameter should be used for text type and subtitles text type tracks.

passthrough
string

This optional parameter should be used for text type and subtitles text type tracks.

playback_policy
array

An array of playback policy names that you want applied to this asset and available through playback_ids. Options include: "public" (anyone with the playback URL can stream the asset). And "signed" (an additional access token is required to play the asset). If no playback_policy is set, the asset will have no playback IDs and will therefore not be playable. For simplicity, a single string name can be used in place of the array in the case of only one playback policy.

Possible values: "public" "signed"

  • public playback IDs are accessible by constructing an HLS url like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDS should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

per_title_encode
boolean
passthrough
string

Arbitrary metadata that will be included in the asset details and related webhooks. Can be used to store your own ID for a video along with the asset. Max: 255 characters.

mp4_support
string
Possible values: "none" "standard"

Specify what level (if any) of support for mp4 playback. In most cases you should use our default HLS-based streaming playback ({playback_id}.m3u8) which can automatically adjust to viewers' connection speeds, but an mp4 can be useful for some legacy devices or downloading for offline playback. See the Download your videos guide for more information.

normalize_audio
boolean

Normalize the audio track loudness level. This parameter is only applicable to on-demand (not live) assets.

master_access
string
Possible values: "none" "temporary"

Specify what level (if any) of support for master access. Master access can be enabled temporarily for your asset to be downloaded. See the Download your videos guide for more information.

test
boolean

Marks the asset as a test asset when the value is set to true. A Test asset can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test assets created. Test asset are watermarked with the Mux logo, limited to 10 seconds, deleted after 24 hrs.

post
201
/video/v1/assets
Request
(application/json)
{
  "input": "https://muxed.s3.amazonaws.com/leds.mp4",
  "playback_policy": [
    "public"
  ]
}
Response
(application/json)
{
  "data": {
    "status": "preparing",
    "playback_ids": [
      {
        "policy": "public",
        "id": "uNbxnGLKJ00yfbijDO8COxTOyVKT01xpxW"
      }
    ],
    "mp4_support": "none",
    "master_access": "none",
    "id": "SqQnqz6s5MBuXGvJaUWdXuXM93J9Q2yv",
    "created_at": "1607452572"
  }
}
List assets
get

List all Mux assets.

curl https://api.mux.com/video/v1/assets \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

get
200
/video/v1/assets
Response
(application/json)
{
  "data": [
    {
      "tracks": [
        {
          "type": "video",
          "max_width": 1920,
          "max_height": 800,
          "max_frame_rate": 24,
          "id": "HK01Bq7FrEQmIu3QpRiZZ98HQOOZjm6BYyg17eEunlyo",
          "duration": 734.166667
        },
        {
          "type": "audio",
          "max_channels": 2,
          "max_channel_layout": "stereo",
          "id": "nNKHJqw2G9cE019AoK16CJr3O27gGnbtW4w525hJWqWw",
          "duration": 734.143991
        }
      ],
      "status": "ready",
      "playback_ids": [
        {
          "policy": "public",
          "id": "85g23gYz7NmQu02YsY81ihuod6cZMxCp017ZrfglyLCKc"
        }
      ],
      "mp4_support": "none",
      "max_stored_resolution": "HD",
      "max_stored_frame_rate": 24,
      "master_access": "none",
      "id": "8jd7M77xQgf2NzuocJRPYdSdEfY5dLlcRwFARtgQqU4",
      "duration": 734.25,
      "created_at": "1609869152",
      "aspect_ratio": "12:5"
    },
    {
      "tracks": [
        {
          "type": "video",
          "max_width": 1920,
          "max_height": 1080,
          "max_frame_rate": 29.97,
          "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4",
          "duration": 23.8238
        },
        {
          "type": "audio",
          "max_channels": 2,
          "max_channel_layout": "stereo",
          "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg",
          "duration": 23.823792
        }
      ],
      "status": "ready",
      "playback_ids": [
        {
          "policy": "public",
          "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I"
        }
      ],
      "mp4_support": "none",
      "max_stored_resolution": "HD",
      "max_stored_frame_rate": 29.97,
      "master_access": "none",
      "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68",
      "duration": 23.857167,
      "created_at": "1609868768",
      "aspect_ratio": "16:9"
    }
  ]
}
Retrieve an asset
get

Retrieves the details of an asset that has previously been created. Supply the unique asset ID that was returned from your previous request, and Mux will return the corresponding asset information. The same information is returned when creating an asset.

curl https://api.mux.com/video/v1/assets/${ASSET_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

get
200
/video/v1/assets/{ASSET_ID}
Response
(application/json)
{
  "data": {
    "tracks": [
      {
        "type": "video",
        "max_width": 1920,
        "max_height": 1080,
        "max_frame_rate": 29.97,
        "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4",
        "duration": 23.8238
      },
      {
        "type": "audio",
        "max_channels": 2,
        "max_channel_layout": "stereo",
        "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg",
        "duration": 23.823792
      }
    ],
    "status": "ready",
    "playback_ids": [
      {
        "policy": "public",
        "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I"
      }
    ],
    "mp4_support": "none",
    "max_stored_resolution": "HD",
    "max_stored_frame_rate": 29.97,
    "master_access": "none",
    "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68",
    "duration": 23.857167,
    "created_at": "1609868768",
    "aspect_ratio": "16:9"
  }
}
Delete an asset
del

Deletes a video asset and all its data

curl https://api.mux.com/video/v1/assets/${ASSET_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

del
204
/video/v1/assets/{ASSET_ID}
Retrieve asset input info
get

Returns a list of the input objects that were used to create the asset along with any settings that were applied to each input.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/input-info \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

get
200
/video/v1/assets/{ASSET_ID}/input-info
Response
(application/json)
{
  "data": [
    {
      "settings": {
        "url": "https://muxed.s3.amazonaws.com/leds.mp4"
      },
      "file": {
        "container_format": "mp4",
        "tracks": [
          {
            "type": "video",
            "duration": 120,
            "width": 1280,
            "height": 720,
            "frame_rate": 30,
            "encoding": "h.264"
          },
          {
            "type": "audio",
            "duration": 120,
            "sample_rate": 16000,
            "sample_size": 24,
            "encoding": "aac"
          }
        ]
      }
    },
    {
      "settings": {
        "url": "https://exmaple.com/myVideo_en.srt"
      },
      "file": {
        "container_format": "srt"
      }
    }
  ]
}
Create a playback ID
post
curl https://api.mux.com/video/v1/assets/${ASSET_ID}/playback-ids \
  -X POST \
  -d '{ "policy": "public" }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
policy
string
Possible values: "public" "signed"

  • public playback IDs are accessible by constructing an HLS url like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDS should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

Request path & query params
ASSET_ID
string

The asset ID.

post
201
/video/v1/assets/{ASSET_ID}/playback-ids
Request
(application/json)
{
  "policy": "public"
}
Response
(application/json)
{
  "data": {
    "policy": "public",
    "id": "Lj02VZDorh9hCV00flNqPli8fmwf6KEppug01w8zDEYVlQ"
  }
}
Retrieve a playback ID
get
curl https://api.mux.com/video/v1/assets/${ASSET_ID}/playback-ids/${PLAYBACK_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

PLAYBACK_ID
string

The live stream's playback ID.

get
200
/video/v1/assets/{ASSET_ID}/playback-ids/{PLAYBACK_ID}
Response
(application/json)
{
  "data": {
    "policy": "public",
    "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I"
  }
}
Delete a playback ID
del
curl https://api.mux.com/video/v1/assets/${ASSET_ID}/playback-ids/${PLAYBACK_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

PLAYBACK_ID
string

The live stream's playback ID.

del
204
/video/v1/assets/{ASSET_ID}/playback-ids/{PLAYBACK_ID}
Update MP4 support
put

Allows you to add or remove mp4 support for assets that were created without it. Currently there are two values supported in this request, standard and none. none means that an asset does not have mp4 support, so submitting a request with mp4_support set to none will delete the mp4 assets from the asset in question.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/mp4-support \
  -X PUT \
  -d '{ "mp4_support": "standard" }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
mp4_support
string
Possible values: "standard" "none"

String value for the level of mp4 support

Request path & query params
ASSET_ID
string

The asset ID.

put
200
/video/v1/assets/{ASSET_ID}/mp4-support
Request
(application/json)
{
  "mp4_support": "standard"
}
Response
(application/json)
{
  "data": {
    "tracks": [
      {
        "type": "video",
        "max_width": 1920,
        "max_height": 1080,
        "max_frame_rate": 29.97,
        "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4",
        "duration": 23.8238
      },
      {
        "type": "audio",
        "max_channels": 2,
        "max_channel_layout": "stereo",
        "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg",
        "duration": 23.823792
      }
    ],
    "status": "ready",
    "static_renditions": {
      "status": "preparing"
    },
    "playback_ids": [
      {
        "policy": "public",
        "id": "Lj02VZDorh9hCV00flNqPli8fmwf6KEppug01w8zDEYVlQ"
      }
    ],
    "mp4_support": "standard",
    "max_stored_resolution": "HD",
    "max_stored_frame_rate": 29.97,
    "master_access": "none",
    "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68",
    "duration": 23.857167,
    "created_at": "1609868768",
    "aspect_ratio": "16:9"
  }
}
Update master access
put

Allows you to add temporary access to the master (highest-quality) version of the asset in MP4 format. A URL will be created that can be used to download the master version for 24 hours. After 24 hours Master Access will revert to "none". This master version is not optimized for web and not meant to be streamed, only downloaded for purposes like archiving or editing the video offline.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/master-access \
  -X PUT \
  -d '{ "master_access": "temporary" }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
master_access
string
Possible values: "temporary" "none"

Add or remove access to the master version of the video.

Request path & query params
ASSET_ID
string

The asset ID.

put
200
/video/v1/assets/{ASSET_ID}/master-access
Request
(application/json)
{
  "master_access": "temporary"
}
Response
(application/json)
{
  "data": {
    "tracks": [
      {
        "type": "video",
        "max_width": 1920,
        "max_height": 1080,
        "max_frame_rate": 29.97,
        "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4",
        "duration": 23.8238
      },
      {
        "type": "audio",
        "max_channels": 2,
        "max_channel_layout": "stereo",
        "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg",
        "duration": 23.823792
      }
    ],
    "status": "ready",
    "playback_ids": [
      {
        "policy": "public",
        "id": "Lj02VZDorh9hCV00flNqPli8fmwf6KEppug01w8zDEYVlQ"
      }
    ],
    "mp4_support": "none",
    "max_stored_resolution": "HD",
    "max_stored_frame_rate": 29.97,
    "master_access": "temporary",
    "master": {
      "status": "preparing"
    },
    "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68",
    "duration": 23.857167,
    "created_at": "1609868768",
    "aspect_ratio": "16:9"
  }
}
Create an asset track
post
curl https://api.mux.com/video/v1/assets/${ASSET_ID}/tracks \
  -X POST \
  -d '{ "url": "https://example.com/myVIdeo_en.srt", "type": "text", "text_type": "subtitles", "closed_captions": true, "language_code": "en-US", "name": "English",  "passthrough": "English" }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
url
string
type
string
Possible values: "text"
text_type
string
Possible values: "subtitles"
language_code
string

The language code value must be a valid BCP 47 specification compliant value. For example, en for English or en-US for the US version of English.

name
string

The name of the track containing a human-readable description. This value must be unqiue across all the text type and subtitles text type tracks. HLS manifest will associate subtitle text track with this value. For example, set the value to "English" for subtitles text track with language_code as en-US. If this parameter is not included, Mux will auto-populate based on the language_code value.

closed_captions
boolean

Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH).

passthrough
string

Arbitrary metadata set for the track either when creating the asset or track.

Request path & query params
ASSET_ID
string

The asset ID.

post
201
/video/v1/assets/{ASSET_ID}/tracks
Request
(application/json)
{
  "url": "https://example.com/myVideo_en.srt",
  "type": "text",
  "text_type": "subtitles",
  "language_code": "en-US",
  "name": "English",
  "closed_captions": true,
  "passthrough": "English"
}
Response
(application/json)
{
  "data": {
    "type": "text",
    "text_type": "subtitles",
    "status": "preparing",
    "passthrough": "English",
    "name": "English",
    "language_code": "en-US",
    "id": "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw",
    "closed_captions": true
  }
}
Delete an asset track
del
curl https://api.mux.com/video/v1/assets/${ASSET_ID}/tracks/${TRACK_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

TRACK_ID
string

The track ID.

del
204
/video/v1/assets/{ASSET_ID}/tracks/{TRACK_ID}

Live Streams

A Live Stream represents a unique live stream of video being pushed to Mux. It includes configuration details (a Stream Key) for live broadcasting software/hardware and a Playback ID for playing the stream anywhere. Currently, RTMP is the only supported method of ingesting video. Use rtmp://global-live.mux.com:5222/app with the Live Stream's Stream Key for getting the video into Mux, and use https://stream.mux.com with the Live Stream's Playback ID for playback.

A Live Stream can be used once for a specific event, or re-used forever. If you're building an application like Facebook Live or Twitch, you could create one Live Stream per user. This allows them the configure their broadcasting software once, and the Live Stream Playback ID will always show their latest stream.

Each RTMP session creates a new video asset automatically. You can set up a webhook to be notified each time a broadcast (or Live Stream RTMP session) begins or ends with the video.live_stream.active and video.live_stream.idle events respectively. Assets that are created from a Live Stream have the same behavior as other Assets you create.

Learn more about how to go live in our guides.

Properties
id.
string

Unique identifier for the Live Stream. Max 255 characters.

created_at.
string

Time the Live Stream was created, defined as a Unix timestamp (seconds since epoch).

stream_key.
string

Unique key used for streaming to a Mux RTMP endpoint. This should be considered as sensitive as credentials, anyone with this stream key can begin streaming.

active_asset_id.
string

The Asset that is currently being created if there is an active broadcast.

recent_asset_ids.
array

An array of strings with the most recent Assets that were created from this live stream.

status.
string
Possible values: "active" "idle" "disabled"

idle indicates that there is no active broadcast. active indicates that there is an active broadcast and disabled status indicates that no future RTMP streams can be published.

playback_ids.
array

An array of Playback ID objects. Use these to create HLS playback URLs. See Play your videos for more details.

playback_ids[].id.
string

Unique identifier for the PlaybackID

playback_ids[].policy.
string
Possible values: "public" "signed"

  • public playback IDs are accessible by constructing an HLS url like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDS should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

new_asset_settings.
object

The settings to be used when creating a new asset. You can use any of the usual settings when creating an asset normally, with the exception to not include file url for creating the asset in input. You could optionally add overlay_setting and input urls to add Subtitles / Captions.

passthrough.
string

Arbitrary metadata set for the asset. Max 255 characters.

reconnect_window.
number (default: 60)

When live streaming software disconnects from Mux, either intentionally or due to a drop in the network, the Reconnect Window is the time in seconds that Mux should wait for the streaming software to reconnect before considering the live stream finished and completing the recorded asset. Min: 0.1s. Max: 300s (5 minutes).

reduced_latency.
boolean

Latency is the time from when the streamer does something in real life to when you see it happen in the player. Set this if you want lower latency for your live stream. Note: Reconnect windows are incompatible with Reduced Latency and will always be set to zero (0) seconds. See the Reduce live stream latency guide to understand the tradeoffs.

simulcast_targets.
array

Each Simulcast Target contains configuration details to broadcast (or "restream") a live stream to a third-party streaming service. See the Stream live to 3rd party platforms guide.

simulcast_targets[].id.
string

ID of the Simulcast Target

simulcast_targets[].passthrough.
string

Arbitrary Metadata set when creating a simulcast target.

simulcast_targets[].status.
string
Possible values: "idle" "starting" "broadcasting" "errored"

The current status of the simulcast target. See Statuses below for detailed description.

  • idle: Default status. When the parent live stream is in disconnected status, simulcast targets will be idle state.
  • starting: The simulcast target transitions into this state when the parent live stream transition into connected state.
  • broadcasting: The simulcast target has successfully connected to the third party live streaming service and is pushing video to that service.
  • errored: The simulcast target encountered an error either while attempting to connect to the third party live streaming service, or mid-broadcasting. Compared to other errored statuses in the Mux Video API, a simulcast may transition back into the broadcasting state if a connection with the service can be re-established.
simulcast_targets[].stream_key.
string

Stream Key represents an stream identifier for the third party live streaming service to simulcast the parent live stream too.

simulcast_targets[].url.
string

RTMP hostname including the application name for the third party live streaming service.

test.
boolean

True means this live stream is a test live stream. Test live streams can be used to help evaluate the Mux Video APIs for free. There is no limit on the number of test live streams, but they are watermarked with the Mux logo, and limited to 5 minutes. The test live stream is disabled after the stream is active for 5 mins and the recorded asset also deleted after 24 hours.

Create a live stream
post
curl https://api.mux.com/video/v1/live-streams \
  -X POST \
  -d '{ "playback_policy": "public", "new_asset_settings": { "playback_policy": "public" } }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
playback_policy
array
Possible values: "public" "signed"

  • public playback IDs are accessible by constructing an HLS url like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDS should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

new_asset_settings
object
input
array

An array of objects that each describe an input file to be used to create the asset. As a shortcut, input can also be a string URL for a file when only one input file is used. See input[].url for requirements.

url
string

The web address of the file that Mux should download and use.

  • For subtitles text tracks, the url is the location of subtitle/captions file. Mux supports SubRip Text (SRT) and Web Video Text Tracks format for ingesting Subtitles and Closed Captions.
  • For Watermarking or Overlay, the url is the location of the watermark image.
  • When creating clips from existing Mux assets, the url is defined with mux://assets/{asset_id} template where asset_id is the Asset Identifier for creating the clip from.
overlay_settings
object

An object that describes how the image file referenced in url should be placed over the video (i.e. watermarking).

vertical_align
string
Possible values: "top" "middle" "bottom"

Where the vertical positioning of the overlay/watermark should begin from. Defaults to "top"

vertical_margin
string

The distance from the vertical_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'middle', a positive value will shift the overlay towards the bottom and and a negative value will shift it towards the top.

horizontal_align
string
Possible values: "left" "center" "right"

Where the horizontal positioning of the overlay/watermark should begin from.

horizontal_margin
string

The distance from the horizontal_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'center', a positive value will shift the image towards the right and and a negative value will shift it towards the left.

width
string

How wide the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the width will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If height is supplied with no width, the width will scale proportionally to the height.

height
string

How tall the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the height will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If width is supplied with no height, the height will scale proportionally to the width.

opacity
string

How opaque the overlay should appear, expressed as a percent. (Default 100%)

start_time
number

The time offset in seconds from the beginning of the video indicating the clip's starting marker. The default value is 0 when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

end_time
number

The time offset in seconds from the beginning of the video, indicating the clip's ending marker. The default value is the duration of the video when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

type
string
Possible values: "video" "audio" "text"

This parameter is required for the text track type.

text_type
string
Possible values: "subtitles"

Type of text track. This parameter only supports subtitles value. For more information on Subtitles / Closed Captions, see this blog post. This parameter is required for text track type.

language_code
string

The language code value must be a valid BCP 47 specification compliant value. For example, en for English or en-US for the US version of English. This parameter is required for text type and subtitles text type track.

name
string

The name of the track containing a human-readable description. This value must be unique across all text type and subtitles text type tracks. The hls manifest will associate a subtitle text track with this value. For example, the value should be "English" for subtitles text track with language_code as en. This optional parameter should be used only for text type and subtitles text type track. If this parameter is not included, Mux will auto-populate based on the input[].language_code value.

closed_captions
boolean

Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH). This optional parameter should be used for text type and subtitles text type tracks.

passthrough
string

This optional parameter should be used for text type and subtitles text type tracks.

playback_policy
array

An array of playback policy names that you want applied to this asset and available through playback_ids. Options include: "public" (anyone with the playback URL can stream the asset). And "signed" (an additional access token is required to play the asset). If no playback_policy is set, the asset will have no playback IDs and will therefore not be playable. For simplicity, a single string name can be used in place of the array in the case of only one playback policy.

Possible values: "public" "signed"

  • public playback IDs are accessible by constructing an HLS url like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDS should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

per_title_encode
boolean
passthrough
string

Arbitrary metadata that will be included in the asset details and related webhooks. Can be used to store your own ID for a video along with the asset. Max: 255 characters.

mp4_support
string
Possible values: "none" "standard"

Specify what level (if any) of support for mp4 playback. In most cases you should use our default HLS-based streaming playback ({playback_id}.m3u8) which can automatically adjust to viewers' connection speeds, but an mp4 can be useful for some legacy devices or downloading for offline playback. See the Download your videos guide for more information.

normalize_audio
boolean

Normalize the audio track loudness level. This parameter is only applicable to on-demand (not live) assets.

master_access
string
Possible values: "none" "temporary"

Specify what level (if any) of support for master access. Master access can be enabled temporarily for your asset to be downloaded. See the Download your videos guide for more information.

test
boolean

Marks the asset as a test asset when the value is set to true. A Test asset can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test assets created. Test asset are watermarked with the Mux logo, limited to 10 seconds, deleted after 24 hrs.

reconnect_window
number

When live streaming software disconnects from Mux, either intentionally or due to a drop in the network, the Reconnect Window is the time in seconds that Mux should wait for the streaming software to reconnect before considering the live stream finished and completing the recorded asset. Defaults to 60 seconds on the API if not specified.

passthrough
string
reduced_latency
boolean

Latency is the time from when the streamer does something in real life to when you see it happen in the player. Set this if you want lower latency for your live stream. Note: Reconnect windows are incompatible with Reduced Latency and will always be set to zero (0) seconds. Read more here: https://mux.com/blog/reduced-latency-for-mux-live-streaming-now-available/

test
boolean

Marks the live stream as a test live stream when the value is set to true. A test live stream can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test live streams created. Test live streams are watermarked with the Mux logo and limited to 5 minutes. The test live stream is disabled after the stream is active for 5 mins and the recorded asset also deleted after 24 hours.

simulcast_targets
array
passthrough
string

Arbitrary metadata set by you when creating a simulcast target.

stream_key
string

Stream Key represents a stream identifier on the third party live streaming service to send the parent live stream to.

url
string

RTMP hostname including application name for the third party live streaming service. Example: 'rtmp://live.example.com/app'.

post
201
/video/v1/live-streams
Request
(application/json)
{
  "playback_policy": "public",
  "new_asset_settings": {
    "playback_policy": "public"
  }
}
Response
(application/json)
{
  "data": {
    "stream_key": "abcdefgh",
    "status": "idle",
    "reconnect_window": 60,
    "playback_ids": [
      {
        "policy": "public",
        "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
      }
    ],
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ]
    },
    "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "created_at": "1609937654"
  }
}
List live streams
get
curl https://api.mux.com/video/v1/live-streams \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

get
200
/video/v1/live-streams
Response
(application/json)
{
  "data": [
    {
      "stream_key": "831b5bde-cd8a-5bc4-115d-4ba34b19f481",
      "status": "idle",
      "reconnect_window": 60,
      "playback_ids": [
        {
          "policy": "public",
          "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
        }
      ],
      "new_asset_settings": {
        "playback_policies": [
          "public"
        ]
      },
      "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
      "created_at": "1609937654"
    },
    {
      "stream_key": "d273c65e-1fc8-27dc-e9ef-56144cbceb3a",
      "status": "idle",
      "reconnect_window": 60,
      "recent_asset_ids": [
        "SZs02xxHgYdkHp00OSCjJiHUHqzVQZNU332XPXRxe341o",
        "e4J9cwb5tjVxMeeV8201dC00i800ThPKKGT2SEN002dHH2s"
      ],
      "playback_ids": [
        {
          "policy": "public",
          "id": "00zOcribkUmXqXHzBTpflk2771BRTcKATqPjWf7JHpuM"
        }
      ],
      "new_asset_settings": {
        "playback_policies": [
          "public"
        ]
      },
      "id": "B65hEUWW01ErVKDDGImKcBquYhwEAkjW6Ic3lPY0299Cc",
      "created_at": "1607587513"
    }
  ]
}
Retrieve a live stream
get

Retrieves the details of a live stream that has previously been created. Supply the unique live stream ID that was returned from your previous request, and Mux will return the corresponding live stream information. The same information is returned when creating a live stream.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

get
200
/video/v1/live-streams/{LIVE_STREAM_ID}
Response
(application/json)
{
  "data": {
    "stream_key": "831b5bde-cd8a-5bc4-115d-4ba34b19f481",
    "status": "idle",
    "reconnect_window": 60,
    "playback_ids": [
      {
        "policy": "public",
        "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
      }
    ],
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ]
    },
    "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "created_at": "1609937654"
  }
}
Delete a live stream
del
curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

del
204
/video/v1/live-streams/{LIVE_STREAM_ID}
Create a live stream playback ID
post
curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/playback-ids \
  -X POST \
  -d '{ "policy": "public" }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
policy
string
Possible values: "public" "signed"

  • public playback IDs are accessible by constructing an HLS url like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDS should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

Request path & query params
LIVE_STREAM_ID
string

The live stream ID

post
201
/video/v1/live-streams/{LIVE_STREAM_ID}/playback-ids
Request
(application/json)
{
  "policy": "signed"
}
Response
(application/json)
{
  "data": {
    "policy": "public",
    "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw"
  }
}
Delete a live stream playback ID
del
curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/playback-ids/${PLAYBACK_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

PLAYBACK_ID
string

The live stream's playback ID.

del
204
/video/v1/live-streams/{LIVE_STREAM_ID}/playback-ids/{PLAYBACK_ID}
Reset a live stream’s stream key
post

Reset a live stream key if you want to immediately stop the current stream key from working and create a new stream key that can be used for future broadcasts.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/reset-stream-key \
  -X POST \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

post
201
/video/v1/live-streams/{LIVE_STREAM_ID}/reset-stream-key
Response
(application/json)
{
  "data": {
    "stream_key": "acaf2ca1-ba9c-5ffe-8c9c-a02bbf0009a6",
    "status": "idle",
    "reconnect_window": 60,
    "playback_ids": [
      {
        "policy": "public",
        "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
      },
      {
        "policy": "public",
        "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw"
      }
    ],
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ]
    },
    "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "created_at": "1609937654"
  }
}
Signal a live stream is finished
put

(Optional) End the live stream recording immediately instead of waiting for the reconnect_window. EXT-X-ENDLIST tag is added to the HLS manifest which notifies the player that this live stream is over.

Mux does not close the encoder connection immediately. Encoders are often configured to re-establish connections immediately which would result in a new recorded asset. For this reason, Mux waits for 60s before closing the connection with the encoder. This 60s timeframe is meant to give encoder operators a chance to disconnect from their end.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/complete \
  -X PUT \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

put
200
/video/v1/live-streams/{LIVE_STREAM_ID}/complete
Response
(application/json)
{
  "data": {}
}
Disable a live stream
put

Disables a live stream, making it reject incoming RTMP streams until re-enabled. The API also ends the live stream recording immediately when active. Ending the live stream recording adds the EXT-X-ENDLIST tag to the HLS manifest which notifies the player that this live stream is over.

Mux also closes the encoder connection immediately. Any attempt from the encoder to re-establish connection will fail till the live stream is re-enabled.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/disable \
  -X PUT \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

put
200
/video/v1/live-streams/{LIVE_STREAM_ID}/disable
Response
(application/json)
{
  "data": {}
}
Enable a live stream
put

Enables a live stream, allowing it to accept an incoming RTMP stream.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/enable \
  -X PUT \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

put
200
/video/v1/live-streams/{LIVE_STREAM_ID}/enable
Response
(application/json)
{
  "data": {}
}
Create a live stream simulcast target
post

Create a simulcast target for the parent live stream. Simulcast target can only be created when the parent live stream is in idle state. Only one simulcast target can be created at a time with this API.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/simulcast-targets \
  -X POST \
  -d '{"url": "rtmp://live.example.com/app", "stream_key": "abcdefgh", "passthrough":"Example"}' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
passthrough
string

Arbitrary metadata set by you when creating a simulcast target.

stream_key
string

Stream Key represents a stream identifier on the third party live streaming service to send the parent live stream to.

url
string

RTMP hostname including application name for the third party live streaming service. Example: 'rtmp://live.example.com/app'.

Request path & query params
LIVE_STREAM_ID
string

The live stream ID

post
201
/video/v1/live-streams/{LIVE_STREAM_ID}/simulcast-targets
Request
(application/json)
{
  "url": "rtmp://live.example.com/app",
  "stream_key": "abcdefgh",
  "passthrough": "Example"
}
Response
(application/json)
{
  "data": {
    "url": "rtmp://live.example.com/app",
    "stream_key": "abcdefgh",
    "status": "idle",
    "passthrough": "Example",
    "id": "le1axfGDc9ETqh6trHNTxGQ9XEhj02fOnX0200aAh24fwlmwzqKCYNJgw"
  }
}
Delete a Live Stream Simulcast Target
del

Delete the simulcast target using the simulcast target ID returned when creating the simulcast target. Simulcast Target can only be deleted when the parent live stream is in idle state.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/simulcast-targets/${SIMULCAST_TARGET_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

SIMULCAST_TARGET_ID
string

The ID of the simulcast target.

del
204
/video/v1/live-streams/{LIVE_STREAM_ID}/simulcast-targets/{SIMULCAST_TARGET_ID}
Retrieve a Live Stream Simulcast Target
get

Retrieves the details of the simulcast target created for the parent live stream. Supply the unique live stream ID and simulcast target ID that was returned in the response of create simulcast target request, and Mux will return the corresponding information.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/simulcast-targets/${SIMULCAST_TARGET_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

SIMULCAST_TARGET_ID
string

The ID of the simulcast target.

get
200
/video/v1/live-streams/{LIVE_STREAM_ID}/simulcast-targets/{SIMULCAST_TARGET_ID}
Response
(application/json)
{
  "data": {
    "url": "rtmp://live.example.com/app",
    "stream_key": "abcdefgh",
    "status": "idle",
    "passthrough": "Example",
    "id": "02FU00rPq00fC9S6kygrqlxygGMdpW1lk00BkFpCfc2kGregEIr7brt7CQ"
  }
}

Playback ID

Properties
id.
string

Unique identifier for the PlaybackID

policy.
string
Possible values: "public" "signed"

  • public playback IDs are accessible by constructing an HLS url like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDS should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

Retrieve an Asset or Live Stream ID
get

Retrieves the Identifier of the Asset or Live Stream associated with the Playback ID.

Request path & query params
PLAYBACK_ID
string

The live stream's playback ID.

get
200
/video/v1/playback-ids/{PLAYBACK_ID}
Response
(application/json)
{
  "data": {
    "id": "a1B2c3D4e5F6g7H8i9",
    "policy": "public",
    "object": {
      "type": "asset",
      "id": "123456789012345678"
    }
  }
}

URL Signing Keys

A URL signing key is used as the secret when signing any Mux URL. Mux requires a JSON Web Token as the value of the token query parameter. The token query parameter must be set for URLs that reference a playback ID with a signed playback policy.

Properties
id.
string

Unique identifier for the Signing Key.

created_at.
string

Time at which the object was created. Measured in seconds since the Unix epoch.

private_key.
string

A Base64 encoded private key that can be used with the RS256 algorithm when creating a JWT. Note that this value is only returned once when creating a URL signing key.

Create a URL signing key
post

Creates a new signing key pair. When creating a new signing key, the API will generate a 2048-bit RSA key-pair and return the private key and a generated key-id; the public key will be stored at Mux to validate signed tokens.

curl https://api.mux.com/video/v1/signing-keys \
  -X POST \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
post
201
/video/v1/signing-keys
Response
(application/json)
{
  "data": {
    "private_key": "abcd123=",
    "id": "vI5KTQ78ohYriuvWKHY6COtZWXexHGLllxksOdZuya8",
    "created_at": "1610108345"
  }
}
List URL signing keys
get

Returns a list of URL signing keys.

curl https://api.mux.com/video/v1/signing-keys \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

get
200
/video/v1/signing-keys
Response
(application/json)
{
  "data": [
    {
      "id": "vI5KTQ78ohYriuvWKHY6COtZWXexHGLllxksOdZuya8",
      "created_at": "1610108345"
    },
    {
      "id": "jc6lJiCLMjyC202EXtRQ644sShzDv6x5tWJrbvUFpvmo",
      "created_at": "1608632647"
    }
  ]
}
Retrieve a URL signing key
get

Retrieves the details of a URL signing key that has previously been created. Supply the unique signing key ID that was returned from your previous request, and Mux will return the corresponding signing key information. The private key is not returned in this response.

curl https://api.mux.com/video/v1/signing-keys/${SIGNING_KEY_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
SIGNING_KEY_ID
string

The ID of the signing key.

get
200
/video/v1/signing-keys/{SIGNING_KEY_ID}
Response
(application/json)
{
  "data": {
    "id": "jc6lJiCLMjyC202EXtRQ644sShzDv6x5tWJrbvUFpvmo",
    "created_at": "1608632647"
  }
}
Delete a URL signing key
del

Deletes an existing signing key. Use with caution, as this will invalidate any existing signatures and no URLs can be signed using the key again.

url https://api.mux.com/video/v1/signing-keys/${SIGNING_KEY_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
SIGNING_KEY_ID
string

The ID of the signing key.

del
204
/video/v1/signing-keys/{SIGNING_KEY_ID}

Direct Uploads

Properties
id.
string

Unique identifier for the Direct Upload.

timeout.
integer (default: 3600)

Max time in seconds for the signed upload URL to be valid. If a successful upload has not occurred before the timeout limit, the direct upload is marked timed_out

status.
string
Possible values: "waiting" "asset_created" "errored" "cancelled" "timed_out"
new_asset_settings.
object

The settings to be used when creating a new asset. You can use any of the usual settings when creating an asset normally, with the exception to not include file url for creating the asset in input. You could optionally add overlay_setting and input urls to add Subtitles / Captions.

asset_id.
string

Only set once the upload is in the asset_created state.

error.
object

Only set if an error occurred during asset creation.

error.type.
string

Label for the specific error

error.message.
string

Human readable error message

cors_origin.
string

If the upload URL will be used in a browser, you must specify the origin in order for the signed URL to have the correct CORS headers.

url.
string

The URL to upload the associated source media to.

test.
boolean

Indicates if this is a test Direct Upload, in which case the Asset that gets created will be a test Asset.

Create a new direct upload URL
post
curl https://api.mux.com/video/v1/uploads \
  -X POST \
  -d '{ "cors_origin": "*", "new_asset_settings": { "playback_policy": ["public"] } }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
timeout
integer
(default: 3600)

Max time in seconds for the signed upload URL to be valid. If a successful upload has not occurred before the timeout limit, the direct upload is marked timed_out

cors_origin
string

If the upload URL will be used in a browser, you must specify the origin in order for the signed URL to have the correct CORS headers.

new_asset_settings
object
input
array

An array of objects that each describe an input file to be used to create the asset. As a shortcut, input can also be a string URL for a file when only one input file is used. See input[].url for requirements.

url
string

The web address of the file that Mux should download and use.

  • For subtitles text tracks, the url is the location of subtitle/captions file. Mux supports SubRip Text (SRT) and Web Video Text Tracks format for ingesting Subtitles and Closed Captions.
  • For Watermarking or Overlay, the url is the location of the watermark image.
  • When creating clips from existing Mux assets, the url is defined with mux://assets/{asset_id} template where asset_id is the Asset Identifier for creating the clip from.
overlay_settings
object

An object that describes how the image file referenced in url should be placed over the video (i.e. watermarking).

vertical_align
string
Possible values: "top" "middle" "bottom"

Where the vertical positioning of the overlay/watermark should begin from. Defaults to "top"

vertical_margin
string

The distance from the vertical_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'middle', a positive value will shift the overlay towards the bottom and and a negative value will shift it towards the top.

horizontal_align
string
Possible values: "left" "center" "right"

Where the horizontal positioning of the overlay/watermark should begin from.

horizontal_margin
string

The distance from the horizontal_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'center', a positive value will shift the image towards the right and and a negative value will shift it towards the left.

width
string

How wide the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the width will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If height is supplied with no width, the width will scale proportionally to the height.

height
string

How tall the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the height will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If width is supplied with no height, the height will scale proportionally to the width.

opacity
string

How opaque the overlay should appear, expressed as a percent. (Default 100%)

start_time
number

The time offset in seconds from the beginning of the video indicating the clip's starting marker. The default value is 0 when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

end_time
number

The time offset in seconds from the beginning of the video, indicating the clip's ending marker. The default value is the duration of the video when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

type
string
Possible values: "video" "audio" "text"

This parameter is required for the text track type.

text_type
string
Possible values: "subtitles"

Type of text track. This parameter only supports subtitles value. For more information on Subtitles / Closed Captions, see this blog post. This parameter is required for text track type.

language_code
string

The language code value must be a valid BCP 47 specification compliant value. For example, en for English or en-US for the US version of English. This parameter is required for text type and subtitles text type track.

name
string

The name of the track containing a human-readable description. This value must be unique across all text type and subtitles text type tracks. The hls manifest will associate a subtitle text track with this value. For example, the value should be "English" for subtitles text track with language_code as en. This optional parameter should be used only for text type and subtitles text type track. If this parameter is not included, Mux will auto-populate based on the input[].language_code value.

closed_captions
boolean

Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH). This optional parameter should be used for text type and subtitles text type tracks.

passthrough
string

This optional parameter should be used for text type and subtitles text type tracks.

playback_policy
array

An array of playback policy names that you want applied to this asset and available through playback_ids. Options include: "public" (anyone with the playback URL can stream the asset). And "signed" (an additional access token is required to play the asset). If no playback_policy is set, the asset will have no playback IDs and will therefore not be playable. For simplicity, a single string name can be used in place of the array in the case of only one playback policy.

Possible values: "public" "signed"

  • public playback IDs are accessible by constructing an HLS url like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDS should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

per_title_encode
boolean
passthrough
string

Arbitrary metadata that will be included in the asset details and related webhooks. Can be used to store your own ID for a video along with the asset. Max: 255 characters.

mp4_support
string
Possible values: "none" "standard"

Specify what level (if any) of support for mp4 playback. In most cases you should use our default HLS-based streaming playback ({playback_id}.m3u8) which can automatically adjust to viewers' connection speeds, but an mp4 can be useful for some legacy devices or downloading for offline playback. See the Download your videos guide for more information.

normalize_audio
boolean

Normalize the audio track loudness level. This parameter is only applicable to on-demand (not live) assets.

master_access
string
Possible values: "none" "temporary"

Specify what level (if any) of support for master access. Master access can be enabled temporarily for your asset to be downloaded. See the Download your videos guide for more information.

test
boolean

Marks the asset as a test asset when the value is set to true. A Test asset can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test assets created. Test asset are watermarked with the Mux logo, limited to 10 seconds, deleted after 24 hrs.

test
boolean
post
201
/video/v1/uploads
Request
(application/json)
{
  "cors_origin": "https://example.com/",
  "new_asset_settings": {
    "playback_policy": [
      "public"
    ],
    "mp4_support": "standard"
  }
}
Response
(application/json)
[
  {
    "url": "https://storage.googleapis.com/video-storage-us-east1-uploads/zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc?Expires=1610112458&GoogleAccessId=mux-direct-upload%40mux-cloud.iam.gserviceaccount.com&Signature=LCu4PMoKUo%2BJkWQAUwB9WU4bWVVfW3K5bZxSxEptBz3DrjbFxNyGvs0sriyJupZh9Jdb6FxKWFIRbxEetfnAAiesOvSPH%2F1GlIichmGg3YfebfxiX77%2B6ToFF6FMkJucBo284PD90AVLHhKagOea2VsbdO0fh78MAxGH9sEspyQ2uJEfYWjHFqYQ9smJyIuM3CYOmN5HKPgRWy2yUqzV7OTMe%2FivPO4%2FX6XiiN2J4nTmy83252CJUsHIvbiGctfKxcNI6b23UVN4B1tJTVgyxTOZiBQCkMLkD%2FEe5OhoAkvJgkqENRr0q3swO0IChDDWjrh7OTMwqvWGwAoVXEGiHg%3D%3D&upload_id=ABg5-UznTdib1HhOAMjdHhWIYqBbwmSYM6dVKyPe3v33uTeEE8gkN5QzvR3cei6uSZOSrjPn7bdvvDH3nhsrLBq8AjWY2qE4UQ",
    "timeout": 3600,
    "status": "waiting",
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ],
      "mp4_support": "standard"
    },
    "id": "zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc",
    "cors_origin": "https://example.com/"
  }
]
List direct uploads
get
curl https://api.mux.com/video/v1/uploads \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

get
200
/video/v1/uploads
Response
(application/json)
{
  "data": [
    {
      "url": "https://storage.googleapis.com/video-storage-us-east1-uploads/zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc?Expires=1610112458&GoogleAccessId=mux-direct-upload%40mux-cloud.iam.gserviceaccount.com&Signature=LCu4PMoKUo%2BJkWQAUwB9WU4bWVVfW3K5bZxSxEptBz3DrjbFxNyGvs0sriyJupZh9Jdb6FxKWFIRbxEetfnAAiesOvSPH%2F1GlIichmGg3YfebfxiX77%2B6ToFF6FMkJucBo284PD90AVLHhKagOea2VsbdO0fh78MAxGH9sEspyQ2uJEfYWjHFqYQ9smJyIuM3CYOmN5HKPgRWy2yUqzV7OTMe%2FivPO4%2FX6XiiN2J4nTmy83252CJUsHIvbiGctfKxcNI6b23UVN4B1tJTVgyxTOZiBQCkMLkD%2FEe5OhoAkvJgkqENRr0q3swO0IChDDWjrh7OTMwqvWGwAoVXEGiHg%3D%3D&upload_id=ABg5-UznTdib1HhOAMjdHhWIYqBbwmSYM6dVKyPe3v33uTeEE8gkN5QzvR3cei6uSZOSrjPn7bdvvDH3nhsrLBq8AjWY2qE4UQ",
      "timeout": 3600,
      "status": "waiting",
      "new_asset_settings": {
        "playback_policies": [
          "public"
        ],
        "mp4_support": "standard"
      },
      "id": "zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc",
      "cors_origin": "https://example.com/"
    },
    {
      "timeout": 3600,
      "status": "asset_created",
      "new_asset_settings": {
        "playback_policies": [
          "public"
        ],
        "mp4_support": "standard"
      },
      "id": "YzoCL01HHOtAVYq4Ds9zekdHJ2XqL9e8ukPWbr01KhtvM",
      "asset_id": "AnFVqAVXfb7vVL3ypSQDMnJZunnb8nkwe02O00p2gK8P00"
    },
    {
      "timeout": 10800,
      "status": "cancelled",
      "new_asset_settings": {
        "playback_policies": [
          "public"
        ],
        "mp4_support": "standard"
      },
      "id": "AZcWu0201SqVW01LMdmVxE00m3gEWUFZPItvni1sTqF800dQ"
    }
  ]
}
Retrieve a single direct upload's info
get
curl https://api.mux.com/video/v1/uploads/${UPLOAD_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
UPLOAD_ID
string

ID of the Upload

get
200
/video/v1/uploads/{UPLOAD_ID}
Response
(application/json)
{
  "data": {
    "timeout": 3600,
    "status": "asset_created",
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ],
      "mp4_support": "standard"
    },
    "id": "YzoCL01HHOtAVYq4Ds9zekdHJ2XqL9e8ukPWbr01KhtvM",
    "asset_id": "AnFVqAVXfb7vVL3ypSQDMnJZunnb8nkwe02O00p2gK8P00"
  }
}
Cancel a direct upload
put

Cancels a direct upload and marks it as cancelled. If a pending upload finishes after this request, no asset will be created. This request will only succeed if the upload is still in the waiting state.

curl https://api.mux.com/video/v1/uploads/${UPLOAD_ID}/cancel \
  -X PUT \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
UPLOAD_ID
string

ID of the Upload

put
200
/video/v1/uploads/{UPLOAD_ID}/cancel
Response
(application/json)
{
  "data": {
    "timeout": 3600,
    "status": "cancelled",
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ],
      "mp4_support": "standard"
    },
    "id": "zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc",
    "cors_origin": "https://example.com/"
  }
}

Delivery Usage

The Delivery Usage API allows you to get delivery/streaming usage details for each asset and across all assets. Delivery usage details are aggregated every hour at the top of the hour and can be requested for a specified time window within the last 90 days starting at 12 hours prior to when the request is made.

Assets are ordered by delivery usage starting with the one with the highest usage. Only assets with delivery usage greater than 0 seconds are returned in the response.

Properties
live_stream_id.
string

Unique identifier for the live stream that created the asset.

asset_id.
string

Unique identifier for the asset.

passthrough.
string

The passthrough value for the asset.

created_at.
string

Time at which the asset was created. Measured in seconds since the Unix epoch.

asset_state.
string
Possible values: "ready" "errored" "deleted"

The state of the asset.

asset_duration.
number

The duration of the asset in seconds.

delivered_seconds.
number

Total number of delivered seconds during this time window.

List Usage
get

Returns a list of delivery usage records and their associated Asset IDs or Live Stream IDs.

curl 'https://api.mux.com/video/v1/delivery-usage?timeframe[]=${START_TIME}&timeframe[]=${END_TIME}'   -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
page
integer
(default: 1)

Offset by this many pages, of the size of limit

limit
integer
(default: 100)

Number of items to include in the response

asset_id
string

Filter response to return delivery usage for this asset only.

timeframe[]
array

Time window to get delivery usage information. timeframe[0] indicates the start time, timeframe[1] indicates the end time in seconds since the Unix epoch. Default time window is 1 hour representing usage from 13th to 12th hour from when the request is made.

get
200
/video/v1/delivery-usage
Response
(application/json)
{
  "total_row_count": 2,
  "timeframe": [
    1607817600,
    1607990400
  ],
  "page": 1,
  "limit": 100,
  "data": [
    {
      "live_stream_id": "B65hEUWW01ErVKDDGImKcBquYhwEAkjW6Ic3lPY0299Cc",
      "delivered_seconds": 206.366667,
      "deleted_at": "1607945257",
      "created_at": "1607939184",
      "asset_state": "deleted",
      "asset_id": "Ww4v2q2H4MNbHIAM2wApKb3cmrh7eHjGLUjdKohR5wM",
      "asset_duration": 154.366667
    },
    {
      "delivered_seconds": 30,
      "deleted_at": "1607935288",
      "created_at": "1607617107",
      "asset_state": "deleted",
      "asset_id": "Qlb007on1TwN43XLIG027QJlUxm3jd01v5PRi1aXhnyFZY",
      "asset_duration": 98.773667
    }
  ]
}

Web Inputs

Web Inputs are Mux-managed web browsers that you can use to broadcast visually compelling live streams from any web page you build.

Properties
id.
string

Unique identifier for the Web Input.

created_at.
string

Time the Web Input was created, defined as a Unix timestamp (seconds since epoch).

url.
string

The URL for the Web Input to load.

auto_launch.
boolean

When set to true the Web Input will automatically launch and start streaming immediately after creation.

live_stream_id.
string

The Live Stream ID to broadcast this Web Input to.

status.
string
Possible values: "idle" "launching" "streaming"
passthrough.
string

Arbitrary metadata that will be included in the Web Input details and related webhooks. Can be used to store your own ID for the Web Input. Max: 255 characters.

resolution.
string
Possible values: "1920x1080" "1280x720" "1080x1920" "720x1280" "1080x1080" "720x720"

The resolution of the viewport of the Web Inputs browser instance. Defaults to 1920x1080 if not set.

timeout.
integer

The Number of seconds that the Web Input should stream for before automatically shutting down. Defaults to 3600 if not set.

Create a new Web Input
post
Request body params
url
string

The URL for the Web Input to load.

live_stream_id
string

The Live Stream ID to broadcast this Web Input to.

auto_launch
boolean

When set to true the Web Input will automatically launch and start streaming immediately after creation.

passthrough
string

Arbitrary metadata that will be included in the Web Input details and related webhooks. Can be used to store your own ID for the Web Input. Max: 255 characters.

resolution
string
Possible values: "1920x1080" "1280x720" "1080x1920" "720x1280" "1080x1080" "720x720"

The resolution of the viewport of the Web Inputs browser instance. Defaults to 1920x1080 if not set.

timeout
integer

The Number of seconds that the Web Input should stream for before automatically shutting down. Defaults to 3600 if not set.

post
201
/video/v1/web-inputs
Request
(application/json)
{
  "url": "https://example.com/hello.html",
  "live_stream_id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag"
}
Response
(application/json)
{
  "data": {
    "id": "S3Jlx7KABs1EfhscCGEM02G5RYpgwb02nn",
    "created_at": 1609868768,
    "url": "https://example.com/hello.html",
    "live_stream_id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "status": "idle",
    "resolution": "1920x1080",
    "timeout": 3600
  }
}
List Web Inputs
get
Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

get
200
/video/v1/web-inputs
Response
(application/json)
{
  "data": [
    {
      "id": "S3Jlx7KABs1EfhscCGEM02G5RYpgwb02nn",
      "created_at": 1609868101,
      "url": "https://example.com/hello.html",
      "live_stream_id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
      "status": "streaming",
      "resolution": "1920x1080",
      "timeout": 3600
    },
    {
      "id": "eMSK5cBGHTz3DLVjGy02BnrKvCLPN2QdF",
      "created_at": 1609868768,
      "url": "https://example.com/hello-there.html",
      "live_stream_id": "RlWPQAZ1PdGuL2eZYmZ50202XUlc7Cn1AM",
      "status": "idle",
      "resolution": "720x720",
      "timeout": 3600
    }
  ]
}
Retrieve a single Web Input's info
get
Request path & query params
WEB_INPUT_ID
string

ID of the Web Input

get
200
/video/v1/web-inputs/{WEB_INPUT_ID}
Response
(application/json)
{
  "data": {
    "id": "S3Jlx7KABs1EfhscCGEM02G5RYpgwb02nn",
    "created_at": 1609868768,
    "url": "https://example.com/hello.html",
    "live_stream_id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "status": "idle",
    "resolution": "1920x1080",
    "timeout": 3600
  }
}
Delete a Web Input
del

Deletes a Web Input and all its data

Request path & query params
WEB_INPUT_ID
string

ID of the Web Input

del
204
/video/v1/web-inputs/{WEB_INPUT_ID}
Launch a Web Input
put

Launches the browser instance and loads the URL specified, then starts streaming to the specified Live Stream.

Request path & query params
WEB_INPUT_ID
string

ID of the Web Input

put
200
/video/v1/web-inputs/{WEB_INPUT_ID}/launch
Response
(application/json)
{
  "data": {}
}
Shutdown a Web Input
put

Ends streaming to the specified Live Stream, then shuts down the Web Input browser instance.

Request path & query params
WEB_INPUT_ID
string

ID of the Web Input

put
200
/video/v1/web-inputs/{WEB_INPUT_ID}/shutdown
Response
(application/json)
{
  "data": {}
}
Reload a Web Input
put

Reloads the page that a Web Input is displaying. Note: Using this when the Web Input is streaming will display the page reloading.

Request path & query params
WEB_INPUT_ID
string

ID of the Web Input

put
200
/video/v1/web-inputs/{WEB_INPUT_ID}/reload
Response
(application/json)
{
  "data": {}
}
Update Web Input URL
put

Changes the URL that a Web Input loads when it launches. Note: Can only be called when the Web Input is idle.

Request body params
url
string

The URL for the Web Input to load.

Request path & query params
WEB_INPUT_ID
string

ID of the Web Input

put
200
/video/v1/web-inputs/{WEB_INPUT_ID}/url
Request
(application/json)
{
  "url": "https://example.com/hello-there.html"
}
Response
(application/json)
{
  "data": {
    "id": "S3Jlx7KABs1EfhscCGEM02G5RYpgwb02nn",
    "created_at": 1609868768,
    "url": "https://example.com/hello-there.html",
    "live_stream_id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "status": "idle",
    "resolution": "1920x1080",
    "timeout": 3600
  }
}