啟動RTC雲端錄製任務。
介面說明
雲端錄製屬於收費功能,收費詳情請參見雲端錄製費用。
啟動錄製任務後,空閒狀態下(無任何推流),仍然會產生費用,因此請在錄製結束時及時呼叫 StopRtcCloudRecording,或者按照需要調小 MaxIdleTime。
服務端點
本介面可用的服務端點包括:
| 地域名稱 | 地域 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程式碼範例。
調試
授權資訊
|
操作 |
存取層級 |
資源類型 |
條件關鍵字 |
關聯操作 |
|
live:StartRtcCloudRecording |
create |
*全部資源。
|
無 | 無 |
請求參數
|
名稱 |
類型 |
必填 |
描述 |
樣本值 |
| AppId |
string |
是 |
待錄製的頻道所屬 app 的 id。該 app 需要歸屬於目前呼叫介面帳號所屬的主帳號。 |
********-7074-****-9ef5-85c19a4***** |
| ChannelId |
string |
是 |
待錄製的頻道對應的 id。需要確保呼叫本介面時,該頻道內有使用者,否則會建立錄製任務失敗。 |
room1024 |
| SubscribeParams |
object |
是 |
訂閱相關參數。 |
|
| SubscribeUserIdList |
array<object> |
是 |
訂閱的 UserId 資訊清單,單流錄製模式下,會對其中每個 UserId 分別進行錄製;混流錄製模式下,會將所有 UserId 的音訊與影片混合到一組音訊與影片中。 說明
|
|
|
object |
否 |
訂閱的 UserId 的資訊。 |
||
| UserId |
string |
是 |
訂閱的 UserId。 |
userA |
| StreamType |
integer |
否 |
訂閱的 UserId 的媒體類型。取值:
枚舉值:
|
0 |
| SourceType |
integer |
否 |
該 UserId 的影片輸入流類型,僅訂閱非純音訊流時(StreamType!=1)有效。取值:
枚舉值:
|
0 |
| RecordParams |
object |
是 |
錄製相關參數。 |
|
| RecordMode |
integer |
是 |
錄製模式。取值:
枚舉值:
|
0 |
| StreamType |
integer |
否 |
錄製的輸出流的媒體類型。取值:
枚舉值:
|
0 |
| MaxFileDuration |
integer |
否 |
錄製檔案最大時長(秒)。超過該時長的錄製檔案會被分割。取值範圍須在[180,7200]內,即最大 2 小時。不指定時,則預設 2 小時。 |
7200 |
| StorageParams |
object |
是 |
儲存相關參數。 |
|
| StorageType |
integer |
是 |
儲存方式。取值:
枚舉值:
|
1 |
| FileInfo |
array<object> |
否 |
檔案儲存資訊,用於指定錄製檔案的格式、儲存位置和命名,僅在 StorageType 為 OSS 時有效。 說明
對於陣列中每個元素,會分別產生對應設定的錄製檔案。不設定任何格式時,會預設包含 HLS 格式的設定。 |
|
|
object |
否 |
不同檔案格式的儲存設定。 |
||
| Format |
string |
是 |
檔案儲存格式。取值:
枚舉值:
|
HLS |
| FileNamePattern |
string |
否 |
檔案命名格式。可以由以下變數按任意順序選擇並組合:
預設值如下:
說明
|
{AppId}_{ChannelId}_{StartTime}_{UserId} |
| SliceNamePattern |
string |
否 |
切片命名格式,僅在 HLS 格式下有效。與 FileNamePattern 類似,只是可選變數多出了 Sequence:
預設值如下:
說明
|
{AppId}_{ChannelId}_{StartTime}_{Sequence} |
| FilePathPrefix |
array |
否 |
檔案儲存路徑。陣列中的元素對應每一層目錄,例如參數值為["dir1","dir2"]時,xxx.m3u8 檔案將被儲存為 dir1/dir2/TaskId/xxx.m3u8。該參數為空時,上述範例將直接儲存為 TaskId/xxx.m3u8。
|
|
|
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 時無效。 說明
|
|
| StorageLocation |
string |
否 |
點播主控台->媒體資源管理設定->儲存管理中包含的儲存位址,錄製檔案會先儲存到這裡,再上傳到 VOD。 說明
|
mytest.oss-cn-shenzhen.aliyuncs.com |
| VodTranscodeGroupId |
string |
否 |
點播轉碼範本群組 ID。 說明
|
****8a914d3989e9825eb90530b2**** |
| AutoCompose |
integer |
否 |
自動合併。取值:
枚舉值:
|
0 |
| ComposeVodTranscodeGroupId |
string |
否 |
對自動合成出來的新影片在點播服務中進行一次轉碼,所使用的點播轉碼範本群組 ID。 說明
|
****4c34112cfe68248f2f77759c**** |
| MixTranscodeParams |
object |
否 |
轉碼相關參數,單流錄製模式下不填,混流錄製模式下必填。 |
|
| FrameFillType |
integer |
否 |
斷流補幀類型。取值:
枚舉值:
|
0 |
| AudioBitrate |
integer |
是 |
音訊位元率(kbps),取值範圍須在[8, 500]內。混流模式下必填。 |
300 |
| AudioChannels |
integer |
是 |
音訊聲道數。取值:
混流模式下必填。 枚舉值:
|
2 |
| AudioSampleRate |
integer |
是 |
音訊取樣率(Hz)。取值:
混流模式下必填。 枚舉值:
|
32000 |
| VideoCodec |
string |
否 |
影片編碼格式。取值:
枚舉值:
|
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 |
| Url |
string |
否 |
背景圖 URL,最大長度不超過 2048 個字元。 |
https://xxxx.com/photos/my-test-picture.png |
| UserPanes |
array<object> |
否 |
用於指定訂閱的使用者的視窗版面配置資訊,只有設定了版面配置資訊的 UserId,才會被放到畫面中。混流模式且錄製非純音訊檔案時必填。 |
|
|
array<object> |
否 |
畫面中視窗配置。 |
||
| UserId |
string |
否 |
該視窗對應的 UserId。
|
userA |
| SourceType |
integer |
否 |
該 UserId 的視訊輸入流類型。不填寫 UserId 時,此處設定 SourceType 無效。取值:
這裡設定的 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 |
| Url |
string |
否 |
背景圖 URL,最大長度不超過 2048 個字元。 |
https://xxxx.com/photos/my-test-pane-picture.png |
| NotifyUrl |
string |
否 |
接收回呼訊息位址。任務狀態訊息會透過 POST 方式,以 JSON 格式推送到該位址,最大長度不超過 2048 個字元。 回呼訊息說明參考文件。 |
http://xxxx/test/mycallback |
| NotifyAuthKey |
string |
否 |
回呼訊息驗證金鑰,預設不填,即不進行驗證。如果填寫,長度需要在[16,64]個字元內,且只由大小寫英文字母和數字組成。
|
mytestkeymytestkey |
| NotifyFileUploadedFormat |
array |
否 |
指定的格式,在觸發錄製檔案產生事件(RecordFileUploaded)時,將發送回呼訊息。 |
|
|
string |
否 |
需要接收回呼的具體檔案格式。取值(可忽略大小寫):
暫不支援 VOD 儲存模式。 對於 OSS 儲存模式,選擇的格式要包含在 StorageParams.FileInfo 的檔案格式中。 |
MP4 |
|
| MaxIdleTime |
integer |
否 |
閒置逾時時間,當任務處於閒置狀態的時長超過 MaxIdleTime 時,自動停止任務。單位為秒,範圍須在[10,14400]內,即最大 4 小時。(預設為 300 秒)
|
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 無效,請檢查。 |
| 403 | QuotaExceed.RunningTask | The number of active cloud recording tasks has reached the limit. | 活躍的雲端錄製任務數量達到上限。 |
| 404 | InvalidParameter.ChannelId | %s, please check the channelId. | 參數 ChannelId 無效,請檢查。 |
| 404 | InvalidParameter.AppId | %s, please check the appId. | 參數 AppId 無效,請檢查。 |
| 405 | InvalidParameter.StorageParams.VodParams | %s, please check the vodParams of storageParams. | 參數 VodParams 存在無效欄位,請檢查。 |
| 405 | InvalidParameter.NotifyAuthKey | %s, please check the notifyAuthKey. | 參數 NotifyAuthKey 格式無效,請檢查。 |
| 405 | InvalidParameter.MaxIdleTime | %s, please check the maxIdleTime. | 參數 MaxIdleTime 無效,請檢查。 |
| 405 | InvalidParameter.RecordParams | %s, please check the recordParams. | 參數 RecordParams 存在無效欄位,請檢查。 |
| 405 | InvalidParameter.StorageParams.StorageType | %s, please check the storageType of storageParams. | 參數 StorageType 無效,請檢查。 |
| 405 | InvalidParameter.NotifyFileUploadedFormat | %s, please check the notifyFileUploadedFormat. | 參數 NotifyFileUploadedFormat 無效,請檢查。 |
訪問錯誤中心查看更多錯誤碼。
變更歷史
更多資訊,參考變更詳情。