Assets | API reference

Skip to Content

Mux Docs: Home\ \ Mux Logo\ \ Docs

SearchCtrl K

Light

Dark

Auto

Server

LightDarkAuto

Log in

Sign Up

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 12 hours).

max_stored_resolutionDeprecated

string

Possible values:"Audio only""SD""HD""FHD""UHD"

This field is deprecated. Please use resolution_tier instead. 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.

resolution_tier

string

Possible values:"audio-only""720p""1080p""1440p""2160p"

The resolution tier that the asset was ingested at, affecting billing for ingest & storage. This field also represents the highest resolution tier that the content can be delivered at, however the actual resolution may be lower depending on the device, bandwidth, and exact resolution of the uploaded asset.

max_resolution_tier

string

Possible values:"1080p""1440p""2160p"

Max resolution tier can be used to control the maximum resolution_tier your asset is encoded, stored, and streamed at. If not set, this defaults to 1080p.

encoding_tierDeprecated

string

Possible values:"smart""baseline""premium"

This field is deprecated. Please use video_quality instead. The encoding tier informs the cost, quality, and available platform features for the asset. The default encoding tier for an account can be set in the Mux Dashboard. See the video quality guide for more details.

video_quality

string

Possible values:"basic""plus""premium"

The video quality controls the cost, quality, and available platform features for the asset. The default video quality for an account can be set in the Mux Dashboard. This field replaces the deprecated encoding_tier value. See the video quality guide for more details.

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""drm"

playback_ids[].drm_configuration_id

string

The DRM configuration used by this playback ID. Must only be set when policy is set to drm.

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 text type tracks. 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[].text_type

string

Possible values:"subtitles""chapters"

This parameter is only set for text type tracks.

tracks[].text_source

string

Possible values:"uploaded""embedded""generated_live""generated_live_final""generated_vod"

The source of the text contained in a Track of type text. Valid text_source values are listed below.

tracks[].language_code

string

The language code value represents BCP 47 specification compliant value, or 'auto'. For example, en for English or en-US for the US version of English. This parameter is only set for text and audio track types. During automatic language detection for generated subtitles, this value will be set to auto until the language is determined.

tracks[].name

string

The name of the track containing a human-readable description. The HLS manifest will associate a subtitle text or audio track with this value. For example, the value should be "English" for a subtitle text track for the language_code value of en-US. This parameter is only set for text and audio track types.

tracks[].closed_captions

boolean

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

tracks[].passthrough

string

Arbitrary user-supplied metadata set for the track either when creating the asset or track. This parameter is only set for text type tracks. Max 255 characters.

tracks[].status

string

Possible values:"preparing""ready""errored""deleted"

The status of the track.

tracks[].primary

boolean

For an audio track, indicates that this is the primary audio track, ingested from the main input for this asset. The primary audio track cannot be deleted.

tracks[].auto_language_confidence

number

The confidence value (0-1) of the determined language. This value only is available when automatic language detection is utilized in generated subtitles.

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.

upload_id

string

Unique identifier for the Direct Upload. This is an optional parameter added when the asset is created from a direct upload.

is_live

boolean

Indicates whether the live stream that created this asset is currently active and not in idle state. This is an optional parameter added when the asset is created from a live stream.

passthrough

string

You can set this field to anything you want. It will be included in the asset details and related webhooks. If you're looking for more structured metadata, such as title or external_id , you can use the meta object instead. 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_access 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_supportDeprecated

string (default: none)

Possible values:"none""capped-1080p""audio-only""audio-only,capped-1080p""standard" (Deprecated)

Deprecated. The level of MP4 support requested through the legacy mp4_support option, or none if it was not used. Renditions created this way appear in the static_renditions object alongside renditions created with the Static Renditions API; see that object for how the two differ. An asset cannot use both mechanisms at the same time.

source_asset_id

string

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

normalize_audio

boolean (default: false)

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) for this asset. The object does not exist if no static renditions have been requested. See Download your videos for more information.

This object is populated by both the Static Renditions API and the deprecated mp4_support option, and the two report status differently:

static_renditions.status

string (default: disabled)

Possible values:"ready""preparing""disabled""errored"

Indicates the aggregate status of MP4 renditions created with the deprecated mp4_support option. This field is only meaningful when mp4_support is enabled on the asset. For renditions created with the Static Renditions API, use the per-rendition files[].status field instead.

static_renditions.files

array

Array of file objects.

static_renditions.files[].name

string

Possible values:"low.mp4""medium.mp4""high.mp4""highest.mp4""audio.m4a""capped-1080p.mp4""2160p.mp4""1440p.mp4""1080p.mp4""720p.mp4""540p.mp4""480p.mp4""360p.mp4""270p.mp4"

Name of the static rendition file

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

static_renditions.files[].type

string

Possible values:"standard""advanced"

Indicates the static rendition type of this specific MP4 version of this asset. Only present for static renditions created with the Static Renditions API. Not set for renditions created with the deprecated mp4_support option.

static_renditions.files[].status

string

Possible values:"ready""preparing""skipped""errored"

Indicates the status of this specific MP4 version of this asset. Only present for static renditions created with the Static Renditions API. Not set for renditions created with the deprecated mp4_support option. For mp4_support renditions, see the top-level static_renditions.status field on the asset instead.

static_renditions.files[].resolution_tier

string

Possible values:"2160p""1440p""1080p""720p""audio-only"

Indicates the resolution tier of this specific MP4 version of this asset. Only present for static renditions created with the Static Renditions API. Not set for renditions created with the deprecated mp4_support option.

static_renditions.files[].resolution

string

Possible values:"highest""audio-only"

Indicates the resolution of this specific MP4 version of this asset. Only present for static renditions created with the Static Renditions API. Not set for renditions created with the deprecated mp4_support option.

static_renditions.files[].id

string

The ID of this static rendition, used in managing this static rendition. Only present for static renditions created with the Static Renditions API. Not set for renditions created with the deprecated mp4_support option.

static_renditions.files[].passthrough

string

Arbitrary user-supplied metadata set for the static rendition. Max 255 characters.

recording_times

array

An array of individual live stream recording sessions. A recording session is created on each encoder connection during the live stream. Additionally any time slate media is inserted during brief interruptions in the live stream media or times when the live streaming software disconnects, a recording session representing the slate media will be added with a "slate" type.

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.

recording_times[].type

string

Possible values:"content""slate"

The type of media represented by the recording session, either content for normal stream content or slate for slate media inserted during stream interruptions.

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 av1 video codec is non-standard and the value of this parameter is av1.

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 20 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 5 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.video_bitrate

string

Possible values:"high"

The video bitrate of the input file is high. This parameter is present when the average bitrate of any key frame interval (also known as Group of Pictures or GOP) is higher than what's considered standard which typically is 16 Mbps.

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.

non_standard_input_reasons.unsupported_pixel_format

string

The video pixel format, as a string, returned by libav. Considered non-standard if not one of yuv420p or yuvj420p. HEVC inputs additionally permit yuv420p10le.

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.

ingest_type

string

Possible values:"on_demand_url""on_demand_direct_upload""on_demand_clip""live_rtmp""live_srt"

The type of ingest used to create the asset.

meta

object

Customer provided metadata about this asset.

Note: This metadata may be publicly available via the video player. Do not include PII or sensitive information.

meta.title

string

The asset title. Max 512 code points.

meta.creator_id

string

This is an identifier you provide to keep track of the creator of the asset. Max 128 code points.

meta.external_id

string

This is an identifier you provide to link the asset to your own data. Max 128 code points.

progress

object

Detailed state information about the asset ingest process.

progress.state

string

Possible values:"ingesting""transcoding""completed""live""errored"

The detailed state of the asset ingest process. This field is useful for relaying more granular processing information to end users when a non-standard input is encountered.

progress.progress

number (minimum: -1maximum: 100)

Represents the estimated completion percentage. Returns 0 - 100 when in ingesting, transcoding, or completed state, and -1 when in live or errored state.

directives

array

The Mux Robots directives applied to the asset.

directives[].id

string

The Mux Robots directive identifier.

generate_shots

boolean (default: false)

Whether to perform shot detection on this asset. Shots are only generated for video assets and will not be generated for audio-only assets.

shots

object

The results of generating shots on the video

shots.status

string

Possible values:"pending""completed""errored""skipped""deleted"

The status of the shot detection process

shots.created_at

string

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

shots.shots_manifest_url

string

A URL to a JSON manifest describing the shot changes detected in the video along with shot preview images for each shot. This field is only present when status is completed.

shots.errors

object

An object describing any errors encountered during the shot detection process. This field is only present when status is errored.

shots.errors.type

string

The type of error that occurred

shots.errors.messages

array

A list of error messages describing the errors that occurred in more detail

thumbnail_time

number

The media time within the asset used when a thumbnail without an explicit time is requested.

Create an asset post

Create a new Mux Video asset.

copy
Request body params

input

array

Deprecated

Deprecated. Use inputs instead, which accepts an identical type.

inputs

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.

inputs[].url

string

The URL of the file that Mux should download and use.

The url property may be omitted on the first input object when providing asset settings for LiveStream and Upload objects, in order to configure settings related to the primary (live stream or direct upload) input.

inputs[].overlay_settings

object

An object that describes how the image file referenced in URL should be placed over the video (i.e. watermarking). Ensure that the URL is active and persists the entire lifespan of the video object.

inputs[].overlay_settings.vertical_align

string

Possible values:"top""middle""bottom"

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

inputs[].overlay_settings.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.

inputs[].overlay_settings.horizontal_align

string

Possible values:"left""center""right"

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

inputs[].overlay_settings.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.

inputs[].overlay_settings.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.

inputs[].overlay_settings.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.

inputs[].overlay_settings.opacity

string

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

inputs[].generated_subtitles

array

Generate subtitle tracks using automatic speech recognition with this configuration. Subtitles are generated using the audio of the input they are nested within. For direct uploads, this first input should omit the url parameter, as the main input file is provided via the direct upload. Note that subtitle generation happens after initial ingest, so the generated tracks will be in the preparing state when the asset transitions to ready.

inputs[].generated_subtitles[].name

string

A name for this subtitle track.

inputs[].generated_subtitles[].passthrough

string

Arbitrary metadata set for the subtitle track. Max 255 characters.

inputs[].generated_subtitles[].language_code

string

(default: en)

Possible values:"en""es""it""pt""de""fr""pl""ru""nl""ca""tr""sv""uk""no""fi""sk""el""cs""hr""da""ro""bg""auto"

The language of the audio from which subtitles are generated. Selecting a language of "auto" will allow language detection to set the language code automatically.

inputs[].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.

inputs[].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.

inputs[].type

string

Possible values:"video""audio""text"

This parameter is required for text type tracks.

inputs[].text_type

string

Possible values:"subtitles""chapters"

Type of text track. Use subtitles for subtitles and closed captions, or chapters for a chapters track. For more information on Subtitles / Closed Captions, see this blog post. This parameter is required for text type tracks.

inputs[].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 and audio track types.

inputs[].name

string

The name of the track containing a human-readable description. This value must be unique within each group of text or audio track types. The HLS manifest will associate a subtitle text track with this value. For example, the value should be "English" for a subtitle text track with language_code set to en. This optional parameter should be used only for text and audio type tracks. This parameter can be optionally provided for the first video input to denote the name of the muxed audio track if present. If this parameter is not included, Mux will auto-populate based on the input[].language_code value.

inputs[].closed_captions

boolean

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

inputs[].passthrough

string

This optional parameter should be used for tracks with type of text and text_type set to subtitles.

playback_policy

array

Deprecated

Deprecated. Use playback_policies instead, which accepts an identical type.

playback_policies

array

An array of playback policy names that you want applied to this asset and available through playback_ids. Options include:

If no playback_policies are 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""drm"

advanced_playback_policies

array

An array of playback policy objects that you want applied to this asset and available through playback_ids. advanced_playback_policies must be used instead of playback_policies when creating a DRM playback ID.

advanced_playback_policies[].policy

string

Possible values:"public""signed""drm"

advanced_playback_policies[].drm_configuration_id

string

The DRM configuration used by this playback ID. Must only be set when policy is set to drm.

passthrough

string

You can set this field to anything you want. It will be included in the asset details and related webhooks. If you're looking for more structured metadata, such as title or external_id, you can use the meta object instead. Max: 255 characters.

mp4_support

string

Deprecated

Possible values:"none""capped-1080p""audio-only""audio-only,capped-1080p""standard" (Deprecated)

Deprecated. See the Static Renditions API for the updated API.

Specify what level of support for mp4 playback. You may not enable both mp4_support and static_renditions.

The standard(deprecated) option produces up to three MP4 files with different levels of resolution (high.mp4, medium.mp4, low.mp4, or audio.m4a for an audio-only asset).

MP4 files are not produced for none (default).

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

(default: false)

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.

max_resolution_tier

string

Possible values:"1080p""1440p""2160p"

Max resolution tier can be used to control the maximum resolution_tier your asset is encoded, stored, and streamed at. If not set, this defaults to 1080p.

encoding_tier

string

Deprecated

Possible values:"smart""baseline""premium"

video_quality

string

Possible values:"basic""plus""premium"

static_renditions

array

An array of static renditions to create for this asset. You may not enable both static_renditions and the deprecated mp4_support.

static_renditions[].resolution

string

Possible values:"highest""audio-only""2160p""1440p""1080p""720p""540p""480p""360p""270p"

static_renditions[].passthrough

string

Arbitrary user-supplied metadata set for the static rendition. Max 255 characters.

meta

object

Customer provided metadata about this asset.

Note: This metadata may be publicly available via the video player. Do not include PII or sensitive information.

meta.title

string

The asset title. Max 512 code points.

meta.creator_id

string

This is an identifier you provide to keep track of the creator of the asset. Max 128 code points.

meta.external_id

string

This is an identifier you provide to link the asset to your own data. Max 128 code points.

copy_overlays

boolean

(default: true)

If the created asset is a clip, this controls whether overlays are copied from the source asset.

directives

array

An array of Mux Robots directives to apply to the asset.

directives[].id

string

The Mux Robots directive identifier.

generate_shots

boolean

(default: false)

Whether to perform shot detection on this asset. Shots are only generated for video assets and will not be generated for audio-only assets.

post

201

https://api.mux.com/video/v1/assets

Request

(application/json)

copy

Response

(application/json)

copy
List assets get

List all Mux assets.

copy
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

cursor

string

This parameter is used to request pages beyond the first. You can find the cursor value in the next_cursor field of paginated responses.

live_stream_id

string

Filter response to return all the assets for this live stream only

upload_id

string

Filter response to return an asset created from this direct upload only

get

200

https://api.mux.com/video/v1/assets

Response

(application/json)

copy
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.

copy
Request path & query params

ASSET_ID

string

The asset ID.

get

200

https://api.mux.com/video/v1/assets/{ASSET\_ID}

Response

(application/json)

copy
Delete an asset del

Deletes a video asset and all its data.

copy
Request path & query params

ASSET_ID

string

The asset ID.

del

204

https://api.mux.com/video/v1/assets/{ASSET\_ID}

Update an asset patch

Updates the details of an existing Asset with the provided Asset ID. This API currently only supports the passthrough, meta and thumbnail_time fields.

Request body params

passthrough

string

You can set this field to anything you want. It will be included in the asset details and related webhooks. If you're looking for more structured metadata, such as title or external_id , you can use the meta object instead. Max: 255 characters. In order to clear this value, the field should be included with an empty string value.

meta

object

Customer provided metadata about this asset.

Note: This metadata may be publicly available via the video player. Do not include PII or sensitive information.

meta.title

string

The asset title. Max 512 code points.

meta.creator_id

string

This is an identifier you provide to keep track of the creator of the asset. Max 128 code points.

meta.external_id

string

This is an identifier you provide to link the asset to your own data. Max 128 code points.

thumbnail_time

number

The media time within the asset used when a thumbnail without an explicit time is requested.

Request path & query params

ASSET_ID

string

The asset ID.

patch

200

https://api.mux.com/video/v1/assets/{ASSET\_ID}

Request

(application/json)

copy

Response

(application/json)

copy
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.

copy
Request path & query params

ASSET_ID

string

The asset ID.

get

200

https://api.mux.com/video/v1/assets/{ASSET\_ID}/input-info

Response

(application/json)

copy
Create a playback ID post

Creates a playback ID that can be used to stream the asset to a viewer.

copy
Request body params

policy

string

Possible values:"public""signed""drm"

drm_configuration_id

string

The DRM configuration used by this playback ID. Must only be set when policy is set to drm.

Request path & query params

ASSET_ID

string

The asset ID.

post

201

https://api.mux.com/video/v1/assets/{ASSET\_ID}/playback-ids

Request

(application/json)

copy

Response

(application/json)

copy
Retrieve a playback ID get

Retrieves information about the specified playback ID.

copy
Request path & query params

ASSET_ID

string

The asset ID.

PLAYBACK_ID

string

The asset or live stream's playback ID.

get

200

https://api.mux.com/video/v1/assets/{ASSET\_ID}/playback-ids/{PLAYBACK\_ID}

Response

(application/json)

copy
Delete a playback ID del

Deletes a playback ID, rendering it nonfunctional for viewing an asset's video content. Please note that deleting the playback ID removes access to the underlying asset; a viewer who started playback before the playback ID was deleted may be able to watch the entire video for a limited duration.

copy
Request path & query params

ASSET_ID

string

The asset ID.

PLAYBACK_ID

string

The asset or live stream's playback ID.

del

204

https://api.mux.com/video/v1/assets/{ASSET\_ID}/playback-ids/{PLAYBACK\_ID}

Update MP4 support put Deprecated

This method has been deprecated. Please see the Static Rendition API. Allows you to add or remove mp4 support for assets that were created without it. The values supported are capped-1080p, audio-only, audio-only,capped-1080p, standard(deprecated), 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.

copy
Request body params

mp4_support

string

Possible values:"none""capped-1080p""audio-only""audio-only,capped-1080p""standard" (Deprecated)

Specify what level of support for mp4 playback.

none will delete the MP4s from the asset in question.

Request path & query params

ASSET_ID

string

The asset ID.

put

200

https://api.mux.com/video/v1/assets/{ASSET\_ID}/mp4-support

Request

(application/json)

copy

Response

(application/json)

copy
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.

copy
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

https://api.mux.com/video/v1/assets/{ASSET\_ID}/master-access

Request

(application/json)

copy

Response

(application/json)

copy
Create a static rendition for an asset post

Creates a static rendition (i.e. MP4) for an asset

Request body params

resolution

string

Possible values:"highest""audio-only""2160p""1440p""1080p""720p""540p""480p""360p""270p"

passthrough

string

Arbitrary user-supplied metadata set for the static rendition. Max 255 characters.

Request path & query params

ASSET_ID

string

The asset ID.

post

201

https://api.mux.com/video/v1/assets/{ASSET\_ID}/static-renditions

Request

(application/json)

copy

Response

(application/json)

copy
Delete a single static rendition for an asset del

Deletes a single static rendition for an asset

Request path & query params

ASSET_ID

string

The asset ID.

STATIC_RENDITION_ID

string

The static rendition ID.

del

204

https://api.mux.com/video/v1/assets/{ASSET\_ID}/static-renditions/{STATIC\_RENDITION\_ID}

Unset the thumbnail time for an asset del

Unset the thumbnail time for an asset, returning the thumbnail to default behavior

Request path & query params

ASSET_ID

string

The asset ID.

del

204

https://api.mux.com/video/v1/assets/{ASSET\_ID}/thumbnail-time

Create an asset track post

Adds an asset track (for example, subtitles, or an alternate audio track) to an asset. Assets must be in the ready state before tracks can be added.

copy
Request body params

url

string

The URL of the file that Mux should download and use.

type

string

Possible values:"text""audio"

text_type

string

Possible values:"subtitles""chapters"

The type of text track. Required when type is text. Use subtitles for subtitles and closed captions, or chapters for a chapters track.

language_code

string

The language code of this track. The 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 unique within each group of text or audio track types. The HLS manifest will associate the text or audio 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 a value 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 user-supplied metadata set for the track either when creating the asset or track.

Request path & query params

ASSET_ID

string

The asset ID.

post

201

https://api.mux.com/video/v1/assets/{ASSET\_ID}/tracks

Request

(application/json)

copy

Response

(application/json)

copy
Delete an asset track del

Removes a text or additional audio track from an asset. Neither video nor the primary audio track can be removed.

copy
Request path & query params

ASSET_ID

string

The asset ID.

TRACK_ID

string

The ID of the track for an asset.

del

204

https://api.mux.com/video/v1/assets/{ASSET\_ID}/tracks/{TRACK\_ID}

Update an asset track patch

Updates the details of an existing Asset Track with the provided Asset ID and Track ID.

Request body params

language_code

string

name

string

closed_captions

boolean

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

passthrough

string

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

Request path & query params

ASSET_ID

string

The asset ID.

TRACK_ID

string

The ID of the track for an asset.

patch

200

https://api.mux.com/video/v1/assets/{ASSET\_ID}/tracks/{TRACK\_ID}

Request

(application/json)

copy

Response

(application/json)

copy
Generate track subtitles post

Generates subtitles (captions) for a given audio track. See docs for more information.

Request body params

generated_subtitles

array

Generate subtitle tracks using automatic speech recognition with this configuration.

generated_subtitles[].name

string

A name for this subtitle track.

generated_subtitles[].passthrough

string

Arbitrary metadata set for the subtitle track. Max 255 characters.

generated_subtitles[].language_code

string

(default: en)

Possible values:"en""es""it""pt""de""fr""pl""ru""nl""ca""tr""sv""uk""no""fi""sk""el""cs""hr""da""ro""bg""auto"

Request path & query params

ASSET_ID

string

The asset ID.

TRACK_ID

string

The ID of the track for an asset.

post

201

https://api.mux.com/video/v1/assets/{ASSET\_ID}/tracks/{TRACK\_ID}/generate-subtitles

Request

(application/json)

copy

Response

(application/json)

copy
Get asset shots get

Retrieves the shot manifest URL containing shot boundaries and shot preview image URLs.

Request path & query params

ASSET_ID

string

The asset ID.

get

200

https://api.mux.com/video/v1/assets/{ASSET\_ID}/shots

Response

(application/json)

copy
Generate shots post

Generate shot boundaries and shot preview images.

Request body params
Request path & query params

ASSET_ID

string

The asset ID.

post

201

https://api.mux.com/video/v1/assets/{ASSET\_ID}/shots

Request

(application/json)

copy

Response

(application/json)

copy
Delete asset shots del

Deletes detected shot boundaries and shot preview images on the asset.

Request path & query params

ASSET_ID

string

The asset ID.

del

204

https://api.mux.com/video/v1/assets/{ASSET\_ID}/shots

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 to 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. Max 64 characters.

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 Asset IDs that were created from this Live Stream. The most recently generated Asset ID is the last entry in the list.

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""drm"

playback_ids[].drm_configuration_id

string

The DRM configuration used by this playback ID. Must only be set when policy is set to drm.

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 user-supplied metadata set for the asset. Max 255 characters.

audio_only

boolean

The live stream only processes the audio track if the value is set to true. Mux drops the video track if broadcasted.

embedded_subtitles

array

Describes the embedded closed caption configuration of the incoming live stream.

embedded_subtitles[].name

string

A name for this live stream closed caption track.

embedded_subtitles[].passthrough

string

Arbitrary user-supplied metadata set for the live stream closed caption track. Max 255 characters.

embedded_subtitles[].language_code

string (default: en)

The language of the closed caption stream. Value must be BCP 47 compliant.

embedded_subtitles[].language_channel

string (default: cc1)

Possible values:"cc1""cc2""cc3""cc4"

CEA-608 caption channel to read data from.

generated_subtitles

array

Configure the incoming live stream to include subtitles created with automatic speech recognition. Each Asset created from a live stream with generated_subtitles configured will automatically receive two text tracks. The first of these will have a text_source value of generated_live, and will be available with ready status as soon as the stream is live. The second text track will have a text_source value of generated_live_final and will contain subtitles with improved accuracy, timing, and formatting. However, generated_live_final tracks will not be available in ready status until the live stream ends. If an Asset has both generated_live and generated_live_final tracks that are ready, then only the generated_live_final track will be included during playback.

generated_subtitles[].name

string

A name for this live stream subtitle track.

generated_subtitles[].passthrough

string

Arbitrary metadata set for the live stream subtitle track. Max 255 characters.

generated_subtitles[].language_code

string (default: en)

Possible values:"en""en-US""es""fr""de""pt""it"

The language of the audio from which subtitles are generated.

generated_subtitles[].transcription_vocabulary_ids

array

Unique identifiers for existing Transcription Vocabularies to use while generating subtitles for the live stream. If the Transcription Vocabularies provided collectively have more than 1000 phrases, only the first 1000 phrases will be included.

reconnect_window

number (default: 60, minimum: 0, maximum: 1800)

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. Max: 1800s (30 minutes).

If not specified directly, Standard Latency streams have a Reconnect Window of 60 seconds; Reduced and Low Latency streams have a default of 0 seconds, or no Reconnect Window. For that reason, we suggest specifying a value other than zero for Reduced and Low Latency streams.

Reduced and Low Latency streams with a Reconnect Window greater than zero will insert slate media into the recorded asset while waiting for the streaming software to reconnect or when there are brief interruptions in the live stream media. When using a Reconnect Window setting higher than 60 seconds with a Standard Latency stream, we highly recommend enabling slate with the use_slate_for_standard_latency option.

use_slate_for_standard_latency

boolean (default: false)

By default, Standard Latency live streams do not have slate media inserted while waiting for live streaming software to reconnect to Mux. Setting this to true enables slate insertion on a Standard Latency stream.

reconnect_slate_url

string

The URL of the image file that Mux should download and use as slate media during interruptions of the live stream media. This file will be downloaded each time a new recorded asset is created from the live stream. If this is not set, the default slate media will be used.

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 user-supplied 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.

simulcast_targets[].stream_key

string

Stream Key represents a stream identifier on the third party live streaming service to send the parent live stream to. Only used for RTMP(s) simulcast destinations.

simulcast_targets[].url

string

The RTMP(s) or SRT endpoint for a simulcast destination.

Note: SRT simulcast targets can only be used when an source is connected over SRT.

simulcast_targets[].error_severity

string

Possible values:"normal""fatal"

The severity of the error encountered by the simulcast target. This field is only set when the simulcast target is in the errored status. See the values of severities below and their descriptions.

latency_mode

string

Possible values:"low""reduced""standard"

Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this as an alternative to setting low latency or reduced latency flags.

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.

max_continuous_duration

integer (default: 43200, minimum: 60, maximum: 43200)

The time in seconds a live stream may be continuously active before being disconnected. Defaults to 12 hours.

srt_passphrase

string

Unique key used for encrypting a stream to a Mux SRT endpoint. Max 64 characters.

active_ingest_protocol

string

Possible values:"rtmp""srt"

The protocol used for the active ingest stream. This is only set when the live stream is active.

meta

object

Customer provided metadata about this live stream.

Note: This metadata may be publicly available via the video player. Do not include PII or sensitive information.

meta.title

string

The live stream title. Max 512 code points.

Create a live stream post

Creates a new live stream. Once created, an encoder can connect to Mux via the specified stream key and begin streaming to an audience.

copy
Request body params

playback_policy

array

Deprecated

Deprecated. Use playback_policies instead, which accepts an identical type.

playback_policies

array

An array of playback policy names that you want applied to this live stream and available through playback_ids. Options include:

If no playback_policies is set, the live stream 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""drm"

advanced_playback_policies

array

An array of playback policy objects that you want applied on this live stream and available through playback_ids. advanced_playback_policies must be used instead of playback_policies when creating a DRM playback ID.

advanced_playback_policies[].policy

string

Possible values:"public""signed""drm"

advanced_playback_policies[].drm_configuration_id

string

The DRM configuration used by this playback ID. Must only be set when policy is set to drm.

new_asset_settings

object

new_asset_settings.input

array

Deprecated

Deprecated. Use inputs instead, which accepts an identical type.

new_asset_settings.inputs

array

new_asset_settings.inputs[].url

string

The URL of the file that Mux should download and use.

new_asset_settings.inputs[].overlay_settings

object

new_asset_settings.inputs[].overlay_settings.vertical_align

string

Possible values:"top""middle""bottom"

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

new_asset_settings.inputs[].overlay_settings.vertical_margin

string

new_asset_settings.inputs[].overlay_settings.horizontal_align

string

Possible values:"left""center""right"

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

new_asset_settings.inputs[].overlay_settings.horizontal_margin

string

new_asset_settings.inputs[].overlay_settings.width

string

new_asset_settings.inputs[].overlay_settings.height

string

new_asset_settings.inputs[].overlay_settings.opacity

string

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

new_asset_settings.inputs[].generated_subtitles

array

new_asset_settings.inputs[].generated_subtitles[].name

string

A name for this subtitle track.

new_asset_settings.inputs[].generated_subtitles[].passthrough

string

Arbitrary metadata set for the subtitle track. Max 255 characters.

new_asset_settings.inputs[].generated_subtitles[].language_code

string

(default: en)

Possible values:"en""es""it""pt""de""fr""pl""ru""nl""ca""tr""sv""uk""no""fi""sk""el""cs""hr""da""ro""bg""auto"

new_asset_settings.inputs[].start_time

number

new_asset_settings.inputs[].end_time

number

new_asset_settings.inputs[].type

string

Possible values:"video""audio""text"

This parameter is required for text type tracks.

new_asset_settings.inputs[].text_type

string

Possible values:"subtitles""chapters"

new_asset_settings.inputs[].language_code

string

new_asset_settings.inputs[].name

string

new_asset_settings.inputs[].closed_captions

boolean

new_asset_settings.inputs[].passthrough

string

This optional parameter should be used for tracks with type of text and text_type set to subtitles.

new_asset_settings.playback_policy

array

Deprecated

Deprecated. Use playback_policies instead, which accepts an identical type.

new_asset_settings.playback_policies

array

An array of playback policy names that you want applied to this asset and available through playback_ids. Options include:

Possible values:"public""signed""drm"

new_asset_settings.advanced_playback_policies

array

new_asset_settings.advanced_playback_policies[].policy

string

Possible values:"public""signed""drm"

new_asset_settings.advanced_playback_policies[].drm_configuration_id

string

The DRM configuration used by this playback ID. Must only be set when policy is set to drm.

new_asset_settings.passthrough

string

new_asset_settings.mp4_support

string

Deprecated

Possible values:"none""capped-1080p""audio-only""audio-only,capped-1080p""standard" (Deprecated)

Deprecated. See the Static Renditions API for the updated API.

Specify what level of support for mp4 playback. You may not enable both mp4_support and static_renditions.

MP4 files are not produced for none (default).

new_asset_settings.normalize_audio

boolean

(default: false)

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

new_asset_settings.master_access

string

Possible values:"none""temporary"

new_asset_settings.test

boolean

new_asset_settings.max_resolution_tier

string

Possible values:"1080p""1440p""2160p"

Max resolution tier can be used to control the maximum resolution_tier your asset is encoded, stored, and streamed at. If not set, this defaults to 1080p.

new_asset_settings.encoding_tier

string

Deprecated

Possible values:"smart""baseline""premium"

new_asset_settings.video_quality

string

Possible values:"basic""plus""premium"

new_asset_settings.static_renditions

array

An array of static renditions to create for this asset. You may not enable both static_renditions and the deprecated mp4_support.

new_asset_settings.static_renditions[].resolution

string

Possible values:"highest""audio-only""2160p""1440p""1080p""720p""540p""480p""360p""270p"

new_asset_settings.static_renditions[].passthrough

string

Arbitrary user-supplied metadata set for the static rendition. Max 255 characters.

new_asset_settings.meta

object

Customer provided metadata about this asset.

Note: This metadata may be publicly available via the video player. Do not include PII or sensitive information.

new_asset_settings.meta.title

string

The asset title. Max 512 code points.

new_asset_settings.meta.creator_id

string

This is an identifier you provide to keep track of the creator of the asset. Max 128 code points.

new_asset_settings.meta.external_id

string

This is an identifier you provide to link the asset to your own data. Max 128 code points.

new_asset_settings.copy_overlays

boolean

(default: true)

If the created asset is a clip, this controls whether overlays are copied from the source asset.

new_asset_settings.directives

array

An array of Mux Robots directives to apply to the asset.

new_asset_settings.directives[].id

string

The Mux Robots directive identifier.

new_asset_settings.generate_shots

boolean

(default: false)

Whether to perform shot detection on this asset. Shots are only generated for video assets and will not be generated for audio-only assets.

reconnect_window

number

(default: 60, min: 0, max: 1800)

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.

use_slate_for_standard_latency

boolean

(default: false)

reconnect_slate_url

string

passthrough

string

audio_only

boolean

Force the live stream to only process the audio track when the value is set to true. Mux drops the video track if broadcasted.

embedded_subtitles

array

Describe the embedded closed caption contents of the incoming live stream.

embedded_subtitles[].name

string

A name for this live stream closed caption track.

embedded_subtitles[].passthrough

string

Arbitrary user-supplied metadata set for the live stream closed caption track. Max 255 characters.

embedded_subtitles[].language_code

string

(default: en)

The language of the closed caption stream. Value must be BCP 47 compliant.

embedded_subtitles[].language_channel

string

(default: cc1)

Possible values:"cc1""cc2""cc3""cc4"

CEA-608 caption channel to read data from.

generated_subtitles

array

generated_subtitles[].name

string

A name for this live stream subtitle track.

generated_subtitles[].passthrough

string

Arbitrary metadata set for the live stream subtitle track. Max 255 characters.

generated_subtitles[].language_code

string

(default: en)

Possible values:"en""en-US""es""fr""de""pt""it"

The language of the audio from which subtitles are generated.

generated_subtitles[].transcription_vocabulary_ids

array

latency_mode

string

Possible values:"low""reduced""standard"

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

simulcast_targets[].passthrough

string

Arbitrary user-supplied metadata set by you when creating a simulcast target.

simulcast_targets[].stream_key

string

simulcast_targets[].url

string

The RTMP(s) or SRT endpoint for a simulcast destination.

Note: SRT simulcast targets can only be used when an source is connected over SRT.

max_continuous_duration

integer

(default: 43200, min: 60, max: 43200)

The time in seconds a live stream may be continuously active before being disconnected. Defaults to 12 hours.

meta

object

Customer provided metadata about this live stream.

Note: This metadata may be publicly available via the video player. Do not include PII or sensitive information.

meta.title

string

The live stream title. Max 512 code points.

post

201

https://api.mux.com/video/v1/live-streams

Request

(application/json)

copy

Response

(application/json)

copy
List live streams get

Lists the live streams that currently exist in the current environment.

copy
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

stream_key

string

Filter response to return live stream for this stream key only

status

string

Possible values:"active""idle""disabled"

Filter response to return live streams with the specified status only. 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.

get

200

https://api.mux.com/video/v1/live-streams

Response

(application/json)

copy
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.

copy
Request path & query params

LIVE_STREAM_ID

string

The live stream ID

get

200

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}

Response

(application/json)

copy
Delete a live stream del

Deletes a live stream from the current environment. If the live stream is currently active and being streamed to, ingest will be terminated and the encoder will be disconnected.

copy
Request path & query params

LIVE_STREAM_ID

string

The live stream ID

del

204

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}

Update a live stream patch

Updates the parameters of a previously-created live stream. This currently supports a subset of variables. Supply the live stream ID and the updated parameters and Mux will return the corresponding live stream information. The information returned will be the same after update as for subsequent get live stream requests.

Request body params

passthrough

string

Arbitrary user-supplied metadata set for the live stream. Max 255 characters. In order to clear this value, the field should be included with an empty-string value.

latency_mode

string

Possible values:"low""reduced""standard"

reconnect_window

number

(default: 60, min: 0, max: 1800)

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.

use_slate_for_standard_latency

boolean

(default: false)

reconnect_slate_url

string

The URL of the image file that Mux should download and use as slate media during interruptions of the live stream media. This file will be downloaded each time a new recorded asset is created from the live stream. Set this to a blank string to clear the value so that the default slate media will be used.

max_continuous_duration

integer

(default: 43200, min: 60, max: 43200)

The time in seconds a live stream may be continuously active before being disconnected. Defaults to 12 hours.

new_asset_settings

object

Updates the new asset settings to use to generate a new asset for this live stream. Only the mp4_support, master_access, and video_quality settings may be updated.

new_asset_settings.mp4_support

string

Deprecated

Possible values:"none""capped-1080p""audio-only""audio-only,capped-1080p""standard" (Deprecated)

Deprecated. See the Static Renditions API for the updated API.

Specify what level of support for mp4 playback should be added to new assets generated from this live stream.

new_asset_settings.master_access

string

Possible values:"temporary""none"

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

new_asset_settings.video_quality

string

Possible values:"plus""premium"

The video quality controls the cost, quality, and available platform features for the asset. See the video quality guide for more details.

new_asset_settings.meta

object

Customer provided metadata about this asset.

Note: This metadata may be publicly available via the video player. Do not include PII or sensitive information.

new_asset_settings.meta.title

string

The asset title. Max 512 code points.

new_asset_settings.meta.creator_id

string

This is an identifier you provide to keep track of the creator of the asset. Max 128 code points.

new_asset_settings.meta.external_id

string

This is an identifier you provide to link the asset to your own data. Max 128 code points.

meta

object

Customer provided metadata about this live stream.

Note: This metadata may be publicly available via the video player. Do not include PII or sensitive information.

meta.title

string

The live stream title. Max 512 code points.

Request path & query params

LIVE_STREAM_ID

string

The live stream ID

patch

200

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}

Request

(application/json)

copy

Response

(application/json)

copy
Create a live stream playback ID post

Create a new playback ID for this live stream, through which a viewer can watch the streamed content of the live stream.

copy
Request body params

policy

string

Possible values:"public""signed""drm"

drm_configuration_id

string

The DRM configuration used by this playback ID. Must only be set when policy is set to drm.

Request path & query params

LIVE_STREAM_ID

string

The live stream ID

post

201

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/playback-ids

Request

(application/json)

copy

Response

(application/json)

copy
Retrieve a live stream playback ID get

Fetches information about a live stream's playback ID, through which a viewer can watch the streamed content from this live stream.

Request path & query params

LIVE_STREAM_ID

string

The live stream ID

PLAYBACK_ID

string

The asset or live stream's playback ID.

get

200

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/playback-ids/{PLAYBACK\_ID}

Response

(application/json)

copy
Delete a live stream playback ID del

Deletes the playback ID for the live stream. This will not disable ingest (as the live stream still exists). New attempts to play back the live stream will fail immediately. However, current viewers will be able to continue watching the stream for some period of time.

copy
Request path & query params

LIVE_STREAM_ID

string

The live stream ID

PLAYBACK_ID

string

The asset or live stream's playback ID.

del

204

https://api.mux.com/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.

copy
Request path & query params

LIVE_STREAM_ID

string

The live stream ID

post

201

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/reset-stream-key

Response

(application/json)

copy
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.

copy
Request path & query params

LIVE_STREAM_ID

string

The live stream ID

put

200

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/complete

Response

(application/json)

copy
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.

copy
Request path & query params

LIVE_STREAM_ID

string

The live stream ID

put

200

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/disable

Response

(application/json)

copy
Enable a live stream put

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

copy
Request path & query params

LIVE_STREAM_ID

string

The live stream ID

put

200

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/enable

Response

(application/json)

copy
Update a live stream's embedded subtitles put

Configures a live stream to receive embedded closed captions. The resulting Asset's subtitle text track will have closed_captions: true set.

Request body params

embedded_subtitles

array

Describe the embedded closed caption contents of the incoming live stream.

embedded_subtitles[].name

string

A name for this live stream closed caption track.

embedded_subtitles[].passthrough

string

Arbitrary user-supplied metadata set for the live stream closed caption track. Max 255 characters.

embedded_subtitles[].language_code

string

(default: en)

The language of the closed caption stream. Value must be BCP 47 compliant.

embedded_subtitles[].language_channel

string

(default: cc1)

Possible values:"cc1""cc2""cc3""cc4"

CEA-608 caption channel to read data from.

Request path & query params

LIVE_STREAM_ID

string

The live stream ID

put

200

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/embedded-subtitles

Request

(application/json)

copy

Response

(application/json)

copy
Update a live stream's generated subtitles put

Updates a live stream's automatic-speech-recognition-generated subtitle configuration. Automatic speech recognition subtitles can be removed by sending an empty array in the request payload.

Request body params

generated_subtitles

array

Update automated speech recognition subtitle configuration for a live stream. At most one subtitle track is allowed.

generated_subtitles[].name

string

A name for this live stream subtitle track.

generated_subtitles[].passthrough

string

Arbitrary metadata set for the live stream subtitle track. Max 255 characters.

generated_subtitles[].language_code

string

(default: en)

Possible values:"en""en-US""es""fr""de""pt""it"

The language of the audio from which subtitles are generated.

generated_subtitles[].transcription_vocabulary_ids

array

Request path & query params

LIVE_STREAM_ID

string

The live stream ID

put

200

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/generated-subtitles

Request

(application/json)

copy

Response

(application/json)

copy
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.

copy
Request body params

passthrough

string

Arbitrary user-supplied metadata set by you when creating a simulcast target.

stream_key

string

url

string

The RTMP(s) or SRT endpoint for a simulcast destination.

Note: SRT simulcast targets can only be used when an source is connected over SRT.

Request path & query params

LIVE_STREAM_ID

string

The live stream ID

post

201

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/simulcast-targets

Request

(application/json)

copy

Response

(application/json)

copy
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.

copy
Request path & query params

LIVE_STREAM_ID

string

The live stream ID

SIMULCAST_TARGET_ID

string

The ID of the simulcast target.

del

204

https://api.mux.com/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.

copy
Request path & query params

LIVE_STREAM_ID

string

The live stream ID

SIMULCAST_TARGET_ID

string

The ID of the simulcast target.

get

200

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/simulcast-targets/{SIMULCAST\_TARGET\_ID}

Response

(application/json)

copy
Update live stream static renditions for new assets put

Updates a live stream's static renditions settings for new assets. Further assets made via this live stream will create static renditions per the settings provided. You must provide all static renditions desired.

Request body params

static_renditions

array

static_renditions[].resolution

string

Possible values:"highest""audio-only""2160p""1440p""1080p""720p""540p""480p""360p""270p"

static_renditions[].passthrough

string

Arbitrary user-supplied metadata set for the static rendition. Max 255 characters.

Request path & query params

LIVE_STREAM_ID

string

The live stream ID

put

200

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/new-asset-settings/static-renditions

Request

(application/json)

copy

Response

(application/json)

copy
Delete a live stream's static renditions setting for new assets del

Deletes a live stream's static renditions settings for new assets. Further assets made via this live stream will not create static renditions unless re-added.

Request path & query params

LIVE_STREAM_ID

string

The live stream ID

del

204

https://api.mux.com/video/v1/live-streams/{LIVE\_STREAM\_ID}/new-asset-settings/static-renditions

Playback ID

Operations related to the manipulation of playback IDs, through which users are able to stream videos and live streams from Mux.

Properties

id

string

Unique identifier for the PlaybackID

policy

string

Possible values:"public""signed""drm"

drm_configuration_id

string

The DRM configuration used by this playback ID. Must only be set when policy is set to drm.

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 asset or live stream's playback ID.

get

200

https://api.mux.com/video/v1/playback-ids/{PLAYBACK\_ID}

Response

(application/json)

copy

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 Deprecated

This route is now deprecated, please use the Signing Keys API. 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.

Note: Any new access tokens authenticating this route will be required to have System level permissions.

copy

post

201

https://api.mux.com/video/v1/signing-keys

Response

(application/json)

copy
List URL signing keys get Deprecated

This route is now deprecated, please use the Signing Keys API. Returns a list of URL signing keys.

Note: Any new access tokens authenticating this route will be required to have System level permissions.

copy
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

https://api.mux.com/video/v1/signing-keys

Response

(application/json)

copy
Retrieve a URL signing key get Deprecated

This route is now deprecated, please use the Signing Keys API. 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.

Note: Any new access tokens authenticating this route will be required to have System level permissions.

copy
Request path & query params

SIGNING_KEY_ID

string

The ID of the signing key.

get

200

https://api.mux.com/video/v1/signing-keys/{SIGNING\_KEY\_ID}

Response

(application/json)

copy
Delete a URL signing key del Deprecated

This route is now deprecated, please use the Signing Keys API. 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.

Note: Any new access tokens authenticating this route will be required to have System level permissions.

copy
Request path & query params

SIGNING_KEY_ID

string

The ID of the signing key.

del

204

https://api.mux.com/video/v1/signing-keys/{SIGNING\_KEY\_ID}

Direct Uploads

Direct upload allows you to push assets directly to Mux storage instead of needing to go through your own first. When you create a new direct upload, we'll give you back a signed URL for a Google Cloud Storage bucket. Their storage API is S3 compatible, so whatever tool you use to upload to either GCS or S3 should work, just remember you're probably uploading large video files and should take advantage of things like resumable or multipart uploads.

Particularly for customers that deal with a lot of user-generated content, it's common to expect quite a few abandoned uploads. To keep those abandoned uploads from cluttering up your asset lists, we don't create an asset for you until the upload is complete. Once that asset is created, you can expect all of the normal asset-related webhooks.

Properties

id

string

Unique identifier for the Direct Upload.

timeout

integer (default: 3600, minimum: 60, maximum: 604800)

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

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

Creates a new direct upload, through which video content can be uploaded for ingest to Mux.

copy
Request body params

timeout

integer

(default: 3600, min: 60, max: 604800)

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

new_asset_settings.input

array

Deprecated

Deprecated. Use inputs instead, which accepts an identical type.

new_asset_settings.inputs

array

new_asset_settings.inputs[].url

string

The URL of the file that Mux should download and use.

new_asset_settings.inputs[].overlay_settings

object

new_asset_settings.inputs[].overlay_settings.vertical_align

string

Possible values:"top""middle""bottom"

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

new_asset_settings.inputs[].overlay_settings.vertical_margin

string

new_asset_settings.inputs[].overlay_settings.horizontal_align

string

Possible values:"left""center""right"

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

new_asset_settings.inputs[].overlay_settings.horizontal_margin

string

new_asset_settings.inputs[].overlay_settings.width

string

new_asset_settings.inputs[].overlay_settings.height

string

new_asset_settings.inputs[].overlay_settings.opacity

string

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

new_asset_settings.inputs[].generated_subtitles

array

new_asset_settings.inputs[].generated_subtitles[].name

string

A name for this subtitle track.

new_asset_settings.inputs[].generated_subtitles[].passthrough

string

Arbitrary metadata set for the subtitle track. Max 255 characters.

new_asset_settings.inputs[].generated_subtitles[].language_code

string

(default: en)

Possible values:"en""es""it""pt""de""fr""pl""ru""nl""ca""tr""sv""uk""no""fi""sk""el""cs""hr""da""ro""bg""auto"

new_asset_settings.inputs[].start_time

number

new_asset_settings.inputs[].end_time

number

new_asset_settings.inputs[].type

string

Possible values:"video""audio""text"

This parameter is required for text type tracks.

new_asset_settings.inputs[].text_type

string

Possible values:"subtitles""chapters"

new_asset_settings.inputs[].language_code

string

new_asset_settings.inputs[].name

string

new_asset_settings.inputs[].closed_captions

boolean

new_asset_settings.inputs[].passthrough

string

This optional parameter should be used for tracks with type of text and text_type set to subtitles.

new_asset_settings.playback_policy

array

Deprecated

Deprecated. Use playback_policies instead, which accepts an identical type.

new_asset_settings.playback_policies

array

An array of playback policy names that you want applied to this asset and available through playback_ids. Options include:

Possible values:"public""signed""drm"

new_asset_settings.advanced_playback_policies

array

new_asset_settings.advanced_playback_policies[].policy

string

Possible values:"public""signed""drm"

new_asset_settings.advanced_playback_policies[].drm_configuration_id

string

The DRM configuration used by this playback ID. Must only be set when policy is set to drm.

new_asset_settings.passthrough

string

new_asset_settings.mp4_support

string

Deprecated

Possible values:"none""capped-1080p""audio-only""audio-only,capped-1080p""standard" (Deprecated)

Deprecated. See the Static Renditions API for the updated API.

Specify what level of support for mp4 playback. You may not enable both mp4_support and static_renditions.

MP4 files are not produced for none (default).

new_asset_settings.normalize_audio

boolean

(default: false)

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

new_asset_settings.master_access

string

Possible values:"none""temporary"

new_asset_settings.test

boolean

new_asset_settings.max_resolution_tier

string

Possible values:"1080p""1440p""2160p"

Max resolution tier can be used to control the maximum resolution_tier your asset is encoded, stored, and streamed at. If not set, this defaults to 1080p.

new_asset_settings.encoding_tier

string

Deprecated

Possible values:"smart""baseline""premium"

new_asset_settings.video_quality

string

Possible values:"basic""plus""premium"

new_asset_settings.static_renditions

array

An array of static renditions to create for this asset. You may not enable both static_renditions and the deprecated mp4_support.

new_asset_settings.static_renditions[].resolution

string

Possible values:"highest""audio-only""2160p""1440p""1080p""720p""540p""480p""360p""270p"

new_asset_settings.static_renditions[].passthrough

string

Arbitrary user-supplied metadata set for the static rendition. Max 255 characters.

new_asset_settings.meta

object

Customer provided metadata about this asset.

Note: This metadata may be publicly available via the video player. Do not include PII or sensitive information.

new_asset_settings.meta.title

string

The asset title. Max 512 code points.

new_asset_settings.meta.creator_id

string

This is an identifier you provide to keep track of the creator of the asset. Max 128 code points.

new_asset_settings.meta.external_id

string

This is an identifier you provide to link the asset to your own data. Max 128 code points.

new_asset_settings.copy_overlays

boolean

(default: true)

If the created asset is a clip, this controls whether overlays are copied from the source asset.

new_asset_settings.directives

array

An array of Mux Robots directives to apply to the asset.

new_asset_settings.directives[].id

string

The Mux Robots directive identifier.

new_asset_settings.generate_shots

boolean

(default: false)

Whether to perform shot detection on this asset. Shots are only generated for video assets and will not be generated for audio-only assets.

test

boolean

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

post

201

https://api.mux.com/video/v1/uploads

Request

(application/json)

copy

Response

(application/json)

copy
List direct uploads get

Lists direct uploads in the current environment.

copy
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

https://api.mux.com/video/v1/uploads

Response

(application/json)

copy
Retrieve a single direct upload's info get

Fetches information about a single direct upload in the current environment.

copy
Request path & query params

UPLOAD_ID

string

ID of the Upload

get

200

https://api.mux.com/video/v1/uploads/{UPLOAD\_ID}

Response

(application/json)

copy
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.

copy
Request path & query params

UPLOAD_ID

string

ID of the Upload

put

200

https://api.mux.com/video/v1/uploads/{UPLOAD\_ID}/cancel

Response

(application/json)

copy

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.

deleted_at

string

If exists, time at which the asset was deleted. 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.

asset_resolution_tier

string

Possible values:"audio-only""720p""1080p""1440p""2160p"

The resolution tier that the asset was ingested at, affecting billing for ingest & storage

asset_encoding_tierDeprecated

string

Possible values:"smart""baseline""premium"

This field is deprecated. Please use asset_video_quality instead. The encoding tier that the asset was ingested at. See the video quality guide for more details.

asset_video_quality

string

Possible values:"basic""plus""premium"

The video quality that the asset was ingested at. This field replaces asset_encoding_tier. See the video quality guide for more details.

delivered_seconds

number

Total number of delivered seconds during this time window.

delivered_seconds_by_resolution

object

Seconds delivered broken into resolution tiers. Each tier will only be displayed if there was content delivered in the tier.

delivered_seconds_by_resolution.tier_2160p

number

Total number of delivered seconds during this time window that had a resolution larger than the 1440p tier (over 4,194,304 pixels total).

delivered_seconds_by_resolution.tier_1440p

number

Total number of delivered seconds during this time window that had a resolution larger than the 1080p tier but less than or equal to the 2160p tier (over 2,073,600 and <= 4,194,304 pixels total).

delivered_seconds_by_resolution.tier_1080p

number

Total number of delivered seconds during this time window that had a resolution larger than the 720p tier but less than or equal to the 1440p tier (over 921,600 and <= 2,073,600 pixels total).

delivered_seconds_by_resolution.tier_720p

number

Total number of delivered seconds during this time window that had a resolution within the 720p tier (up to 921,600 pixels total, based on typical 1280x720).

delivered_seconds_by_resolution.tier_audio_only

number

Total number of delivered seconds during this time window that had a resolution of audio only.

List Usage get

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

copy
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. You cannot specify both the asset_id and live_stream_id parameters together.

live_stream_id

string

Filter response to return delivery usage for assets for this live stream. You cannot specify both the asset_id and live_stream_id parameters together.

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

https://api.mux.com/video/v1/delivery-usage

Response

(application/json)

copy

Playback Restrictions

Playback Restrictions allows you to set additional rules for playing videos. You can set the domains/hostnames allowed to play your videos. For instance, viewers can play videos embedded on the https://example.com website when you set the Playback Restrictions with example.com as an allowed domain. Any Video requests from other websites are denied. Additionally, you can set rules for what user agents to allow. Please see Using User-Agent HTTP header for validation for more details on this feature.

Properties

data

object

data.id

string

Unique identifier for the Playback Restriction. Max 255 characters.

data.created_at

string

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

data.updated_at

string

Time the Playback Restriction was last updated, defined as a Unix timestamp (seconds since epoch).

data.referrer

object

A list of domains allowed to play your videos.

data.referrer.allowed_domains

array

List of domains allowed to play videos. Possible values are

data.referrer.allow_no_referrer

boolean (default: false)

A boolean to determine whether to allow or deny HTTP requests without Referer HTTP request header. Playback requests coming from non-web/native applications like iOS, Android or smart TVs will not have a Referer HTTP header. Set this value to true to allow these playback requests.

data.user_agent

object

Rules that control what user agents are allowed to play your videos. Please see Using User-Agent HTTP header for validation for more details on this feature.

data.user_agent.allow_no_user_agent

boolean (default: true)

Whether or not to allow views without a User-Agent HTTP request header.

data.user_agent.allow_high_risk_user_agent

boolean (default: true)

Whether or not to allow high risk user agents. The high risk user agents are defined by Mux.

Create a Playback Restriction post

Create a new Playback Restriction.

copy
Request body params

referrer

object

A list of domains allowed to play your videos.

referrer.allowed_domains

array

List of domains allowed to play videos. Possible values are

referrer.allow_no_referrer

boolean

(default: false)

user_agent

object

user_agent.allow_no_user_agent

boolean

(default: true)

Whether or not to allow views without a User-Agent HTTP request header.

user_agent.allow_high_risk_user_agent

boolean

(default: true)

Whether or not to allow high risk user agents. The high risk user agents are defined by Mux.

post

201

https://api.mux.com/video/v1/playback-restrictions

Request

(application/json)

copy

Response

(application/json)

copy
List Playback Restrictions get

Returns a list of all Playback Restrictions.

copy
Request path & query params

page

integer

(default: 1)

Offset by this many pages, of the size of limit

limit

integer

(default: 25)

Number of items to include in the response

get

200

https://api.mux.com/video/v1/playback-restrictions

Response

(application/json)

copy
Delete a Playback Restriction del

Deletes a single Playback Restriction.

copy
Request path & query params

PLAYBACK_RESTRICTION_ID

string

ID of the Playback Restriction.

del

204

https://api.mux.com/video/v1/playback-restrictions/{PLAYBACK\_RESTRICTION\_ID}

Retrieve a Playback Restriction get

Retrieves a Playback Restriction associated with the unique identifier.

copy
Request path & query params

PLAYBACK_RESTRICTION_ID

string

ID of the Playback Restriction.

get

200

https://api.mux.com/video/v1/playback-restrictions/{PLAYBACK\_RESTRICTION\_ID}

Response

(application/json)

copy
Update the Referrer Playback Restriction put

Allows you to modify the list of domains or change how Mux validates playback requests without the Referer HTTP header. The Referrer restriction fully replaces the old list with this new list of domains.

copy
Request body params

allowed_domains

array

List of domains allowed to play videos. Possible values are

allow_no_referrer

boolean

(default: false)

Request path & query params

PLAYBACK_RESTRICTION_ID

string

ID of the Playback Restriction.

put

200

https://api.mux.com/video/v1/playback-restrictions/{PLAYBACK\_RESTRICTION\_ID}/referrer

Request

(application/json)

copy

Response

(application/json)

copy
Update the User Agent Restriction put

Allows you to modify how Mux validates playback requests with different user agents. Please see Using User-Agent HTTP header for validation for more details on this feature.

Request body params

allow_no_user_agent

boolean

(default: true)

Whether or not to allow views without a User-Agent HTTP request header.

allow_high_risk_user_agent

boolean

(default: true)

Whether or not to allow high risk user agents. The high risk user agents are defined by Mux.

Request path & query params

PLAYBACK_RESTRICTION_ID

string

ID of the Playback Restriction.

put

200

https://api.mux.com/video/v1/playback-restrictions/{PLAYBACK\_RESTRICTION\_ID}/user\_agent

Request

(application/json)

copy

Response

(application/json)

copy

DRM Configurations

DRM Configurations allow you to adjust the security level of content delivered through Mux Video's Digital Rights Management (DRM) feature.

Properties

id

string

Unique identifier for the DRM Configuration. Max 255 characters.

List DRM Configurations get

Returns a list of DRM Configurations

Request path & query params

page

integer

(default: 1)

Offset by this many pages, of the size of limit

limit

integer

(default: 25)

Number of items to include in the response

get

200

https://api.mux.com/video/v1/drm-configurations

Response

(application/json)

copy
Retrieve a DRM Configuration get

Retrieves a single DRM Configuration.

Request path & query params

DRM_CONFIGURATION_ID

string

The DRM Configuration ID.

get

200

https://api.mux.com/video/v1/drm-configurations/{DRM\_CONFIGURATION\_ID}

Response

(application/json)

copy

Transcription Vocabularies

Transcription Vocabularies allows you to provide collections of phrases like proper nouns, technical jargon, and uncommon words as part of captioning workflows. When using Auto-Generated Captions, Transcription Vocabularies increase the likelihood of correct speech recognition for these words and phrases.

Properties

id

string

Unique identifier for the Transcription Vocabulary

name

string

The user-supplied name of the Transcription Vocabulary.

phrases

array

Phrases, individual words, or proper names to include in the Transcription Vocabulary. When the Transcription Vocabulary is attached to a live stream's generated_subtitles configuration, the probability of successful speech recognition for these words or phrases is boosted.

passthrough

string

Arbitrary user-supplied metadata set for the Transcription Vocabulary. Max 255 characters.

created_at

string

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

updated_at

string

Time the Transcription Vocabulary was updated, defined as a Unix timestamp (seconds since epoch).

Create a Transcription Vocabulary post

Create a new Transcription Vocabulary.

Request body params

name

string

The user-supplied name of the Transcription Vocabulary.

phrases

array

Phrases, individual words, or proper names to include in the Transcription Vocabulary. When the Transcription Vocabulary is attached to a live stream's generated_subtitles, the probability of successful speech recognition for these words or phrases is boosted.

passthrough

string

Arbitrary user-supplied metadata set for the Transcription Vocabulary. Max 255 characters.

post

201

https://api.mux.com/video/v1/transcription-vocabularies

Request

(application/json)

copy

Response

(application/json)

copy
List Transcription Vocabularies get

List all Transcription Vocabularies.

Request path & query params

limit

integer

(default: 10, max: 10)

Number of items to include in the response

page

integer

(default: 1)

Offset by this many pages, of the size of limit

get

200

https://api.mux.com/video/v1/transcription-vocabularies

Response

(application/json)

copy
Retrieve a Transcription Vocabulary get

Retrieves the details of a Transcription Vocabulary that has previously been created. Supply the unique Transcription Vocabulary ID and Mux will return the corresponding Transcription Vocabulary information. The same information is returned when creating a Transcription Vocabulary.

Request path & query params

TRANSCRIPTION_VOCABULARY_ID

string

The ID of the Transcription Vocabulary.

get

200

https://api.mux.com/video/v1/transcription-vocabularies/{TRANSCRIPTION\_VOCABULARY\_ID}

Response

(application/json)

copy
Delete a Transcription Vocabulary del

Deletes a Transcription Vocabulary. The Transcription Vocabulary's ID will be disassociated from any live streams using it. Transcription Vocabularies can be deleted while associated live streams are active. However, the words and phrases in the deleted Transcription Vocabulary will remain attached to those streams while they are active.

Request path & query params

TRANSCRIPTION_VOCABULARY_ID

string

The ID of the Transcription Vocabulary.

del

204

https://api.mux.com/video/v1/transcription-vocabularies/{TRANSCRIPTION\_VOCABULARY\_ID}

Update a Transcription Vocabulary put

Updates the details of a previously-created Transcription Vocabulary. Updates to Transcription Vocabularies are allowed while associated live streams are active. However, updates will not be applied to those streams while they are active.

Request body params

name

string

The user-supplied name of the Transcription Vocabulary.

phrases

array

passthrough

string

Arbitrary user-supplied metadata set for the Transcription Vocabulary. Max 255 characters.

Request path & query params

TRANSCRIPTION_VOCABULARY_ID

string

The ID of the Transcription Vocabulary.

put

200

https://api.mux.com/video/v1/transcription-vocabularies/{TRANSCRIPTION\_VOCABULARY\_ID}

Request

(application/json)

copy

Response

(application/json)

copy

Mux Developer ConsoleBETA

✕

Welcome to the Mux developer console.

Here, you can try out Mux API capabilities and inspect the responses.

To get started, log in with your Mux credentials: mux login

Note: All assets will be created in test mode and deleted after 24 hours.

Console input$

Type Mux commands here. Use arrow up and down to navigate command history. Press Tab to autocomplete.