Creating an OTT Channel

Function

Creates an OTT channel.

URI

POST /v1/{project_id}/ott/channels

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. This parameter is mandatory when token authentication is used. It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.
Access-Control-Allow-Internal	No	String	Service authentication token. If authentication is enabled for a service, Access-Control-Allow-Internal must be carried to access the service.
Access-Control-Allow-External	No	String	Service authentication token. If authentication is enabled for a service, Access-Control-Allow-External must be carried to access the service.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
domain	Yes	String	Ingest domain name of a channel.
app_name	Yes	String	Group name or application name.
id	Yes	String	Unique ID of a channel. This parameter is mandatory. You are not advised to enter underscores (_) in a channel ID. Otherwise, transcoding and snapshot capturing will be affected.
name	No	String	Channel name. This parameter is optional.
state	Yes	String	Channel status. ON: After a channel is delivered, functions such as stream pull, transcoding, and recording are automatically enabled. OFF: Only the channel information is saved but the channel is not started.
input	Yes	InputStreamInfo object	Channel input stream information.
encoder_settings	No	Array of encoder_settings objects	Transcoding template configuration.
record_settings	Yes	record_settings object	Maximum replay recording duration. The recording is continuous in this period. This parameter is mandatory. Unit: second. The value 0 indicates that recording is not supported. The maximum recording duration is 14 days.
endpoints	Yes	Array of EndpointItem objects	Channel output stream information.

**Table 4** InputStreamInfo
Parameter	Mandatory	Type	Description
input_protocol	Yes	String	Channel input stream protocol. FLV_PULL RTMP_PUSH RTMP_PULL HLS_PULL SRT_PULL SRT_PUSH
sources	No	Array of SourcesInfo objects	Information about the primary source stream of a channel. This parameter is optional when the stream input protocol is RTMP_PUSH or SRT_PUSH. In other cases, this parameter is mandatory.
secondary_sources	No	Array of SecondarySourcesInfo objects	Standby input stream array. This parameter is optional. If there is a standby input stream, ensure that the number of channels, codec, and resolution of the primary and standby input streams are the same. If the stream input protocol is RTMP_PUSH, you do not need to specify this parameter.
failover_conditions	No	FailoverConditions object	This parameter is mandatory when there are primary and standby input streams. If the stream input protocol is RTMP_PUSH, you do not need to specify this parameter.
max_bandwidth_limit	No	Integer	Maximum bandwidth when the stream pull protocol is HLS_PULL. If this parameter is not specified, the stream with the highest BANDWIDTH is selected by default.
ip_port_mode	No	Boolean	When the stream push protocol is SRT_PUSH and streams are pushed to the origin server, the encoder does not support the input of streamid. In this case, set this parameter to true.
ip_whitelist	No	String	Customer push IP address trustlist when the type is SRT_PUSH.
scte35_source	No	String	Advertised scte35 signal.
ad_triggers	No	Array of strings	Supported Ad Tags.
audio_selectors	No	Array of InputAudioSelector objects	Set up audio selectors, up to 8 audio selectors.

**Table 5** SourcesInfo
Parameter	Mandatory	Type	Description
url	No	String	Channel source stream URL, which is used for external stream pull.
bitrate	No	Integer	Bitrate. This parameter is mandatory when live transcoding is not required. Unit: bit/s. Value range: 0–104,857,600 (100 Mbit/s)
width	No	Integer	Width corresponding to the resolution. This parameter is optional. Value range: 0–4096 (4K)
height	No	Integer	Height corresponding to the resolution. This parameter is optional. Value range: 0–2160 (4K)
enable_snapshot	No	Boolean	Whether to use the stream for snapshot capturing.
bitrate_for3u8	No	Boolean	Whether to use bitrate to fix the bitrate. Default value: false
passphrase	No	String	Encryption information when the protocol is SRT_PUSH.
backup_urls	No	Array of strings	Standby streaming URL list
stream_id	No	String	Stream ID of the streaming URL when the protocol is SRT_PULL
latency	No	Integer	Stream pull latency when the protocol is SRT_PULL

**Table 6** SecondarySourcesInfo
Parameter	Mandatory	Type	Description
url	No	String	Channel source stream URL, which is used for external stream pull.
bitrate	No	Integer	Bitrate. This parameter is mandatory when live transcoding is not required. Unit: bit/s. Value range: 0–104,857,600 (100 Mbit/s)
width	No	Integer	Width corresponding to the resolution. This parameter is optional. Value range: 0–4096 (4K)
height	No	Integer	Height corresponding to the resolution. This parameter is optional. Value range: 0–2160 (4K)
bitrate_for3u8	No	Boolean	Whether to use bitrate to fix the bitrate. Default value: false
passphrase	No	String	Encryption information when the protocol is SRT_PUSH
backup_urls	No	Array of strings	Standby streaming URL list
stream_id	No	String	Stream ID of the streaming URL when the protocol is SRT_PULL
latency	No	Integer	Stream pull latency when the protocol is SRT_PULL

**Table 7** FailoverConditions
Parameter	Mandatory	Type	Description
input_loss_threshold_msec	No	Integer	Duration threshold for stopping input streams. When the threshold is reached, the primary/standby switchover is automatically triggered. Unit: millisecond. Value range: 0–3,600,000
input_preference	No	String	Whether the primary ingest URL has the highest priority (PRIMARY) or the primary and standby URLs are switched equally (EQUAL). If equal switchover is used, you do not need to manually switch to the primary URL.

**Table 8** InputAudioSelector
Parameter	Mandatory	Type	Description
name	Yes	String	Name of the audio selector.
selector_settings	No	AudioSelectorSettings object	Setting the Audio Selector.

**Table 9** AudioSelectorSettings
Parameter	Mandatory	Type	Description
audio_language_selection	No	AudioSelectorLangSelection object	Setting the Language Selector.
audio_pid_selection	No	AudioSelectorPidSelection object	Setting the PID Selector.

**Table 10** AudioSelectorLangSelection
Parameter	Mandatory	Type	Description
language_code	Yes	String	Language abbreviation, consisting of only three lowercase letters.
language_selection_policy	No	String	Language output policy. The value is of the enumerated type. The options are LOOSE and STRICT.

**Table 11** AudioSelectorPidSelection
Parameter	Mandatory	Type	Description
pid	Yes	Integer	Sets the PID value.

**Table 12** encoder_settings
Parameter	Mandatory	Type	Description
template_id	No	String	Transcoding template ID.

**Table 13** record_settings
Parameter	Mandatory	Type	Description
rollingbuffer_duration	Yes	Integer	Maximum replay recording duration. The recording is continuous in this period. This parameter is mandatory. Unit: second. The value 0 indicates that recording is not supported. The maximum recording duration is 14 days.

**Table 14** EndpointItem
Parameter	Mandatory	Type	Description
hls_package	No	Array of HlsPackageItem objects	HLS packaging information.
dash_package	No	Array of DashPackageItem objects	DASH packaging information.
mss_package	No	Array of MssPackageItem objects	MSS packaging information.

**Table 15** HlsPackageItem
Parameter	Mandatory	Type	Description
url	Yes	String	Streaming URL customized by the customer, including the method, domain name, path, and parameters.
stream_selection	No	Array of StreamSelectionItem objects	Filters out a stream whose bitrate is in the range of [min, max] from all streams. If bitrate filtering is not required, you do not need to specify this parameter.
hls_version	No	String	HLS version number.
segment_duration_seconds	No	Integer	Output segment duration of a channel. This parameter is mandatory. Unit: second. The value ranges from 1 to 10.
playlist_window_seconds	No	Integer	Total output segment duration of a channel. The value is the output segment duration multiplied by the number of segments. There are at least three returned segments. Unit: second. Value range: 0–86,400 (value of converting 24 hours to seconds)
encryption	No	Encryption object	Encryption information.
ads	No	Object	Advertising configuration
ext_args	No	Object	Other additional parameters
request_args	No	PackageRequestArgs object	Playback configuration
ad_marker	No	Array of strings	Advertisement ID.

**Table 16** DashPackageItem
Parameter	Mandatory	Type	Description
url	Yes	String	Streaming URL customized by the customer, including the method, domain name, path, and parameters.
stream_selection	No	Array of StreamSelectionItem objects	Filters out a stream whose bitrate is in the range of [min, max] from all streams. If bitrate filtering is not required, you do not need to specify this parameter.
segment_duration_seconds	No	Integer	Output segment duration of a channel. This parameter is mandatory. Unit: second. The value ranges from 1 to 10.
playlist_window_seconds	No	Integer	Total output segment duration of a channel. The value is the output segment duration multiplied by the number of segments. There are at least three returned segments. Unit: second. Value range: 0–86,400 (value of converting 24 hours to seconds)
encryption	No	Encryption object	Encryption information.
ads	No	Object	Advertising configuration
ext_args	No	Object	Other additional parameters
request_args	No	PackageRequestArgs object	Playback configuration
ad_marker	No	String	Advertisement ID.

**Table 17** MssPackageItem
Parameter	Mandatory	Type	Description
url	Yes	String	Streaming URL customized by the customer, including the method, domain name, path, and parameters.
stream_selection	No	Array of StreamSelectionItem objects	Filters out a stream whose bitrate is in the range of [min, max] from all streams. If bitrate filtering is not required, you do not need to specify this parameter.
segment_duration_seconds	No	Integer	Output segment duration of a channel. This parameter is mandatory. Unit: second. The value ranges from 1 to 10.
playlist_window_seconds	No	Integer	Total output segment duration of a channel. The value is the output segment duration multiplied by the number of segments. There are at least three returned segments. Unit: second. Value range: 0–86,400 (value of converting 24 hours to seconds)
encryption	No	Encryption object	Encryption information.
ext_args	No	Object	Other additional parameters
delay_segment	No	Integer	Playback delay, in seconds.
request_args	No	PackageRequestArgs object	Playback configuration

**Table 18** StreamSelectionItem
Parameter	Mandatory	Type	Description
key	No	String	Parameter used for bitrate filtering in a streaming URL.
max_bandwidth	No	Integer	Maximum bitrate, in bit/s. Value range: 0-104,857,600 (100 Mbit/s)
min_bandwidth	No	Integer	Minimum bitrate, in bit/s. Value range: 0-104,857,600 (100 Mbit/s)

**Table 19** Encryption
Parameter	Mandatory	Type	Description
key_rotation_interval_seconds	No	Integer	Key cache time. If the key remains unchanged, the data is cached for seven days by default.
encryption_method	No	String	Encryption mode.
level	No	String	The options are as follows: content: One channel corresponds to one key. profile: One bitrate corresponds to one key. Default value: content
resource_id	Yes	String	ID of the DRM content generated by the customer.
system_ids	Yes	Array of strings	Enumerated value of system_id.
url	Yes	String	Address of the DRM that obtains the key.
speke_version	Yes	String	Currently, only 1.0 is supported for the drm speke version.
request_mode	Yes	String	Request Mode
http_headers	Yes	Array of HttpHeader objects	Authentication information to be added to the DRM request header.
urn	No	String	In functiongraph_proxy mode, the URN of the FG needs to be provided.

**Table 20** HttpHeader
Parameter	Mandatory	Type	Description
key	Yes	String	Key field name in the request header.
value	Yes	String	Value corresponding to the key in the request header.

**Table 21** PackageRequestArgs
Parameter	Mandatory	Type	Description
record	No	Array of RecordRequestArgs objects	Recording configuration
timeshift	No	Array of TimeshiftRequestArgs objects	Time shifting configuration
live	No	Array of LiveRequestArgs objects	Livestreaming configuration

**Table 22** RecordRequestArgs
Parameter	Mandatory	Type	Description
start_time	No	String	Start time
end_time	No	String	End time
format	No	String	Format
unit	No	String	Unit

**Table 23** TimeshiftRequestArgs
Parameter	Mandatory	Type	Description
back_time	No	String	Time shifting duration field name
unit	No	String	Unit

**Table 24** LiveRequestArgs
Parameter	Mandatory	Type	Description
delay	No	String	Delay field
unit	No	String	Unit

Response Parameters

Status code: 201

**Table 25** Response body parameters
Parameter	Type	Description
result_code	String	Error code.
result_msg	String	Error description.
domain	String	Ingest domain name.
app_name	String	Group name or application name. This parameter is mandatory.
id	String	Unique ID of a channel. This parameter is mandatory.
sources	Array of SourceRsp objects	Ingest URL list. During channel creation, the ingest URL list is returned only when the input stream protocol is RTMP_PUSH.

**Table 26** SourceRsp
Parameter	Type	Description
url	String	RTMP ingest URL.
bitrate	Integer	Bitrate. Unit: bit/s. Value range: 0–104,857,600 (100 Mbit/s)
width	Integer	Width corresponding to the resolution. Value range: 0–4096 (4K)
height	Integer	Height corresponding to the resolution. Value range: 0–2160 (4K)
enable_snapshot	Boolean	Whether to use the stream for snapshot capturing.

Status code: 400

**Table 27** Response body parameters
Parameter	Type	Description
result_code	String	Error code.
result_msg	String	Error description.
domain	String	Ingest domain name.
app_name	String	Group name or application name. This parameter is mandatory.
id	String	Unique ID of a channel. This parameter is mandatory.

Example Requests

POST https://{endpoint}/v1/{project_id}/ott/channels

{
  "domain" : "push.testott.hls.com",
  "app_name" : "ott",
  "id" : "test",
  "name" : "testname",
  "input" : {
    "input_protocol" : "RTMP_PUSH",
    "sources" : [ {
      "url" : "http://192.168.0.1/ott/test.flv?vhost=pull.testott.hls.com",
      "bitrate" : 1024,
      "width" : 100,
      "height" : 100
    } ],
    "failover_conditions" : {
      "input_loss_threshold_msec" : 100,
      "input_preference" : "EQUAL"
    }
  },
  "record_settings" : {
    "rollingbuffer_duration" : 86400
  },
  "endpoints" : [ {
    "hls_package" : [ {
      "url" : "pull.testott.hls.com/ott/test/index.m3u8",
      "stream_selection" : [ {
        "key" : "sss",
        "max_bandwidth" : 100,
        "min_bandwidth" : 100
      } ],
      "hls_version" : "1",
      "segment_duration_seconds" : 4,
      "playlist_window_seconds" : 3600
    } ],
    "dash_package" : [ {
      "url" : "pull.testott.hls.com/ott/test/index.mpd",
      "stream_selection" : [ {
        "key" : "bitrate=900000-1800000",
        "max_bandwidth" : 1800000,
        "min_bandwidth" : 900000
      } ],
      "segment_duration_seconds" : 4,
      "playlist_window_seconds" : 3600
    } ],
    "mss_package" : [ {
      "url" : "pull.testott.hls.com/ott/channel/manifest",
      "stream_selection" : [ {
        "key" : "bitrate=900000-1800000",
        "max_bandwidth" : 1800000,
        "min_bandwidth" : 900000
      } ],
      "segment_duration_seconds" : 4,
      "playlist_window_seconds" : 3600
    } ]
  } ],
  "state" : "OFF"
}

Example Responses

Status code: 201

Demo Information

{
  "result_code" : "LIVE.100000000",
  "result_msg" : "SUCCESS",
  "domain" : "push.testott.hls.com",
  "app_name" : "ott",
  "id" : "test",
  "sources" : [ {
    "url" : "rtmp://push.testott.hls.com/ott/test_1024?request_source=ott&channel_id=test",
    "bitrate" : 1024,
    "width" : 100,
    "height" : 100
  } ]
}

Status code: 400

Error response

{
  "result_code" : "LIVE.100011001",
  "result_msg" : "output url pull.testott.hls.com/ott/test/index.m3u8 is exist",
  "domain" : "push.testott.hls.com",
  "app_name" : "ott",
  "id" : "test"
}