All Products
Search

This Product

    ApsaraVideo Live:CreateLivePullToPush

    Document Center

    ApsaraVideo Live:CreateLivePullToPush

    Last Updated:Mar 13, 2026

    Creates a pull-to-push task.

    Operation description

    Important The pull-to-push feature is a paid service. Billing for this service starts at 00:00 on December 5, 2025.

    • For pricing details, see Pull-to-push Fees.

    • You can call this API to create a pull-to-push task.

    • This API supports both live stream pulling and video-on-demand (VOD) stream pulling tasks.

    • After you create a task, it starts at the specified start time and stops at the specified end time. The task is automatically deleted after it stops.

    • The destination ingest URL for a task must be unique. If multiple tasks push streams to the same URL, ingestion will fail.

    • Pull-to-push callback events include task status change callbacks and task exit callbacks. For more information, see Pull-to-push Event Callbacks.

    QPS limit

    This API supports up to 10 calls per second per user. If you exceed this limit, throttling is triggered, which may affect your business operations. It is recommended that you adhere to this limit.

    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:CreateLivePullToPush

    create

    *All Resource

    *

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    No

    The region ID.

    cn-beijing
    Region

    string

    Yes

    The region where the task runs. Valid values:

    • ap-southeast-1 (Singapore)

    • ap-southeast-5 (Indonesia)

    • cn-beijing (Beijing)

    • cn-shanghai (Shanghai)

    • cn-shenzhen (Shenzhen)

    cn-shanghai
    TaskName

    string

    No

    The task name. You can use this name for fuzzy searches. Default value: empty string.

    test
    StartTime

    string

    Yes

    The task start time.

    Note

    • Format: yyyy-MM-ddTHH:mm:ssZ (UTC).

    2024-08-26T10:30:00Z
    EndTime

    string

    Yes

    The task end time.

    Note

    • Format: yyyy-MM-ddTHH:mm:ssZ (UTC).

    • EndTime must be later than StartTime.

    • EndTime must be later than the current time.

    2024-08-27T14:30:00Z
    SourceType

    string

    Yes

    The source stream type. Valid values:

    • live: a live stream.

    • vod: an Alibaba Cloud ApsaraVideo VOD resource.

    • url: a third-party video file resource.

    live
    SourceProtocol

    string

    No

    The source stream protocol.

    Valid values:

    • rtmp

    • srt

    • http-flv

    • hls

    Note

    This parameter is required only when SourceType is live. It is ignored if SourceType is vod or url.

    rtmp
    SourceUrls

    array

    Yes

    The list of source stream URLs.

    Note

    • For live streams, specify one complete live playback URL.

    • For VOD or third-party video files, specify up to 30 URLs.

    • Live streams support RTMP, SRT, and HTTP-FLV protocols.

    • For VOD, specify the media asset ID of an Alibaba Cloud ApsaraVideo VOD resource.

    • Third-party video files support MP4 and HTTP-FLV protocols.

    testurls

    string

    No

    The source stream URL.

    Note

    • For live streams, specify one complete live playback URL.

    • For VOD or third-party video files, specify up to 30 URLs.

    • Live streams support RTMP, SRT, and HTTP-FLV protocols.

    • For VOD, specify the media asset ID of an Alibaba Cloud ApsaraVideo VOD resource.

    • Third-party video files support MP4 and HTTP-FLV protocols.

    rtmp://pulltest.****.aliyunlive.com/pulltest493/pulltest-w434
    DstUrl

    string

    Yes

    The destination ingest URL.

    Note

    • Supports the RTMP protocol.

    • Maximum length: 2,000 characters.

    rtmp://pushtest.********.aliyunlive.com/pulltest493/pulltest-w434
    RepeatNumber

    integer

    No

    The number of times to repeat playback after the stream ends. Valid values:

    • 0 (default): Do not repeat playback.

    • -1: Repeat playback in a loop.

    • A positive integer: Number of times to repeat playback.

    Note

    This parameter applies only to video-on-demand (VOD) or third-party video streams.

    0
    FileIndex

    integer

    No

    The file index. Playback starts from the Nth file.

    0
    Offset

    integer

    No

    The start offset of the video file. Unit: seconds. Value must be greater than 0.

    Note

    • This is the time offset from the first frame of the first video.

    • This parameter applies only to video-on-demand (VOD) or third-party video streams.

    2
    CallbackUrl

    string

    No

    The HTTP webhook address. Default value: empty.

    Note

    • The address that receives task-related callbacks.

    • Maximum length: 2,000 characters.

    • If you do not specify this parameter, no task-related callbacks are sent.

    https://callback*****.com
    RetryInterval

    integer

    No

    The retry interval. Unit: seconds. Valid values: 60 to 300. Default value: 60.

    60
    RetryCount

    integer

    No

    The number of retries. Default value: 3.

    3

    Response elements

    Element

    Type

    Description

    Example

    object

    Response schema

    RequestId

    string

    The request ID.

    16A96B9A-F203-4EC5-8E43-CB92E68*****
    RetCode

    integer

    The return code.

    Note

    • 0 indicates success.

    • For other values, see the error codes section below.

    0
    Description

    string

    The error description.

    OK
    TaskId

    string

    The task ID.

    fd245384-4067-4f91-9d75-9666a6bc9****

    Examples

    Success response

    JSON format

    {
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68*****",
  "RetCode": 0,
  "Description": "OK",
  "TaskId": "fd245384-4067-4f91-9d75-9666a6bc9****"
}

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 InvalidParameter %s. Parameter error
    400 InvalidParam.CodeIllegalDuration %s. The value of start time should be less than the value of end time .
    400 CodeInvalidAliUid This aliuid does not have a live domain name. This aluid does not have a live domain name.
    400 CodeNotEnoughResource Exceeded configuration limits or insufficient resources. Exceeded configuration limits or insufficient resources
    400 CodeConfigAlreadyExists Code Config Already Exists
    500 InternalError %s. error on the live liveapi server.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.