全部產品
Search
文件中心

ApsaraVideo Live:AddCasterComponent - 添加導播台組件

更新時間:Jan 15, 2026

添加導播台組件。

介面說明

請先建立導播台、瞭解導播台的布局列表後再調用本介面添加導播台組件。本介面目前支援添加圖片、文字、字幕三類組件。使用 API 建立導播台,請參見建立導播台

QPS 限制

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

調試

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

調試

授權資訊

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

  • 操作:是指具體的許可權點。

  • 存取層級:是指每個操作的存取層級,取值為寫入(Write)、讀取(Read)或列出(List)。

  • 資源類型:是指操作中支援授權的資源類型。具體說明如下:

    • 對於必選的資源類型,用前面加 * 表示。

    • 對於不支援資源級授權的操作,用全部資源表示。

  • 條件關鍵字:是指雲產品自身定義的條件關鍵字。

  • 關聯操作:是指成功執行操作所需要的其他許可權。操作者必須同時具備關聯操作的許可權,操作才能成功。

操作

存取層級

資源類型

條件關鍵字

關聯操作

live:AddCasterComponent

create

*Caster

acs:live:*:{#accountId}:caster/{#CasterId}

請求參數

名稱

類型

必填

描述

樣本值

RegionId

string

地區 ID。

cn-shanghai

CasterId

string

導播台 ID。

  • 如果您通過 CreateCaster 介面建立導播台,請查看 CreateCaster 介面調用返回的參數 CasterId 值。

  • 如果您通過直播控制台建立導播台,請通過直播控制台 > 導播台 > 雲導播台頁面查看。

說明

直播控制台雲導播台頁面導播台列表中的導播台名稱即導播台 ID。

LIVEPRODUCER_POST-cn-0pp1czt****

ComponentName

string

組件名稱。預設為組件 ID。

text01

LocationId

string

用於指定組件位置,每個位置至多設定一個組件,格式需符合“RC01~RC99”。

說明

組件類型為 caption 時,表示引用的視頻源 Location。

RC01

ComponentType

string

組件類型。取值:

  • text:文字組件。如果選擇 text 類型,必須同時佈建要求參數 TextLayerContent。

  • image:圖片組件。如果選擇 image 類型,必須同時佈建要求參數 ImageLayerContent。

  • caption:翻譯跑馬燈元件。如果選擇 caption 類型,必須同時佈建要求參數 CaptionLayerContent。

text

Effect

string

組件顯示的特效 。取值:

  • none(預設值):無。

  • animateH:水平滾動。

  • animateV:垂直滾動。

animateH

ComponentLayer

string

該組件 Layer 的尺寸,布局等資訊。設定元素說明如下:

  • HeightNormalized:高度歸一化比例值。

  • WidthNormalized:寬度歸一化比例值。

  • PositionNormalized:layer 元素的位置歸一化值。

  • PositionRefer:元素的位置參考座標值。

JSON 格式字串,參數名採用首字母大寫、駝峰格式。

{"HeightNormalized":"1","PositionRefer":"topRight","WidthNormalized":"0","PositionNormalized":["0.1","0.2"]}

LayerOrder

string

組件層疊次序。

  • cover:覆蓋。

  • background:背景。

cover

TextLayerContent

string

Layer 元素屬性。元素屬性說明如下:

重要 當 ComponentType 為 text 時,本參數才可用且必傳。

  • SizeNormalized:字型歸一化大小,字型設定大小為“font_size/output_height”,取值範圍[0,1],如果系統根據歸一化方式反計算出來的字型大小大於 1024,取 1024。

  • BorderWidthNormalized:文字邊框寬度歸一化值,該歸一化值是基於文字的 size 來計算的,即“BorderWidth/FontSize”,取值範圍[0,1],如果根據歸一化方式反計算出來的值超過 16,取 16,預設 0。

  • FontName:字型名稱,取值請參見導播台字型說明,預設楷體,“KaiTi”。

  • BorderColor:文字邊框色彩,取值“0x000000-0xffffff”,預設“”,表示無效。

  • Text:常值內容,預設“”。

  • Color:文字色彩,預設“0xff0000”,紅色。

JSON 格式字串,參數名採用首字母大寫,駝峰格式。

{"BorderWidthNormalized":"1","SizeNormalized":"0.2","Color":"0x000000","FontName":"KaiTi","BorderColor":"0x000000","Text":"hello world!"}

ImageLayerContent

string

Layer 元素屬性。元素屬性說明如下:

重要 ComponentType 為 image 時,該參數必傳。

MaterialId:媒資庫素材 ID。上傳素材時設定的名稱就是媒資庫素材 ID。

JSON 格式字串,參數名採用首字母大寫,駝峰格式。

{"MaterialId":"6cf724c6ebfd4a59b5b3cec6f10d****"}

CaptionLayerContent

string

Layer 元素屬性。元素屬性說明如下:

重要 當 ComponentType 為 caption 時,該參數必傳。

  • SizeNormalized:字型歸一化大小,字型設定大小為“font_size/output_height”,取值範圍[0,1],精確到小數點後兩位,如果系統根據歸一化方式反計算出來的字型大小大於 1024,取 1024

  • BorderWidthNormalized:文字邊框寬度歸一化值,該歸一化值是基於文字的 size 來計算的,即“BorderWidth/FontSize”,取值範圍[0,1],精確到小數點後兩位,如果根據歸一化方式反計算出來的值超過 16,取 16,預設 0

  • FontName:字型名稱,取值請參見雲導播字型說明,預設楷體,“KaiTi”。

  • BorderColor:文字邊框色彩,取值“0x000000-0xffffff”,預設“”,表示無效。

  • LocationId: 翻譯源的 channelId。

  • SourceLan: 視頻源的原始音頻語言。En-英文,cn-中文,es-西班牙文,ru-俄文,預設為 cn-中文。

  • TargetLan:視頻源的目標音頻語言。不設定表示語音辨識,設定表示翻譯。取值:en-英文,cn-中文,es-西班牙文,ru-俄文,cn-中文。

  • ShowSourceLan:是否顯示源語言。取值:true-顯示,false-不顯示,預設為 false。

  • Truncation:字幕是否可以被截斷。取值:true-可以被截斷,false-不可以被截斷,預設為 false。

  • SourceLanPerLineWordCount:源語言每行字數,預設 20。

  • TargetLanPerLineWordCount:目標語言每行字數,預設 20。

  • SourceLanReservePages:源語言保留行數,Truncation 為 true 的時候生效,預設 2 行。

  • TargetLanReservePages:目標語言保留行數,Truncation 為 true 的時候生效,預設 2 行。

JSON 格式字串,參數名採用首字母大寫,駝峰格式。

{"BorderWidthNormalized":0.01,"SizeNormalized":0.05,"Color":"0x000000","LocationId":"RV01","SourceLan":"cn","FontName":"KaiTi","BorderColor":"0xffffff"}

HtmlLayerContent

string

H5 組件配置。

{"htmlUrl":http://caster.example.com}

雲導播字型說明

字型FontName 取值
楷體KaiTi
阿里巴巴普惠體-常規AlibabaPuHuiTi-Regular
阿里巴巴普惠體-粗體AlibabaPuHuiTi-Bold
阿里巴巴普惠體-細體AlibabaPuHuiTi-Light
思源黑體-常規NotoSansHans-Regular
思源黑體-粗體NotoSansHans-Bold
思源黑體-細體NotoSansHans-Light

返回參數

名稱

類型

描述

樣本值

object

ComponentId

string

組件 ID。可作為查詢導播台組件、修改導播台組件、刪除導播台組件的請求參數。

21926b36-7dd2-4fde-ae25-51b5bc8e****

RequestId

string

請求 ID。

16A96B9A-F203-4EC5-8E43-CB92E68F4CD8

樣本

正常返回樣本

JSON格式

{
  "ComponentId": "21926b36-7dd2-4fde-ae25-51b5bc8e****",
  "RequestId": "16A96B9A-F203-4EC5-8E43-CB92E68F4CD8"
}

錯誤碼

HTTP status code

錯誤碼

錯誤資訊

描述

400 InvalidUserId.Malformed %s, please check userId. 傳入的userId無效,請檢查。
400 InvalidCasterId.Malformed %s, please check and try again later. 參數CasterId無效,請檢查後重試。
400 MissingParameter %s. 參數缺失
400 InvalidParameter.Malformed There are invalid parameters: %s. 存在無效參數:%s。
400 InvalidPositionNormalized.Malformed %s, please check and try again later. 參數PositionNormalized無效,請檢查後重試。
400 DuplicateLocationID %s, please check and try again later. 參數LocationID重複,請檢查後重試。
401 IllegalOperation %s, please check and try again later. 不允許的操作,請檢查後重試。
500 InternalError %s, please try again later. 內部錯誤,請稍後重試。
404 InvalidCaster.NotFound %s, please check and try again later. 導播台不存在,請檢查後重試。
404 CanvasNotExist %s, please check and try again later. Canvas不存在,請檢查後重試。

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

變更歷史

更多資訊,參考變更詳情