All Products
Search

This Product

    ApsaraVideo Live:AddLiveStreamMerge

    Document Center

    ApsaraVideo Live:AddLiveStreamMerge

    Last Updated:Oct 29, 2025

    Adds a primary/backup stream merge configuration.

    Operation description

    You can call this operation up to 100 times per second per account. Requests that exceed this limit are dropped and you may experience service interruptions.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    live:AddLiveStreamMerge

    create

    *Domain

    acs:cdn:*:{#accountId}:domain/{#DomainName}

    None

    None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    RegionId

    string

    No

    The region ID.

    cn-shanghai

    DomainName

    string

    Yes

    The streaming domain.

    example.com

    AppName

    string

    Yes

    The AppName for the merged stream. This must match the AppName in the final streaming URL for the rule to apply. Wildcards (*) are not allowed.

    app

    StreamName

    string

    Yes

    The StreamName for the merged stream. This must match the StreamName in the final streaming URL for the rule to apply. Wildcards (*) are not allowed.

    StreamName

    InAppName1

    string

    Yes

    The AppName of the primary input stream. This must match the AppName in the primary stream's ingest URL.

    app1

    InStreamName1

    string

    Yes

    The StreamName of the primary input stream. This must match the StreamName in the primary stream's ingest URL.

    InStream1

    InAppName2

    string

    Yes

    The AppName of the backup input stream. This must match the AppName in the backup stream's ingest URL.

    app2

    InStreamName2

    string

    Yes

    The StreamName of the backup input stream. This must match the StreamName in the backup stream's ingest URL.

    stream2

    StartTime

    string

    Yes

    The time when the merge rule becomes active, in UTC.

    Format: yyyy-MM-ddTHH:mm:ssZ.

    2020-05-29T00:00:00Z

    EndTime

    string

    Yes

    The time when the merge rule expires, in UTC.

    Format: yyyy-MM-ddTHH:mm:ssZ.

    Note

    The maximum duration between the start and end times is 7 days.

    2020-05-29T01:00:00Z

    Protocol

    string

    No

    The protocol of the input live streams. Valid values:

    • rtmp (default)

    • rtc

    rtmp

    LiveMerger

    string

    No

    Specifies the engine to use.

    • on: Uses the new liveswitch engine.

    • off: Uses the legacy engine, such as rtmpr. This is the default value.

    off

    MergeParameters

    string

    No

    Configures failover trigger conditions. Triggers:

    1. Explicit stream disconnection, such as EOF and network error.

    2. The stutter rate exceeds 60% within the last 5 seconds.

    3. No frame data is received for 2 seconds.

    4. The average frame rate drops below ali_low_frame_rate_threshold within the last ali_max_no_frame_timeout seconds, even without stuttering.

    5. If block_all_jitter is set to 1, Rules 2, 3, and 4 do not take effect.

    Valid values:

    • ali_low_frame_rate_threshold: (1,200).

    • ali_max_no_frame_timeout: (2,10)

    • block_all_jitter: 0 or 1.

    ali_low_frame_rate_threshold=10&ali_max_no_frame_timeout=5&block_all_jitter=0

    Note

    The values of AppName, InAppName1, and InAppName2 must be unique among themselves. The values of StreamName, InStreamName1, and InStreamName2 must also be unique among themselves.

    Response elements

    Parameter

    Type

    Description

    Example

    object

    RequestId

    string

    The request ID.

    16A96B9A-F203-4EC5-8E43-CB92E68F****

    Message

    string

    • Additional information. This is typically a brief description of a failed call to help you locate the issue.

    • Valid values: OK, config invalid, degrade to no livemerger.

    OK

    The message "config invalid, degrade to no livemerger" indicates that the configuration for the new liveswitch engine is incomplete. The system automatically downgrades to the legacy engine.

    Examples

    Success response

    JSON format

    {
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F****",
  "Message": "OK"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description

    400

    InvalidStartTime.Malformed

    Specified parameter StartTime is not valid.

    400

    InvalidEndTime.Malformed

    Specified parameter EndTime is not valid.

    400

    InvalidStartTime.ValueNotSupported

    The specified value of parameter StartTime is not supported.

    The value specified for the StartTime parameter is invalid.

    400

    InvalidParam

    Parameter invalid.

    Illegal input parameters

    400

    QuotaExceeded.Merge

    Exceed max merge count limit

    400

    ConfigAlreadyExists

    Config has already exist.

    400

    Duration.Exceed

    Duration between StartTime and EndTime is too long.

    400

    InvalidParam.CodeIllegalDuration

    %s.

    The value of start time should be less than the value of end time .

    500

    InternalError

    The request processing has failed due to backend service exception.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.