批量截图 BatchScreenShot--云手机-火山引擎

文档中心

立即注册

导航

批量截图 BatchScreenShot

最近更新时间：2025.07.30 16:28:25首次发布时间：2024.05.08 16:20:07

向多个正在运行中的指定云手机实例发送截图指令，请求抓取并返回该批实例当前显示画面的图像数据。

使用说明

调用本接口发送批量截图请求后，会生成异步执行的截图任务。您可以参考云手机回调服务接入指南，通过配置“截图结果回调”，获取截图结果。

注意事项

本接口的单用户 QPS 限制为 50 次/秒。超过限制，API 调用会被限流。

请求说明

请求方式：POST
请求地址：https://open.volcengineapi.com?Action=BatchScreenShot&Version=2023-10-30

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`BatchScreenShot`	接口名称。当前 API 的名称为 `BatchScreenShot`。
Version	String	是	`2023-10-30`	接口版本。当前 API 的版本为 `2023-10-30`。

Body

参数	类型	是否必选	示例值	描述
ProductId	String	是	`1608456935646******`	实例所属业务 ID，可登录云手机控制台，在已创建的业务卡片中获取。
PodIdList	Array of String	是	`["7299381659819****","7299405883363****"]`	实例 ID 列表，用于指定需要截图的多个云手机实例。批量操作的最大实例数量为 100。
IsSavedOnPod	Boolean	否	`true`	是否在云手机实例中保留截图文件。调用接口成功截图后，截图文件将自动上传至火山引擎对象存储（TOS）。通过设置此参数，您可以选择是否在云手机实例中保留该截图文件。 `true`：是，截图文件将同时保存在云手机实例和 TOS 中。当截图数量超过 1000 张时，系统会按时间顺序自动清理云手机实例中较早的截图文件。若云手机存储空间小于 600MB，将无法完成截图操作。 `false`：（默认值）否，截图文件仅保存在 TOS 中。云手机实例中的对应文件将在截图文件成功上传至 TOS 后被自动删除。
Rotation	Integer	否	`0`	截图画面横竖屏旋转： 0：默认值，截图方向不做处理； 1：截图画面旋转为竖屏：手机竖屏的截图，不做处理；手机横屏的截图，截图顺时针旋转 90 度。
IsBroadcasted	Boolean	否	`true`	截图事件是否广播： true：（默认值）广播； false：不广播。
Interval	Integer	否	`0`	设置截图地址回调触发的频次： 0/1/置空：（默认值）表示每次调用本接口发起截图，都会刷新 URL，触发新的截图地址回调； -1：URL 固定不刷新，直到 7 天刷新一次 URL（由于 TOS 的 URL 链接有效期为 7 天）；其他数值：截图累计 xx 次后，再刷新 URL，刷新 URL 再触发回调。URL 不变，则不触发新的回调。
Quality	Integer	否	`10`	截图图片质量，即截图画质相对于原画质的压缩比例。可选范围：[1-100]，默认为 100，即原画质。注意本参数需配合 2025 年 2 月 13 日及以后发布的公共镜像使用。
Width	Integer	否	`700`	自定义截图图片宽度，单位为 px，取值范围为 [200-2560]。本参数与 `Height` 参数互为依赖，如需自定义截图尺寸，则两个参数均必填。注意本参数需配合 2025 年 3 月 13 日及以后发布的公共镜像使用。
Height	Integer	否	`1400`	自定义截图图片高度，单位为 px，取值范围为 [200-2560]。本参数与 `Width` 参数互为依赖，如需自定义截图尺寸，则两个参数均必填。注意本参数需配合 2025 年 3 月 13 日及以后发布的公共镜像使用。
ResizeMode	Integer	否	`1`	截图图片的缩放模式。当传入 `Width` 和 `Height` 自定义截图尺寸时，可同时使用本参数控制截图的缩放模式。取值及含义参看缩放模式说明。注意本参数需配合 2025 年 3 月 13 日及以后发布的公共镜像使用。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构。

参数	类型	示例值	描述
SucceedList	Array of String	`[ "7299381659819******"]`	截图成功的实例列表。此列表仅表示截图命令已成功发送至相应云手机实例，并不直接反映截图操作的最终结果。截图的实际完成情况及结果请通过回调获取。
FailedList	Array of String	`["7299405883363******"]`	截图失败的实例列表。具体失败原因请通过回调获取。

请求示例

POST https://open.volcengineapi.com?Action=BatchScreenShot&Version=2023-10-30
{
    "PodIdList": [
        "7299381659819******",
        "7299405883363******"
    ],
    "ProductId": "1608456935646******",
    "IsSavedOnPod": true,
    "Rotation": 0,
    "IsBroadcasted": true,
    "Interval": 0,
    "Quality": 10
}

返回示例

{
    "ResponseMetadata": {
        "Action": "BatchScreenShot",
        "Region": "cn-north-1",
        "Service": "ACEP",
        "Version": "2023-10-30",
        "RequestId": "20230604110420****100232280022D31"
    },
    "Result": {
        "SucceedList": [
            "7299381659819******"
        ],
        "FailedList": [
            "7299405883363******"
        ]
    }
}

错误码

您可访问公共错误码，获取更多错误码信息。

ResizeMode 缩放模式说明

ResizeMode	0（默认值）	1	2	3	4
是否等比例缩放	是	是	是	是	否
缩放方式	缩放图为自定义宽高形成的矩形框内，面积最大的图片。	缩放图为覆盖自定义宽高形成的矩形框，且面积最小的图片。	缩放图为覆盖自定义宽高形成的矩形框，且面积最小的图片。溢出部分将被裁剪。	缩放图为自定义宽高形成的矩形框内，面积最大的图片。未被图片填满部分将以颜色填充。	按照自定义宽高缩放，图片有可能会变形。
图示