全部產品
Search
文件中心

ApsaraVideo Live:StartRtcCloudRecording

更新時間:Sep 03, 2026

啟動RTC雲端錄製任務。

介面說明

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

說明
  • 啟動錄製任務後,空閒狀態下(無任何推流),仍然會產生費用,因此請在錄製結束時及時呼叫 StopRtcCloudRecording,或者按照需要調小 MaxIdleTime。

重要 本介面為非同步介面,呼叫成功不代表任務已經在錄製,強烈建議設定 NotifyUrl 入參以獲取目前任務狀態訊息。

服務端點

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

地域名稱地域 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。

說明
  • 當 StorageType=0(VOD 模式)時本參數必填。

  • 請確保該儲存位址所在區域與選擇的服務端點一致。

mytest.oss-cn-shenzhen.aliyuncs.com

VodTranscodeGroupId

string

否

點播轉碼範本群組 ID。

說明
  • 當 StorageType=0(VOD 模式)時本參數必填。

  • 請確保該轉碼範本群組 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

否

回呼訊息驗證金鑰,預設不填,即不進行驗證。如果填寫,長度需要在[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. 參數 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 無效,請檢查。

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

變更歷史

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