Starting a Single Stream Recording Job

Function

Starts a single stream recording job.

The naming rule of single-stream recording triggered by the API is as follows: {jobtype}_{jobid}_{roomid}_{userid}

If the value of jobtype is s, the job is a single stream recording job.

URI

POST /v2/apps/{app_id}/individual-stream-jobs

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
app_id	Yes	String	Application ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	Content type.
X-Auth-Token	No	String	User token. This parameter is mandatory when token authentication is used. It can be obtained by calling the IAM API that is used for obtaining a user token. The value of X-Subject-Token in the response header is the user token.
Authorization	No	String	Authentication information. This parameter is mandatory when AK/SK-based authentication is used.
X-Sdk-Date	No	String	Time when the request is sent. This parameter is mandatory when AK/SK-based authentication is used.
X-Project-Id	No	String	Project ID. This parameter is mandatory when AK/SK-based authentication is used.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
room_id	Yes	String	Room ID.
user_id	Yes	String	ID of the user who is selected. The ID must be unique in a single recording job.
is_record_audio	No	Boolean	Whether to record audios. true: Audios are recorded. false: Audios are not recorded. The default value is true.
video_type	No	String	Video stream type. The options are camera stream and screen sharing stream. If this parameter is not specified, the video is not recorded. CAMERASTREAM: camera video stream SCREENSTREAM: screen sharing video stream The default value is CAMERASTREAM.
select_stream_type	No	String	Resolution level for pulling a window. LD SD HD FHD The default value is FHD.
max_idle_time	No	Integer	Maximum duration of an idle channel. The value ranges from 5 to 43200. The default value is 30. Unit: second If the channel is not connected for a period longer than the value of this parameter, the recording program automatically exits. If the start request is called again after the exit, a new recording task is generated. The co-host refers to a joiner or publisher.
publish_param	No	PublishParam object	Forwarding parameters.
record_param	No	RecordParam object	Recording parameters.

**Table 4** PublishParam
Parameter	Mandatory	Type	Description
rtmp_urls	Yes	Array of strings	RTMP stream push URL after a mixed stream streaming job is complete.

**Table 5** RecordParam
Parameter	Mandatory	Type	Description
record_rule_id	Yes	String	Recording rule ID.

Response Parameters

Status code: 201

**Table 6** Response header parameters
Parameter	Type	Description
X-request-Id	String	Request ID for task tracing.

**Table 7** Response body parameters
Parameter	Type	Description
job_id	String	Job ID.
stream_name	String	Stream name.
app_id	String	Application ID.
room_id	String	Room ID.
user_id	String	ID of the user who is selected. The ID must be unique in a single recording job.
is_record_audio	Boolean	Whether to record audios. true: Audios are recorded. false: Audios are not recorded. The default value is true.
video_type	String	Video stream type. The options are camera stream and screen sharing stream. If this parameter is not specified, the video is not recorded. CAMERASTREAM: camera video stream SCREENSTREAM: screen sharing video stream The default value is CAMERASTREAM.
select_stream_type	String	Resolution level for pulling a window. LD SD HD FHD The default value is FHD.
max_idle_time	Integer	Maximum duration of an idle channel. The value ranges from 5 to 43200. The default value is 30. Unit: second If the channel is not connected for a period longer than the value of this parameter, the recording program automatically exits. If the start request is called again after the exit, a new recording task is generated. The co-host refers to a joiner or publisher.
record_param	RecordParam object	Recording parameters.
create_time	String	Creation time, for example, 2006-01-02T15:04:05.075Z. The time zone is UTC.
update_time	String	Update time, for example, 2006-01-02T15:04:05.075Z. The time zone is UTC.
state	String	Job status. INIT: The job is being initialized. RUNNING: The job is running. STOPPED: The job has been stopped.
stop_reason	String	Job termination cause.
description	String	Detailed description of the job status.
start_time	String	Time when a job starts, for example, 2006-01-02T15:04:05.075Z. The time zone is UTC.
stop_time	String	Time when a job ends, for example, 2006-01-02T15:04:05.075Z. The time zone is UTC.

**Table 8** RecordParam
Parameter	Type	Description
record_rule_id	String	Recording rule ID.

Status code: 400

**Table 9** Response header parameters
Parameter	Type	Description
X-request-Id	String	Request ID for task tracing.

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Description.

Status code: 404

**Table 11** Response header parameters
Parameter	Type	Description
X-request-Id	String	Request ID for task tracing.

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Description.

Status code: 500

**Table 13** Response header parameters
Parameter	Type	Description
X-request-Id	String	Request ID for task tracing.

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Description.

Example Requests

POST https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/individual-stream-jobs

{
  "room_id" : 100,
  "user_id" : "user001",
  "is_record_audio" : true,
  "video_type" : "CAMERASTREAM",
  "select_stream_type" : "FHD",
  "max_idle_time" : 30,
  "record_param" : {
    "record_rule_id" : "5f5e172b9016ed5b0961a43"
  }
}

Example Responses

Status code: 201

The job is created, and the job summary information is returned, including job_id.

{
  "job_id" : 1,
  "app_id" : 1,
  "room_id" : 100,
  "user_id" : "user001",
  "is_record_audio" : true,
  "video_type" : "CAMERASTREAM",
  "select_stream_type" : "FHD",
  "max_idle_time" : 30,
  "publish_param" : {
    "rtmp_urls" : [ "rtmp://your.rtmp-server.com" ]
  },
  "record_param" : {
    "record_rule_id" : "5f5e172b9016ed5b0961a43"
  },
  "create_time" : "2006-01-02T15:04:05.075Z",
  "start_time" : "2006-01-02T15:04:05.075Z"
}

Status code: 400

Failed to create the single stream recording job because the request cannot be understood by the server or parameters are incorrect.

{
  "error_code" : "RTC.00001003",
  "error_msg" : "InvalidParameterValue"
}

Status code: 404

Failed to create the single stream recording job because the application does not exist.

{
  "error_code" : "RTC.00001003",
  "error_msg" : "InvalidParameterValue"
}

Status code: 500

Failed to create the single stream recording job due to server error.

{
  "error_code" : "RTC.00002xxx",
  "error_msg" : "InternalError"
}

Status Codes

Status Code	Description
201	The job is created, and the job summary information is returned, including job_id.
400	Failed to create the single stream recording job because the request cannot be understood by the server or parameters are incorrect.
404	Failed to create the single stream recording job because the application does not exist.
500	Failed to create the single stream recording job due to server error.