Configures a layout for a virtual studio.

Usage notes

You can call this operation to configure a common layout or a production studio layout for a virtual studio.

QPS limits

You can call this operation up to 10 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation. For more information, see QPS limit on an API operation in ApsaraVideo Live.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes AddStudioLayout

The operation that you want to perform.

Set the value to AddStudioLayout.

CasterId String Yes a2b8e671-2fe5-4642-a2ec-bf93880e****

The ID of the production studio instance.

Important You must create a production studio instance of the Virtual Studio type in advance. You can call the CreateCaster operation to create a production studio instance. Alternatively, you can log on to the ApsaraVideo Live console to create a production studio instance of the Virtual Studio type.
  • If you call the CreateCaster operation to create a production studio instance, you can obtain the instance ID from the CasterId parameter in the response.
  • If you create a production studio instance in the ApsaraVideo Live console, perform the following operations to obtain the instance ID: Log on to the ApsaraVideo Live console and click Production Studios in the left-side navigation pane. Then, view the instance ID on the Production Studio Management page.
Note The value displayed in the Name column for an instance on the Production Studio Management page is the ID of the instance.
LayoutName String Yes Test layout

The name of the layout.

LayoutType String Yes studio

The type of the layout. Valid values:

  • common: If you set this parameter to common, you must specify CommonConfig.
  • studio: If you set this parameter to studio, you must specify BgImageConfig and ScreenInputConfigList. The MediaInputConfigList parameter is optional.
RegionId String No cn-shanghai

The ID of the region.

CommonConfig String No {"ChannelId":"RV01" }

The common layout configurations. The value is a JSON string. For more information, see CommonConfig.

Important This parameter is required only if the LayoutType parameter is set to common.
BgImageConfig String No { "Id":"k12kj31****", "MaterialId":"f080575eb5f4427684fc0715159a****" }

The background image configurations. The value is a JSON string. For more information, see BgImageConfig.

Important This parameter is required only if the LayoutType parameter is set to studio.
ScreenInputConfigList String No [ { "Index":"1", "ChannelId":"RV01", "Color":"green", "PositionX":"0.1", "PositionY":"0.2", "HeightNormalized":"0.4" } ]

The input configurations for image matting. The value is a JSON string. For more information, see ScreenInputConfig.

Important This parameter is required only if the LayoutType parameter is set to studio.
MediaInputConfigList String No [ { "Id":"k12kj31****", "Index":"1", "ChannelId":"RV01", "FillMode":"none", "PositionRefer":"topLeft", "WidthNormalized":"0.4", "HeightNormalized":"0.4", "PositionNormalized":"[0.1, 0.2]" }, { "Id":"k12kj31****", "Index":"2", "ImageMaterialId":"lkajsdfsa8fd89asd8****", "FillMode":"none", "PositionRefer":"topLeft", "WidthNormalized":"0.6", "HeightNormalized":"0.4", "PositionNormalized":"[0.1, 0.2]" } ]

The multimedia input configurations. The value is a JSON string. For more information, see MediaInputConfig.

Important This parameter is optional and is valid only if the LayoutType parameter is set to studio.
LayerOrderConfigList String No [ { "Type":"media", "Id":"k12kj31****" }, { "Type":"media", "Id":"k12kj31****" } ]

The layer sorting configurations. The value is a JSON string. For more information, see layerOrderConfig.

You can sort layers of background and multimedia materials. The image matting layer cannot be sorted. The layer that is in the front of the code is placed behind the other layer in the layout.

CommonConfig

Parameter

Type

Example

Description

ChannelId

String

RV01

The ID of the channel that you want to bind to the video resource.

BgImageConfig

Note You can specify ImageUrl or MaterialId.

Parameter

Type

Example

Description

Id

String

k12kj31****

The unique ID of the background image.

ImageUrl

String

http://aliyundoc.com

The URL of the image.

MaterialId

String

f080575eb5f4427684fc0715159a****

The ID of the image in ApsaraVideo VOD.

ScreenInputConfig

Parameter

Type

Example

Description

Index

Integer

1

The sequence number of the image matting source. This parameter is displayed on the frontend but not used in the operation logic. The value must be a positive integer.

ChannelId

String

RV01

The ID of the channel that you want to bind to the video resource.

Color

String

green

The background color that you want to use for image matting. Valid values:

blue: the blue background

green: the green background

auto: automatic background recognition

complex: background replacement

PositionX

Float

0.1

The x-coordinate of the material. Valid values: [0,1].

The upper-left corner of the material is used as the coordinate origin.

PositionY

Float

0.2

The y-coordinate of the material. Valid values: [0,1].

The upper-left corner of the material is used as the coordinate origin.

HeightNormalized

Float

0.4

The normalized value of the material height. The value specifies the ratio of the height of the matted image to the height of the background image. Valid values: [0,1].

MediaInputConfig

  • If the multimedia material is a video, configure ChannelId.
  • If the multimedia material is an image, configure ImageMeterialId.
  • ChannelId and ImageMeterialId are mutually exclusive. You can specify ChannelId or ImageMeterialId.

Parameter

Type

Example

Description

Id

String

k12kj31****

The unique ID of the multimedia material.

Index

Integer

1

The sequence number of the multimedia material. This parameter is displayed on the frontend but not used in the operation logic. The value must be a positive integer.

ChannelId

String

RV01

The ID of the channel that you want to bind to the video resource.

ImageMaterialId

String

lkajsdfsa8fd89asd8****

The ID of the image in ApsaraVideo VOD.

FillMode

String

none

The fill type. Set this parameter to none.

PositionRefer

String

topLeft

The coordinate origin of the material. Set this parameter to topLeft to specify the upper-left corner of the material as the coordinate origin.

WidthNormalized

Float

0.4

The normalized value of the material width. The value specifies the ratio of the material width to the width of the background image. Valid values: [0,1].

HeightNormalized

Float

0.4

The normalized value of the material height. The value specifies the ratio of the material height to the height of the background image. Valid values: [0,1].

PositionNormalized

Float

[0.1, 0.2]

The normalized value [x,y] of the coordinates of the material. The values of x and y must be within the valid range [0,1].

For example, [0.1,0.2] indicates that the material is horizontally offset by 10% and vertically offset by 20% towards the upper-left corner.

LayerOrderConfig

Parameter

Type

Example

Description

Type

String

media

The type of the resource.

background: the background material

media: the multimedia material

Id

String

k12kj31****

The unique ID of the resource.

Response parameters

Parameter Type Example Description
LayoutId String 445409ec-7eaa-461d-8f29-4bec2eb9****

The ID of the layout. This parameter is used in the request of the following operations: DeleteStudioLayout, ModifyStudioLayout, and DescribeStudioLayouts.

RequestId String 5c6a2a0d-f228-4a64-af62-20e91b9676b3

The ID of the request.

Examples

Sample requests

http(s)://live.aliyuncs.com/?Action=AddStudioLayout
&CasterId=a2b8e671-2fe5-4642-a2ec-bf93880e****
&LayoutName=Test layout
&LayoutType=studio
&<Common request parameters>

Sample success responses

XML format 

<AddStudioLayoutResponse>
      <RequestId>5c6a2a0d-f228-4a64-af62-20e91b9676b3</RequestId>
      <LayoutId>445409ec-7eaa-461d-8f29-4bec2eb9****</LayoutId>
</AddStudioLayoutResponse>

JSON format 

{
    "AddStudioLayoutResponse": {
        "RequestId": "5c6a2a0d-f228-4a64-af62-20e91b9676b3",
        "LayoutId": "445409ec-7eaa-461d-8f29-4bec2eb9****"
    }
}

Error codes

For a list of error codes, visit the API Error Center.