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

Creating a Relay Task

Function

This API is used to create a relay task for pulling a stream from an external source and pushing it based on the settings 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, use the region of the origin server of the ingest domain name. The default value is the region that the tenant belongs to.

source_type

Yes

String

Source stream type.

PullLivePushLive: live-to-live

PullVodPushLive: VOD-to-live

source_urls

Yes

Array of strings

Source stream URL.

If source_type is set to PullLivePushLive, only one URL can be entered.

If source_type is set to PullVodPushLive, you can specify multiple source file URLs.

domain

No

String

Ingest domain name.

app_name

No

String

Application 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. The time format is as follows:

"2006-01-02T15:04:05Z"

The start time must be earlier than the end time. The default value is the current time.

end_time

No

String

Task end time. The time format is as follows:

"2006-01-02T15:04:05Z"

The end time must be later than the start time. The maximum allowed end time is seven days after the start time.

vod_loop_time

No

String

Number of playback rounds. This parameter is valid only when source_type is set to PullVodPushLive. The default value is -1. -1: plays the file list on an infinite loop until the specified end time arrives; N: plays the file list for N rounds. Playback stops when the round count is exhausted or the 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

Playback mode of source files. This parameter is valid only when source_type is set to PullVodPushLive. Default value: immediate_new_source

**immediate_new_source: immediately starts playback from a new file.

continue_from_file_start: resumes playback from the start of the last file that was streamed. This option is valid only for task updates.

continue_from_break_point: resumes playback from the exact breakpoint of the last file that was streamed. This option is valid only for task updates.

vod_start_video_index

No

Integer

Index of the file to be played. This parameter is valid only when source_type is set to PullVodPushLive. The default value is 0, indicating that the playback starts from the first file. The maximum value is len(source_urls) – 1.

vod_start_video_time

No

Integer

The default value is 0. This parameter indicates the second from which the specified file is played. This parameter is valid only when source_type is set to PullVodPushLive.

backup_source_type

No

String

Type of the standby source.

  • PullLivePushLive: livestreaming

Note:

  1. This parameter is valid only when source_type is set to PullVodPushLive.

  2. When the primary source stream is interrupted, the system automatically switches to the standby source stream.

backup_source_urls

No

Array of strings

Standby source URL. This parameter is valid only when source_type is set to PullVodPushLive.

callback_events

No

Array of strings

List of callback events. If this parameter is left blank, callbacks are sent for all events.

  • 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 notifications

callback_url

No

String

Callback URL.

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

The relay task was created.

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

Status code: 400

The relay task failed to be created.

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

Status Codes

Status Code

Description

200

The relay task was created.

400

The relay task failed to be created.

Error Codes

See Error Codes.

Parent topic: Stream Relay Management