All Products
Search

This Product

    ApsaraVideo Live:AddCasterComponent

    Document Center

    ApsaraVideo Live:AddCasterComponent

    Last Updated:Dec 24, 2025

    Call the AddCasterComponent operation to add a component to a production studio.

    Operation description

    Before you call this operation, create a production studio and review its layout list. This operation adds image, text, and caption components. For more information about how to create a production studio by calling an API, see Create a production studio.

    QPS limit

    The queries per second (QPS) limit for a single user is 10. If you exceed this limit, API calls are throttled, which may affect your business. Plan your calls accordingly.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    live:AddCasterComponent

    create

    *Caster

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

    		 None None

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    CasterId

    string

    Yes

    The ID of the region.

    LIVEPRODUCER_POST-cn-0pp1czt****
    ComponentName

    string

    No

    The production studio ID.

    • If you create the production studio by calling the CreateCaster operation, find the ID in the CasterId parameter of the response.

    • If you create the production studio in the Live console, go to the Live Console > Production Studio > Cloud Production Studio page. The name of the production studio in the list is its ID.

    Note

    The name of the production studio in the list on the Cloud Production Studio page is the production studio ID.

    text01
    LocationId

    string

    Yes

    The name of the component. The default value is the component ID.

    RC01
    ComponentType

    string

    Yes

    Specifies the component's position. The format is RC01 to RC99. Each position can hold only one component.

    Note

    If the component type is caption, this parameter specifies the Location of the referenced video source.

    text
    Effect

    string

    No

    The type of component. Valid values:

    • text: A text component. The TextLayerContent parameter is also required.

    • image: An image component. The ImageLayerContent parameter is also required.

    • caption: A caption component. The CaptionLayerContent parameter is also required.

    animateH
    ComponentLayer

    string

    Yes

    The effect of the component. Valid values:

    • none (default): No effect.

    • animateH: Scrolls horizontally.

    • animateV: Scrolls vertically.

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

    string

    No

    The size and layout of the component layer. The layout is defined by the following elements:

    • HeightNormalized: The normalized height value.

    • WidthNormalized: The normalized width value.

    • PositionNormalized: The normalized position values for the layer.

    • PositionRefer: The reference coordinates for the layer's position.

    The value is a JSON string. Use upper camel case for field names.

    cover
    TextLayerContent

    string

    No

    The layer order of the component.

    • cover: The component is in the foreground.

    • background: The component is in the background.

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

    string

    No

    The properties of the layer element are as follows:

    Important This parameter is required only when ComponentType is set to text.

    • SizeNormalized: The normalized font size. This value is calculated as font_size/output_height. The valid range is [0,1]. If the font size calculated from the normalized value exceeds 1024, the size is set to 1024.

    • BorderWidthNormalized: The normalized width of the text border. This value is calculated based on the font size: BorderWidth/FontSize. The valid range is [0,1]. If the width calculated from the normalized value exceeds 16, the width is set to 16. The default value is 0.

    • FontName: The font name. For a list of valid fonts, see Production studio fonts. The default font is KaiTi.

    • BorderColor: The color of the text border. Valid values range from 0x000000 to 0xffffff. The default value is an empty string (""), which means no border appears.

    • Text: The text content. The default value is an empty string ("").

    • Color: The text color. The default value is 0xff0000, which represents red.

    The value must be a JSON-formatted string. Parameter names must be in UpperCamelCase.

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

    string

    No

    The properties of the layer component.

    Important This parameter is required when ComponentType is set to image.

    MaterialId: The ID of the media asset. This is the name assigned to the asset during upload.

    The value is a JSON string. The parameter names must be in UpperCamelCase.

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

    string

    No

    The properties of the layer element are as follows:

    Important This parameter is required when ComponentType is set to caption.

    • SizeNormalized: The normalized font size. This value is calculated as `font_size/output_height`. The valid range is `[0,1]`, accurate to two decimal places. If the font size derived from this normalized value is greater than 1024, the value is capped at 1024.

    • BorderWidthNormalized: The normalized width of the text border, relative to the font size. This value is calculated as `BorderWidth/FontSize`. The valid range is `[0,1]`, accurate to two decimal places. If the border width derived from this normalized value is greater than 16, the value is capped at 16. The default value is 0.

    • FontName: The font name. For valid values, see Caster font instructions. The default value is "KaiTi".

    • BorderColor: The color of the text border. The value is a hexadecimal color code that ranges from `0x000000` to `0xffffff`. The default value is an empty string `""`, which indicates that no border color is set.

    • LocationId: The channel ID of the translation source.

    • SourceLan: The original audio language of the video source. Valid values: `en` (English), `cn` (Chinese), `es` (Spanish), and `ru` (Russian). The default value is `cn`.

    • TargetLan: The target audio language for the video source. Leave this parameter empty to perform only speech recognition. Set this parameter to a language code to translate the audio. Valid values: `en` (English), `cn` (Chinese), `es` (Spanish), and `ru` (Russian).

    • ShowSourceLan: Specifies whether to display the source language in the captions. Valid values: `true` and `false`. The default value is `false`.

    • Truncation: Specifies whether captions can be truncated. Valid values: `true` and `false`. The default value is `false`.

    • SourceLanPerLineWordCount: The maximum number of words per line for the source language captions. The default value is 20.

    • TargetLanPerLineWordCount: The maximum number of words per line for the target language captions. The default value is 20.

    • SourceLanReservePages: The number of lines to reserve for the source language captions. This parameter takes effect only when `Truncation` is set to `true`. The default value is 2.

    • TargetLanReservePages: The number of lines to reserve for the target language captions. This parameter takes effect only when `Truncation` is set to `true`. The default value is 2.

    The value must be a JSON-formatted string. The property names must be in UpperCamelCase.

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

    Cloud Director fonts

    FontFontName value
    KaiTiKaiTi
    Alibaba PuHuiTi - RegularAlibabaPuHuiTi-Regular
    Alibaba PuHuiTi - BoldAlibabaPuHuiTi-Bold
    Alibaba PuHuiTi - LightAlibabaPuHuiTi-Light
    Source Han Sans - RegularNotoSansHans-Regular
    Source Han Sans - BoldNotoSansHans-Bold
    Source Han Sans - LightNotoSansHans-Light

    Response elements

    Element

    Type

    Description

    Example

    object

    ComponentId

    string

    The component ID. Use this ID to query, modify, or delete the component.

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

    string

    The request ID.

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

    Examples

    Success response

    JSON format

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

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 InvalidUserId.Malformed %s, please check userId. The userId passed in is invalid, please check.
    400 InvalidCasterId.Malformed %s, please check and try again later. The parameter CasterId is invalid, please check and try again.
    400 MissingParameter %s. Missing parameter
    400 InvalidParameter.Malformed There are invalid parameters: %s. There are invalid parameters: %s.
    400 InvalidPositionNormalized.Malformed %s, please check and try again later. The parameter PositionNormalized is invalid, please check and try again.
    400 DuplicateLocationID %s, please check and try again later. The parameter LocationID duplicate. Check and try again.
    401 IllegalOperation %s, please check and try again later. Operation not allowed, please check and try again.
    500 InternalError %s, please try again later. Internal error, please try again later.
    404 InvalidCaster.NotFound %s, please check and try again later. The guide station does not exist, please check and try again.
    404 CanvasNotExist %s, please check and try again later. Canvas does not exist, please check and try again.

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.