Help Center/ Live/ Cloud Live API Reference/ Stream Pull Management/ Creating a Relay Task
Updated on 2026-01-07 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Creating a Relay Task

Function

Create a live stream pulling and pushing task based on the stream source and task information specified by the tenant.

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependencies

    live:stream:createPullTask

    Write

    -

    -

    -

    -

URI

POST /v1/{project_id}/pull/stream/task

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

No

String

User token. This parameter is mandatory when token authentication is used. The token 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.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

region

No

String

Task execution region. If an ingest domain name is specified, the region must be the same as the origin server of the ingest domain name.

source_type

Yes

String

Source type for stream pull.

PullLivePushLive: livestreaming

PullVodPushLive: looped streaming

source_urls

Yes

Array of strings

Source URL for stream pull.

domain

No

String

Ingest domain name.

app_name

No

String

Appliation name.

stream_name

No

String

Stream name.

push_args

No

String

Stream push parameter.

destination_url

No

String

Complete target URL.

If this parameter is specified, domain, app_name, and stream_name must be empty or not transferred.

start_time

No

String

Task start time.

end_time

No

String

Task end time.

vod_loop_time

No

String

The default value is -1. -1: infinite loop until the specified end time arrives; N: N rounds of playback based on the file list. Playback terminates when either the N rounds are completed or the specified end time is reached, whichever comes first. If this parameter is not transferred or is left empty (""), the default value takes effect.

vod_refresh_type

No

String

The default value is immediate_new_source. The options are immediate_new_source, continue_from_file_start, and continue_from_break_point.

vod_start_video_index

No

Integer

Index of the file to be played. The value starts from 0, indicating the first file. The maximum value is len(source_urls) – 1. The default value is 0.

vod_start_video_time

No

Integer

Second from which the specified file is played. The default value is 0.

backup_source_type

No

String

Type of the standby source.

PullLivePushLive: livestreaming

Notes:

  1. The standby source takes effect only when the primary source is a livestream.

  2. When the primary livestream source is interrupted, the standby source is automatically used for stream pull.

backup_source_urls

No

Array of strings

Standby source URL.

callback_events

No

Array of strings

List of events to be called back. If this parameter is left blank, all events are called back.

  • TaskStart: task start callback

  • TaskExit: task stop callback

  • VodSourceFileStart: file switchover callback (available only for PullVodPushLive tasks)

  • VodSourceFileFinish: file playback completion callback (available only for PullVodPushLive tasks)

  • ResetTaskConfig: task update callback (available only for PullVodPushLive tasks)

  • TaskAlarm: alarm event notification

callback_url

No

String

Callback address.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

task_id

String

Task ID.

request_id

String

Request ID.

Status code: 400

Table 5 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error description.

request_id

String

Request ID.

Example Requests

POST https://{endpoint}/v1/{project_id}/pull/stream/task

{
  "region" : "cn-north-4",
  "source_type" : "PullLivePushLive",
  "source_urls" : [ "rtmp://play.example.huawei.com/live/stream1" ],
  "domain" : "publish.example.huawei.com",
  "app_name" : "live",
  "stream_name" : "test",
  "start_time" : "2018-05-19T18:00:00Z",
  "end_time" : "2018-05-19T21:00:00Z",
  "push_args" : "arg1=value1",
  "callback_events" : [ "TaskStart", "TaskExit", "TaskAlarm" ],
  "callback_url" : "callback.example.com",
  "backup_source_type" : "PullLivePushLive",
  "backup_source_urls" : [ "rtmp://play.example.huawei.com/live/stream1_bak" ]
}

Example Responses

Status code: 200

Successfully created a pull-to-push task.

{
  "task_id" : "7864b3dc-e92f-42db-a754-08e627b6d8dd",
  "request_id" : "85968475-e92f-42db-a754-08e627b6d8dd"
}

Status code: 400

Failed to create the pull-to-push task.

{
  "error_code" : "LIVE.100011001",
  "error_msg" : "Request Illegal",
  "request_id" : "85968475-e92f-42db-a754-08e627b6d8dd"
}

Status Codes

Status Code

Description

200

Successfully created a pull-to-push task.

400

Failed to create the pull-to-push task.

Error Codes

See Error Codes.

Parent topic: Stream Pull Management