調用StartRtcCloudRecording API啟動即時音視頻雲端錄製-ApsaraVideo for Live-阿里雲

啟動rtc雲端錄製任務。

介面說明

雲端錄製屬於收費功能，收費詳情請參見雲端錄製費用。

服務存取點

本介面可用的服務存取點包括：

地區名稱	地區 ID	公網接入地址
上海	cn-shanghai	live.aliyuncs.com
新加坡	ap-southeast-1	live.ap-southeast-1.aliyuncs.com
美國（維吉尼亞）	us-east-1	live.us-east-1.aliyuncs.com

QPS 限制

本介面的單使用者 QPS 限制為 50 次/秒。超過限制，API 呼叫會被限流，這可能會影響您的業務，請合理調用。

調試

您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

調試

授權資訊

下表是API對應的授權資訊，可以在RAM權限原則語句的Action元素中使用，用來給RAM使用者或RAM角色授予調用此API的許可權。具體說明如下：

操作：是指具體的許可權點。
存取層級：是指每個操作的存取層級，取值為寫入（Write）、讀取（Read）或列出（List）。
資源類型：是指操作中支援授權的資源類型。具體說明如下：
- 對於必選的資源類型，用前面加 * 表示。
- 對於不支援資源級授權的操作，用全部資源表示。
條件關鍵字：是指雲產品自身定義的條件關鍵字。
關聯操作：是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權，操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

live:StartRtcCloudRecording

create

*全部資源

*

無

請求參數

名稱	類型	必填	描述	樣本值
AppId	string	是	待錄製的頻道所屬 app 的 id。該 app 需要歸屬於當前調用介面帳號所屬的主帳號。	******-7074--9ef5-85c19a4***
ChannelId	string	是	待錄製的頻道對應的 id。需要確保調用本介面時，該頻道內有使用者，否則會建立錄製任務失敗。	room1024
SubscribeParams	object	是	訂閱相關參數。
SubscribeUserIdList	array<object>	是	訂閱的 UserId 資訊列表，單流錄製模式下，會對其中每個 UserId 分別進行錄製；混流錄製模式下，會將所有 UserId 的音視頻混合到一組音視頻中。說明數組不可為空，並且最多支援 17 個元素。
	object	否	訂閱的 UserId 的資訊。
UserId	string	是	訂閱的 UserId。	userA
StreamType	integer	否	訂閱的 UserId 的媒體類型。取值： 0：原始流，即包括音頻和視頻。（預設值） 1：僅音頻流。 2：僅視頻流（混流錄製模式下有效）。	0
SourceType	integer	否	該 UserId 的視頻輸入資料流類型，僅訂閱非純音頻流時（StreamType!=1）有效。取值： 0：網路攝影機。（預設值） 1：螢幕畫面分享。	0
RecordParams	object	是	錄製相關參數。
RecordMode	integer	是	錄製模式。取值： 0：單流錄製模式，對於訂閱的每個 UserId，各自產生錄製檔案。 1：混流錄製模式，對於訂閱的 UserId，將這些使用者的流進行混合轉碼後，僅產生一組錄製檔案。	0
StreamType	integer	否	錄製的輸出資料流的媒體類型。取值： 0：原始流，即包括音頻和視頻。（預設值） 1：僅音頻流。 2：僅視頻流。	0
MaxFileDuration	integer	否	錄製檔案最大時間長度（秒）。超過該時間長度的錄製檔案會被分割。取值範圍須在[180,7200]內，即最大 2 小時。不指定時，則預設 2 小時。	7200
StorageParams	object	是	儲存相關參數。
StorageType	integer	是	儲存方式。取值： 0：VOD 1：OSS	1
FileInfo	array<object>	否	檔案儲存體資訊，用於指定錄製檔案的格式、儲存位置和命名，僅在 StorageType 為 OSS 時有效。說明對於數組中每個元素，會分別產生對應配置的錄製檔案。不設定時，預設包含 HLS 格式的配置；設定時，如果未包含 HLS 格式的配置，會自動產生 HLS 格式的預設配置。
	object	否	不同檔案格式的儲存配置。
Format	string	是	檔案儲存體格式。取值： HLS MP4 MP3	HLS
FileNamePattern	string	否	檔案命名格式。可以由以下變數按任意順序選擇並組合： AppId ChannelId UserId（單流模式下必選；混流模式下無效，選擇的話會保留為{UserId}字串） RecordMode 值為 0 時對應 Single 值為 1 時對應 Mix SourceType 單流模式下，當流類型為純視頻流時，配置生效，SourceType 可配置為：當值為 0 時，對應 C（Camera）網路攝影機視頻流。當值為 1 時，對應 S（Screen）螢幕畫面分享視頻流。單流模式下，當流類型為純音頻流時，SourceType 自動設定為 A（Audio），用於標識該錄製內容為純音頻流。單流模式下，當流類型為原始流時，配置生效，SourceType 可配置為：當值為 0 時，對應 OC（Original Camera）網路攝影機原始流。當值為 1 時，對應 OS（Original Screen）螢幕畫面分享原始流。其他情境下，SourceType 配置無效，若使用者手動設定了 SourceType，系統將會保留{SourceType}預留位置字串。 StreamType（使用 RecordParams 參數下的 StreamType 參數）當值為 0 時對應 AV（Audio Video）音頻流與視頻流。當值為 1 時對應 A（Audio）音頻流。當值為 2 時對應 V（Video）視頻流。 StartTime：開始錄製的時間，為東八區時區，格式類似 2025-03-25-11:27:28。（不使用預設值時必選）預設值如下：單流錄製模式 {AppId}_{ChannelId}_{UserId}_{StartTime} 如果同時訂閱了同一個 UserId 的不同 StreamType 或不同 SourceType，則預設值為{AppId}_{ChannelId}_{UserId}_{SourceType}_{StartTime} 混流錄製模式 {AppId}_{ChannelId}_{StartTime} 說明字串只能由以上變數組成，變數名需要用{}包裹，變數名之間用一個底線（_）分隔，每個變數至多在字串內出現一次。當命名為 xxx 後，檔案最終會儲存為類似 TaskId/xxx.m3u8 的形式，其中 TaskId 是在啟動雲端錄製任務時產生的任務 id，會自動添加到儲存路徑中。	{AppId}_{ChannelId}_{StartTime}_{UserId}
SliceNamePattern	string	否	切片命名格式，僅在 HLS 格式下有效。與 FileNamePattern 類似，只是可選變數多出了 Sequence： AppId ChannelId UserId（單流模式下必選；混流模式下無效，選擇的話會保留為{UserId}字串） RecordMode 值為 0 時對應 Single 值為 1 時對應 Mix SourceType 單流模式下，當流類型為純視頻流時此參數生效，SourceType 可配置為：取值為 0，對應 C（Camera）網路攝影機視頻流。取值為 1，對應 S（Screen）螢幕畫面分享流。單流模式下，當流類型為純音頻流時，SourceType 自動設定為 A（Audio），用於標識該錄製內容為純音頻流。單流模式下，當流類型為原始流時，配置生效，SourceType 可配置為：當值為 0 時，對應 OC（Original Camera）網路攝影機原始流。當值為 1 時，對應 OS（Original Screen）螢幕畫面分享原始流。其他情境下，SourceType 配置無效，若使用者手動設定該參數，系統將保留`{SourceType}`預留位置字串。 StreamType（使用 RecordParams 參數下的 StreamType 參數）當值為 0 時對應 AV（Audio Video）包含音頻流與視頻流。當值為 1 時對應 A（Audio ）音頻流。當值為 2 時對應 V（Video）視頻流。 StartTime：開始錄製的時間，為東八區時區，格式類似 2025-03-25-11:27:28。（不使用預設值時必選）。 Sequence：HLS 格式下，ts 檔案名稱中包含 Sequence，其他格式下無效。（不使用預設值時必選）。預設值如下：單流錄製模式 {AppId}_{ChannelId}_{UserId}_{StartTime}_{Sequence} 如果同時訂閱了同一個 UserId 的不同 StreamType 或不同 SourceType，則預設值為{AppId}_{ChannelId}_{UserId}_{SourceType}_{StartTime}_{Sequence} 混流錄製模式 {AppId}_{ChannelId}_{StartTime}_{Sequence} 說明字串只能由以上變數組成，變數名需要用{}包裹，變數名之間用一個底線（_）分隔，每個變數至多在字串內出現一次。當命名為 xxx 後，切片檔案最終會儲存為類似 TaskId/xxx.ts 的形式，其中 TaskId 是在啟動雲端錄製任務時產生的任務 id，會自動添加到儲存路徑中。	{AppId}_{ChannelId}_{StartTime}_{Sequence}
FilePathPrefix	array	否	檔案儲存體路徑。數組中的元素對應每一級目錄，例如參數值為["dir1","dir2"]時，xxx.m3u8 檔案將被儲存為 dir1/dir2/TaskId/xxx.m3u8。該參數為空白時，上述例子將直接儲存為 TaskId/xxx.m3u8。路徑結尾會自動補充任務的 TaskId，以避免不同任務的錄製檔案混在一起。如果設定了 FilePathPrefix，那麼數組中每個元素，只能由英文字母（a-zA-Z）、數字（0-9）、虛線（-）、底線（_）組成，並且不可為空字串。數組中各層路徑拼接好後，總長度不能超過 128 個字元（包括串連的'/'，不包括自動填入的 TaskId）。例如參數值為["dir1","dir2"]，那麼拼接好的路徑就是"dir1/dir2/"，也即數組中所有元素的總字元數與數組長度之和（對應每層路徑後的"/"），不得超過 128。數組中元素個數不得超過 5，即最多自訂 5 層路徑。
	string	否	每一級目錄名。	dir1
SliceDuration	integer	否	指定切片時間長度，單位為秒，僅 HLS 格式下有效，取值範圍須在[10,30]內。（預設值為 30）沒有特殊需求時，建議直接使用預設值。	30
OSSParams	object	否	OSS 儲存配置。當儲存方式為 OSS 時必須配置，當儲存方式為 VOD 時無效。
OSSEndpoint	string	是	OSS 儲存的 Endpoint 名稱。所對應的 regionId 需要與選擇的服務存取點一致。	oss-cn-shanghai.aliyuncs.com
OSSBucket	string	是	OSS 儲存的 Bucket 名稱。該 Bucket 需要歸屬於當前調用介面帳號所屬的主帳號。	mytest-bucket
VodParams	object	否	VOD 儲存配置。當儲存方式為 VOD 時必須配置，當儲存方式為 OSS 時無效。說明美國（維吉尼亞）地區暫不支援錄製到 VOD。
StorageLocation	string	否	點播控制台->媒資管理配置->儲存管理中包含的儲存地址，錄製檔案會先儲存到這裡，再上傳到 VOD。說明請確保該儲存地址所在地區與選擇的服務存取點一致。	mytest.oss-cn-shenzhen.aliyuncs.com
VodTranscodeGroupId	string	否	點播轉碼模板組 ID。說明請確保該轉碼模板組 ID 所在地區與選擇的服務存取點一致。	**8a914d3989e9825eb90530b2**
AutoCompose	integer	否	自動合并。取值： 0：關閉自動合并。（預設值） 1：開啟自動合并。開啟時必須設定參數 ComposeVodTranscodeGroupId。	0
ComposeVodTranscodeGroupId	string	否	對自動合成出來的新視頻在點播服務中進行一次轉碼，所使用的點播轉碼模板組 ID。說明當 AutoCompose（是否開啟自動合并）設為 1 時，本參數才必填。如果結束錄製時，只有一個媒體資源檔案，那麼即便開啟自動合并，也不會觸發。自動合成和轉碼常見問題，請參見直播轉點播常見問題 FAQ。點播轉碼計費詳情，請參見媒資轉碼計費。	**4c34112cfe68248f2f77759c**
MixTranscodeParams	object	否	轉碼相關參數，單流錄製模式下不填，混流錄製模式下必填。
FrameFillType	integer	否	斷流補框架類型。取值： 0：補最後一幀。（預設值）	0
AudioBitrate	integer	是	音頻碼率（kbps），取值範圍須在[8, 500]內。混流模式下必填。	300
AudioChannels	integer	是	音頻聲道數。取值： 1：單通道。 2：雙通道。混流模式下必填。	2
AudioSampleRate	integer	是	音頻採樣率（Hz）。取值： 8000 16000 32000 44100 48000 混流模式下必填。	32000
VideoCodec	string	否	視頻編碼格式。取值： H.264（預設值） H.265	H.264
VideoBitrate	integer	否	視頻碼率（kbps），取值範圍須在[1,10000]內。混流模式下，期望錄製輸出包含畫面時必填，其他情況下無效。	5000
VideoFramerate	integer	否	視訊框架率（fps），取值範圍須在[1,60]內。混流模式下，期望錄製輸出包含畫面時必填，其他情況下無效。	30
VideoGop	integer	否	視頻 GOP，每 VideoGop 幀存在一個 I 幀，取值範圍須在[1,60]內。混流模式下，期望錄製輸出包含畫面時必填，其他情況下無效。	30
VideoHeight	integer	否	視頻高度（px），取值範圍須在[0,1920]內。（預設值為 0）	480
VideoWidth	integer	否	視頻寬度（px），取值範圍須在[0,1920]內。（預設值為 0）	640
MixLayoutParams	object	否	布局相關參數，單流錄製模式下不填，混流錄製模式下期望錄製出非純音頻檔案時必填。
MixBackground	object	否	混流全域背景圖。
RenderMode	integer	否	畫面輸出時的顯示模式。取值： 0：裁剪。（預設值） 1：縮放並顯示黑底。	0
Url	string	否	背景圖 URL，最大長度不超過 2048 個字元。	https://xxxx.com/photos/my-test-picture.png
UserPanes	array<object>	否	用於指定訂閱的使用者的視窗布局資訊，只有設定了布局資訊的 UserId，才會被放到畫面中。混流模式且錄製非純音頻檔案時必填。
	array<object>	否	畫面中視窗配置。
UserId	string	否	該視窗對應的 UserId。不設定 UserId 時，會按照訂閱的使用者進入頻道的順序依次填入視窗。這裡設定的 UserId 與 SourceType 的組合必須包含在 SubscribeUserIdList 中。訂閱純音頻流是不能加入到布局中的	userA
SourceType	integer	否	該 UserId 的視頻輸入資料流類型。不填寫 UserId 時，此處設定 SourceType 無效。取值： 0：網路攝影機。（預設值） 1：螢幕畫面分享。這裡設定的 UserId 與 SourceType 的組合必須包含在 SubscribeUserIdList 中。	0
Height	string	否	窗格高度，歸一化百分比。取值範圍須在[0,1]內。(預設為 0)	0.5
Width	string	否	窗格寬度，歸一化百分比。取值範圍須在[0,1]內。(預設為 0)	0.5
X	string	否	座標 X，歸一化百分比。取值範圍須在[0,1]內。(預設為 0)	0
Y	string	否	座標 Y，歸一化百分比。取值範圍須在[0,1]內。(預設為 0)	0
ZOrder	integer	否	疊放順序，0 為最底層，1 層在 0 層之上，以此類推。(預設為 0)	0
SubBackground	object	否	子畫面背景圖，當使用者關閉網路攝影機、或入會後未推流、或入會後中途離會時，會在布局位置填充為對應的圖片。
RenderMode	integer	否	子畫面輸出時的顯示模式。取值： 0：裁剪。（預設值） 1：縮放並顯示黑底。	0
Url	string	否	背景圖 URL，最大長度不超過 2048 個字元。	https://xxxx.com/photos/my-test-pane-picture.png
NotifyUrl	string	否	接受回調訊息地址。任務狀態訊息會通過 POST 方式，以 Json 格式推送到該地址，最大長度不超過 2048 個字元。回調訊息說明參考文檔。	http://xxxx/test/mycallback
NotifyAuthKey	string	否	回調訊息鑒權 key，預設不填，即不做鑒權。如果填寫，長度需要在[16,64]個字元內，且只由大小寫英文字母和數字組成。當 NotifyUrl 未填寫時，NotifyAuthKey 也無效。當設定有效 NotifyAuthKey 時，會在回調訊息內攜帶鑒權內容。	mytestkeymytestkey
NotifyFileUploadedFormat	array	否	指定的格式，在觸發錄製檔案建置事件（RecordFileUploaded）時，將發送回調訊息。
	string	否	需要接收回調的具體檔案格式。取值（可忽略大小寫）： SLICE HLS MP4 MP3 暫不支援 VOD 儲存模式。對於 OSS 儲存模式，選擇的格式要包含在 StorageParams.FileInfo 的檔案格式中。	MP4
MaxIdleTime	integer	否	空閑逾時時間，當任務處於空閑狀態的時間長度超過 MaxIdleTime 時，自動停止任務。單位為秒，範圍須在[10,14400]內，即最大 4 小時。（預設為 300 秒）對於混流錄製模式，當所有訂閱的使用者流都停止推流時算作空閑對於單流錄製模式，訂閱的流之間彼此獨立，任意一路流停止推流都算作空閑，達到 MaxIdleTime 後會停止該路流的錄製，當所有訂閱流都空閑逾時後，會停止整個雲端錄製任務。	600

對於單流錄製模式：
- 支援同時訂閱同一個 UserId 的網路攝影機和螢幕畫面分享，但 FileNamePattern 和 SliceNamePattern 參數中必須包含 SourceType 變數（避免出現錄製檔案互相覆蓋的情況）。
- 目前不支援只訂閱某個 UserId 的純視頻流。即在單流模式下，UserInfo.StreamType 的值不能設定為 2。
在單流錄製模式下：
- 如果 RecordParams.StreamType 是純音頻流（取值為 1），那麼 SubscribeParams 中不能存在訂閱純視頻的情況（即 SubscribeParams 取值為 2）。
- 如果 RecordParams.StreamType 是純視頻流（值為 2），那麼 SubscribeParams 中不能存在訂閱純音訊情況（即 SubscribeParams 取值為 1）。
在混流錄製模式下：
- 如果 RecordParams.StreamType 是純音頻流（值為 1），那麼 SubscribeParams 中不能所有 UserId 都只訂閱純視頻（即所有 SubscribeParams 取值為 2）。
- 如果 RecordParams.StreamType 是純視頻流（值為 2），那麼 SubscribeParams 中不能所有 UserId 都只訂閱純音頻（即所有 SubscribeParams 取值為 1）。
錄製過程中，如果中途 channel 關閉，需要在空閑時間長度內重新入會推流，否則任務將自動停止。

返回參數

名稱	類型	描述	樣本值
	object	返回內容。
RequestId	string	請求 id。	****58-5876--83CA-B56278****
TaskId	string	任務 id。	****73-8501--8ac1-72295a****

樣本

正常返回樣本

JSON格式

{
  "RequestId": "******58-5876-****-83CA-B56278******",
  "TaskId": "******73-8501-****-8ac1-72295a******"
}

錯誤碼

HTTP status code	錯誤碼	錯誤資訊	描述
400	InvalidParameter.NotifyUrl	%s, please check the notifyUrl.	參數NotifyUrl格式無效，請檢查。
400	InvalidParameter.StorageParams.FileInfo	%s, please check the fileInfo of storageParams.	參數FileInfo存在無效欄位，請檢查。
400	InvalidParameter.StorageParams.OSSParams	%s, please check the ossParams of storageParams.	參數OSSParams存在無效欄位，請檢查。
400	NotFound.OSSBucket	%s, please check the ossBucket of storageParams.	參數OSSBucket不存在。
400	InvalidParameter.SubscribeParams.SubscribeUserIdList	%s, please check the subscribeUserIdList of subscribeParams.	參數SubscribeUserIdList無效，請檢查。
400	InvalidParameter.MixLayoutParams.UserPanes	%s, please check the userPanes of mixLayoutParams.	參數UserPanes存在無效欄位，請檢查。
400	InvalidParameter.MixTranscodeParams	%s, please check the transcodeParams.	參數MixTranscodeParams存在無效欄位，請檢查。
400	MissingParameter	%s.	參數缺失
403	InvalidParameter.UserId	%s, please check the UserId.	UserId無效，請檢查。
404	InvalidParameter.ChannelId	%s, please check the channelId.
404	InvalidParameter.AppId	%s, please check the appId.	參數AppId無效，請檢查。
405	InvalidParameter.StorageParams.VodParams	%s, please check the vodParams of storageParams.
405	InvalidParameter.NotifyAuthKey	%s, please check the notifyAuthKey.
405	InvalidParameter.MaxIdleTime	%s, please check the maxIdleTime.
405	InvalidParameter.RecordParams	%s, please check the recordParams.
405	InvalidParameter.StorageParams.StorageType	%s, please check the storageType of storageParams.	參數StorageType無效，請檢查。
405	InvalidParameter.NotifyFileUploadedFormat	%s, please check the notifyFileUploadedFormat.	參數NotifyFileUploadedFormat無效，請檢查。

訪問錯誤中心查看更多錯誤碼。

變更歷史

更多資訊，參考變更詳情。