全部產品
Search
文件中心

ApsaraVideo Live:StartRtcCloudRecording

更新時間:Jul 14, 2026

啟動 RTC 雲端錄製任務。

介面說明

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

服務接入點

本介面可用的服務接入點包括:

地域名稱地域 ID公網接入地址
上海cn-shanghailive.aliyuncs.com
新加坡ap-southeast-1live.ap-southeast-1.aliyuncs.com
美國(維吉尼亞)us-east-1live.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 :

    原始流,即包括音訊和影片。

  • 1 :

    僅音訊流。

  • 2 :

    僅影片流。

0

SourceType

integer

該 UserId 的影片輸入流類型,僅訂閱非純音訊流時(StreamType!=1)有效。取值:

  • 0:攝影機。(預設值)

  • 1:螢幕分享。

枚舉值:

  • 0 :

    攝影機。

  • 1 :

    螢幕分享。

0

RecordParams

object

錄製相關參數。

RecordMode

integer

錄製模式。取值:

  • 0:單流錄製模式,對於訂閱的每個 UserId,各自產生錄製檔案。

  • 1:混流錄製模式,對於訂閱的 UserId,將這些使用者的流進行混合轉碼後,僅產生一組錄製檔案。

枚舉值:

  • 0 :

    單流錄製模式,對於訂閱的每個 UserId,各自產生錄製檔案。

  • 1 :

    混流錄製模式,對於訂閱的 UserId,將這些使用者的流進行混合轉碼後,僅產生一組錄製檔案。

0

StreamType

integer

錄製的輸出流的媒體類型。取值:

  • 0:原始流,即包括音訊和影片。(預設值)

  • 1:僅音訊流。

  • 2:僅影片流。

枚舉值:

  • 0 :

    原始流,即包括音訊和影片。

  • 1 :

    僅音訊流。

  • 2 :

    僅影片流。

0

MaxFileDuration

integer

錄製檔案最大時長(秒)。超過該時長的錄製檔案會被分割。取值範圍須在 [180,7200] 內,即最大 2 小時。不指定時,則預設 2 小時。

7200

StorageParams

object

儲存相關參數。

StorageType

integer

儲存方式。取值:

  • 0:VOD

  • 1:OSS

枚舉值:

  • 0 :

    VOD

  • 1 :

    OSS

1

FileInfo

array<object>

檔案儲存資訊,用於指定錄製檔案的格式、儲存位置和命名,僅在 StorageType 為 OSS 時有效。

說明

對於陣列中每個元素,會分別產生對應配置的錄製檔案。不設定任何格式時,會預設包含 HLS 格式的配置。

object

不同檔案格式的儲存配置。

Format

string

檔案儲存格式。取值:

  • HLS

  • MP4

  • MP3

枚舉值:

  • MP4 :

    MP4 格式。

  • MP3 :

    MP3 格式。

  • HLS :

    HLS 格式。

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 :

    關閉自動合併。

  • 1 :

    開啟自動合併。開啟時必須設定參數 ComposeVodTranscodeGroupId。

0

ComposeVodTranscodeGroupId

string

對自動合成出來的新影片在隨選視訊服務中進行一次轉碼,所使用的隨選視訊轉碼範本群組 ID。

說明
  • 當 AutoCompose(是否開啟自動合併)設為 1 時,本參數才必填。

  • 如果結束錄製時,只有一個媒體資源檔案,那麼即便開啟自動合併,也不會觸發。

  • 自動合成和轉碼常見問題,請參見直播轉隨選視訊常見問題 FAQ

  • 隨選視訊轉碼計費詳情,請參見媒資轉碼計費

****4c34112cfe68248f2f77759c****

MixTranscodeParams

object

轉碼相關參數,單流錄製模式下不填,混流錄製模式下必填。

FrameFillType

integer

斷流補幀類型。取值:

  • 0:補最後一幀。(預設值)

枚舉值:

  • 0 :

    補最後一幀。

0

AudioBitrate

integer

音訊位元率(kbps),取值範圍須在 [8, 500] 內。混流模式下必填。

300

AudioChannels

integer

音訊聲道數。取值:

  • 1:單通道。

  • 2:雙通道。

混流模式下必填。

枚舉值:

  • 1 :

    單通道。

  • 2 :

    雙通道。

2

AudioSampleRate

integer

音訊取樣率(Hz)。取值:

  • 8000

  • 16000

  • 32000

  • 44100

  • 48000

混流模式下必填。

枚舉值:

  • 8000 :

    8000HZ

  • 16000 :

    16000HZ

  • 32000 :

    32000HZ

  • 44100 :

    44100HZ

  • 48000 :

    48000HZ

32000

VideoCodec

string

影片編碼格式。取值:

  • H.264(預設值)

  • H.265

枚舉值:

  • H.264 :

    H.264 編碼。

  • H.265 :

    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 :

    裁剪。

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

    攝影機。

  • 1 :

    螢幕分享。

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 :

    裁剪。

  • 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無效,請檢查。
403 QuotaExceed.RunningTask The number of active cloud recording tasks has reached the limit. 活躍的雲端錄製任務數量達到上限。
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無效,請檢查。

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

變更歷史

更多資訊,參考變更詳情