空间感知算子支持对图片和视频进行对象检测、实例分割、跨帧跟踪、手部关键点识别与具身机械臂自动分割。可通过自然语言、像素点或像素框指定目标，也可无需 Prompt 自动识别视频中的机械臂；Hand Pose 支持输入相机内参，并返回手部 21 点二维、腕部相对三维及相机坐标系三维关键点。结果还包括映射到源媒体坐标的 bbox、RLE mask 与视频轨迹标识，适用于具身操作、工业巡检、数据标注和视觉内容分析。 # **算子介绍** > 算子 ID：las_spatial_perception # 适用场景 |**场景类型** |**典型目标** |**可用能力** | |---|---|---| |具身操作 |机械臂、夹爪、工具、被操作物体 |机械臂自动分割、文本定位、点框分割、视频跟踪、手部姿态估计 | |工业巡检 |安全帽、零部件、缺失或异常对象 |目标检测、实例分割、逐帧结构化结果 | |数据标注 |为指定对象生成 bbox、mask 和轨迹 ID |交互式分割、跨帧传播、RLE mask | |内容分析 |在图片或视频中定位并持续跟踪目标 |多 Prompt 检测、分割与轨迹关联 | |头戴双目视频 |佩戴者手部 |手部姿态估计与佩戴者手部筛选 | # 支持的任务 |核心能力 |能力说明 |适用的任务类型 | |---|---|---| |**文本目标检测** |根据对象名称、类别或外观描述，在图片或视频采样帧中返回目标 bbox；视频结果带有跨帧轨迹标识。 |使用 text prompt 检测图片或视频中的目标。 | |**文本定位后分割** |通过 `grounded_segmentation@v1` 先根据文字描述找到目标，再沿目标轮廓将其从背景中精确圈出，并在后续视频帧中持续跟踪。 |使用 text prompt 直接对目标进行分割。 | |**交互式实例分割** |使用正负点或像素框约束目标，返回源分辨率网格上的实例 mask。 |使用按 target 分组的 point/box Prompt 分割目标。 | |**视频目标跟踪** |在采样帧之间保持对象实例和轨迹身份，逐帧返回 bbox、mask 与时间信息。 |* 先使用文本定位候选对象，再执行分割和视频传播。

* 目标分割支持在视频场景进行跨帧跟踪。 | |**手部姿态估计** |通过 `hand_pose_estimation` 识别图片或视频中的手部姿态。 |使用 `hand_pose_estimation` 处理图片或视频中的手部姿态。 | |**佩戴者手部筛选** |Hand Pose 视频任务可结合头戴双目设备数据筛选佩戴者手部。 |Hand Pose 视频任务可按需启用佩戴者手部筛选。 | |**机械臂识别与分割** |* 通过预置任务模版`robot_arm_segmentation`自动识别视频中的机械臂及夹爪等可见部件，按机械臂实例合并后返回源画面坐标的 bbox 和 RLE mask。

* 无需 Prompt，可按需声明相机视角。部件归属和自动视角判断依赖模型，不保证所有画面均判断正确。 |适合用于机器人操作数据清洗、机械臂区域标注与跨帧跟踪，也可作为夹爪状态分析、交互关系理解等下游任务的前置输入 | ## 效果展示 ---

【通用目标检测与分割】

* 示例场景： * 分割并追踪视频中的机械夹爪 * 输入视频

* 任务代码\-核心参数示例 ```Bash data: { action: "segment", media: { uri: $input_uri, type: "video", fps: $fps }, prompts: [ { type: "box", target: "robot_gripper", box: [210, 420, 685, 1300] } ] } ```

——以第0帧机械夹爪所在位置框坐标作为目标位置指定

* 输出结果 [manifest.json](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/aed6cbbc6c25414bb02d98acbb0d7f94~tplv-goo7wpa0wc-image.image) * 基于输出结果的视频标注展示

——注意，本算子不直接返回视频结果，以上为基于算子处理结果 manifest 的 bbox 和 COCO RLE mask，在原视频上叠加标注后的示例。

---

【手部姿态估计 \- 示例1：未开启佩戴者手部筛选（ownership）】

* 输入示例 * 左目视频

* 任务代码\-核心参数示例 ```Bash "data": { "task_template": "hand_pose_estimation@v1", "media": { "uri": "https://tos_test/left.mp4", "type": "video", "fps": 10, "max_frames": 3600 } } ``` * 输出结果示例 [manifest(1).json](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/712206c650c64f5a99db187d8ba36454~tplv-goo7wpa0wc-image.image) * 基于输出结果视频标注展示

——注意，本算子不直接返回视频结果，以上为基于算子处理结果 manifest 在原视频上进行标注后的示例。

【手部姿态估计 \- 示例2：开启佩戴者手部筛选（ownership）】

* 输入示例 * 左目视频、时间戳、鱼眼相机参数

[left_timestamps.txt](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/12727de9390b4efaae79d4fc3fbda1d1~tplv-goo7wpa0wc-image.image) [left_intrinsic.json](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/be5837493e9e439780a426544df3fd2c~tplv-goo7wpa0wc-image.image) * 右目视频、时间戳、鱼眼相机参数

[right_timestamps.txt](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/9a204b36f86d4f35ad3d595b55a08f51~tplv-goo7wpa0wc-image.image) [right_intrinsic.json](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/f8fd98d5668d451cb18070fe3d38b8e9~tplv-goo7wpa0wc-image.image) * 左相机坐标系到右相机坐标系的刚体变换 [left_T_right.json](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/86c291416f274f199d553421a7c12b2d~tplv-goo7wpa0wc-image.image) * 任务代码\-核心参数示例 ```Bash "data": { "task_template": "hand_pose_estimation@v1", "media": { "uri": "https://tos_test/left.mp4", "type": "video", "fps": 10, "max_frames": 3600 }, "task_context": { "ownership": { "enabled": true, "stereo": { "right_media_uri": "https://tos_test/right.mp4", "left_timestamps": { "uri": "https://tos_test/left_timestamps.txt" }, "right_timestamps": { "uri": "https://tos_test/right_timestamps.txt" }, "left_intrinsic": { "uri": "https://tos_test/left_intrinsic.json" }, "right_intrinsic": { "uri": "https://tos_test/right_intrinsic.json" }, "extrinsic": { "uri": "https://tos_test/left_T_right.json" } } } } } ``` * 输出结果示例 [manifest.json](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/51351bb10ebd4a73916ee46292b09588~tplv-goo7wpa0wc-image.image) * 基于输出结果视频标注展示

——注意，本算子不直接返回视频结果，以上为基于算子处理结果 manifest 在原左视频上进行标注后的示例。

--- ## 支持的地域 * 北京：cn\-beijing * 上海：cn\-shanghai * 广州：cn\-guangzhou ## 算子性能 |细分项 |性能影响说明 | |---|---| |最大 RPM |600 | |最大并发数 |10 | # 输入与输出要求 ## 输入要求 |细分 |详细要求 | |---|---| |支持的输入数据模态 |* 视频

* 图片

* 文本 | |输入格式：视频/图片 |* 格式：

* 图片：bmp、gif、jpeg、jpg、png、tif、tiff、webp

* 视频：avi、m4v、mkv、mov、mp4、mpeg、mpg、webm

* 大小、时长等：

* 图片大小 ≤100 MiB；视频大小 ≤5 GiB。

* 源媒体最长边 ≤4096，总像素数 ≤4096×2160。

* 视频采样 fps 范围为 [0.1, 30]，且不得高于源视频 fps；grounded_segmentation@v1 默认 5，hand_pose_estimation@v1 默认 10；启用佩戴者手部筛选时不得低于 10。

* Hand Pose 任务：

* 每个请求最多处理 18000 个视频采样帧；超限时需降低 fps 或预先切分视频。

* 不支持输入 Prompt。

* 机械臂 Grounding 任务

* 仅支持视频输入，视频时长不超过 1800 秒。

* 其他任务：

* 每个请求最多处理 360 个视频采样帧；超限时需降低 fps 或预先切分视频。

* 每个请求支持 1～5 个 Prompt；text 与 point/box 不能混用。 | |输入路径要求 |通过请求参数 `uri` 提供给算子输入数据，当前支持公网 URL、TOS 路径这两种方式。

* 公网 URL：公网可访问的 URL，格式为 `http/https`。

* 公网 URL 不支持需要登录态或额外 Header 鉴权的地址；临时 URL 需在任务执行期间有效。

* TOS 路径：将待处理数据上传至与当前 LAS 服务同主账号、同地域的 TOS Bucket后，可提供 TOS 路径，格式为`tos://bucket_name/demo`。

* TOS 对象需存在且具备读取权限。 | ## 输出要求 |细分 |详细要求 | |---|---| |输出数据模态 |* 文本

* 分割输出固定为 COCO compressed RLE，结果恢复到源媒体分辨率网格。 | |输出路径：TOS |通过请求参数`output.destination` 指定算子输出结果的存储路径，当前支持设置为 TOS 路径。

* TOS 路径：与LAS服务同主账号、同地域下，有可写权限的 TOS Bucket 目录，格式：`tos://bucket/output/`。 | # 计费说明 ## 手部姿态预估任务 * 计费标准 |细分项 |计费标准说明 | |---|---| |计费项 |按有效目标实际处理的采样帧数计费。您可以通过 poll接口返回的 `prompt_frame_count` 参数查看当前任务的有效目标实际处理的采样帧数 | |计费类型 |按量计费，按实际的计费用量每小时出账。 | |单价 |手部姿态预估任务的计费受单价和 FPS 系数影响，`费用 = 单价 * FPS 系数 * 用量`，详情见下文。 | * 计费单价 |单价 |FPS 系数 | |---|---| |1.6 元/千帧 |与请求参数 `media.fps` 的设置结果有关：

* [1 , 5] ：系数为 5

* (6 , 10]：系数为 7

* (11 , 30] ：系数为 10 | * 计费示例提交了一个手部姿态估计任务，请求参数的 `media.fps` 设置为 15，poll 接口返回的 `prompt_frame_count` 取值为 600，则，FPS 系数为 10，`目标检测与分割费用 = 1.6元/千帧 * 10 * 600帧/1000 = 9.6 元`。

说明

如果您希望在调用算子前预估任务处理的用量（prompt_frame_count）值，可通过以下方式进行预估。

prompt_frame_count ≈ 视频时长（秒） * FPS 系数

注意，以上仅为预估取值，实际用量需以 poll 接口和最终账单为准。

## 机械臂检测与分割任务 * 计费标准 |细分项 |通用目标检测与分割任务 | |---|---| |计费项 |当前包含以下两个计费项：

* **目标检测与分割费用**：按有效目标实际处理的采样帧数计费。

* 每条文本 Prompt 算一个目标；同一 target 的 point/box Prompt 合并为一个目标。

* 您可以通过 poll接口返回的 `prompt_frame_count` 参数查看当前任务的有效目标实际处理的采样帧数。

* **模型调用费用**：当前仅机械臂检测与分割任务场景（`task_template=robot_arm_segmentation`）涉及模型调用费用，其他任务场景不涉及。 | |计费类型 |按量计费，按实际的计费用量每小时出账。 | |单价与计费公式 |不同计费项单价不一致详情见下表，计费公式为：`费用 = 目标检测与分割费用 + 模型调用费用`。 | * 计费单价 * **目标检测与分割费用**：`1.6 元/千帧` * **模型调用费用**：

说明

当前仅机械臂检测与分割任务场景（task_template=robot_arm_segmentation）涉及。

|模型名称 |输入 |缓存命中 |输出 | |---|---|---|---| |Seed 2.1 Turbo |6 元/百万 tokens |1.2 元/百万 tokens |30 元/百万 tokens | ## 通用目标检测与分割任务 * 计费标准 |细分项 |计费标准说明 | |---|---| |计费项 |按有效目标实际处理的采样帧数计费。

```Plain Text```
```* 每条文本 Prompt 算一个目标；同一 target 的 point/box Prompt 合并为一个目标。```
```* 您可以通过 poll接口返回的 `prompt_frame_count `参数查看当前任务的有效目标实际处理的采样帧数。```
| |计费类型 |按量计费，按实际的计费用量每小时出账。 | |单价 |单价为 `1.6 元/千帧`，`费用 = 单价 * 用量`。 | # 注意与前提 |细分项 |注意与前提 | |---|---| |开通 LAS |* 如果您是一个全新的火山引擎用户，此前未开通过 LAS 产品，您可先开通 LAS，不使用 LAS 的计费功能仅开通 LAS 产品不会产生费用。开通操作请参见[准备工作](https://docs.volcengine.com/docs/6492/1264537)。

* 开通完成后可查看算子介绍文档，了解算子能力、上手引导等，详情可参见：[LAS 智能数据处理算子](https://docs.volcengine.com/docs/6492/1798368)。 | |费用 |调用算子前，您需先了解使用算子时的模型调用费用，详情请参见[大模型调用计费](https://www.volcengine.com/docs/6492/1544808)。 | |鉴权（API Key） |调用算子前，您需要先生成算子调用的API Key，并建议将API Key配置为环境变量，便于更安全地调用算子，详情请参见[获取 API Key 并配置](https://docs.volcengine.com/docs/6492/2191994)。 | |BaseURL |调用算子前，您需要先根据您当前使用的LAS服务所在地域，了解算子调用的BaseURL，用于配置算子调用路径参数取值。

详情请参见[获取 Base URL](https://docs.volcengine.com/docs/6492/2191993)，下文中的调用示例仅作为参考，实际调用时需替换为您对应地域的路径取值。 | # **Rest API 调用** ## API 调用说明 * 本算子的 API 为异步任务接口，您需要通过 `Submit` 接口提交任务获得任务的 `task_id`，再通过 `Poll` 接口获取对应任务（`task_id`）运行状态，并获取算子处理结果。 * 注意，任务提交后，任务的 `task_id` 有效期为 3 天，超过 3 天后即无法通过此 `task_id` 来获取算子处理结果。 ## submit ### 接口说明调用空间感知算子提交异步任务。支持对图片和视频中的目标进行检测、实例分割与跨帧跟踪，可使用自然语言、像素点或像素框指定目标；同时支持通过 `hand_pose_estimation` 进行手部姿态估计，以及通过 `robot_arm_segmentation` 自动分割视频中的机械臂。图片结果通过 Poll 响应内联返回，视频结果通过结果 manifest 返回。 ### 请求参数 **operator_id** string 必选 `示例值: las_spatial_perception` 算子 ID，固定为 `las_spatial_perception`。 **operator_version** string 必选 `示例值: v1` 算子版本，固定为 `v1`。 **data** SpatialPerceptionInfo 必选空间感知任务参数。 **action** string `示例值: segment` 任务动作。`detect` 表示目标检测：根据文本 Prompt 找出目标位置并返回 bbox，视频结果包含跨帧轨迹；`segment` 表示目标分割：根据文本、点或框 Prompt 精确圈出目标区域并返回 bbox 和 mask，视频输入还会把同一目标的分割结果传播到后续采样帧。与 `task_template` 至少传一个；两者同时传入时必须语义一致。`hand_pose_estimation` 仅支持 `detect`，省略时自动按 `detect` 处理；`robot_arm_segmentation` 仅支持 `segment`，省略时自动按 `segment` 处理。 **task_template** string `示例值: grounded_segmentation` 任务模板。支持 `grounded_segmentation`、`hand_pose_estimation` 和 `robot_arm_segmentation`。与 `action` 至少传一个。 **ark_api_key** string 仅 `robot_arm_segmentation` 支持。填写时由对应 Ark 账号承担模型费用，LAS 不收取模型 Token 费用；不填写时由 LAS 调用模型，并按算子定价收取 Token 费用。两种方式均收取 LAS 帧费。 **media** SpatialMedia 必选输入图片或视频。 **uri** string 必选 `示例值: tos://example-bucket/input.mp4` 输入媒体地址。支持 `http://`、`https://`、`tos://`。HTTP(S) 地址必须可直接下载；TOS 对象由服务使用调用方权限读取。 **type** string `示例值: video` `image` 或 `video`。可根据 URI 后缀识别时可省略；无后缀或后缀不可识别时必须显式传入。支持的图片后缀：bmp、gif、jpeg、jpg、png、tif、tiff、webp；支持的视频后缀：avi、m4v、mkv、mov、mp4、mpeg、mpg、webm。 **fps** float `示例值: 5` 仅视频支持。采样频率范围为 `[0.1, 30]`，且不得高于源视频 fps。普通任务默认 5；`hand_pose_estimation` 默认 10，启用佩戴者手部筛选时不得低于 10；`robot_arm_segmentation` 默认 2、参数上限为 30，但还需满足最多采样 18000 帧和视频时长不超过 1800 秒的限制。 **max_frames** integer `示例值: 1200` 仅视频支持，用于限制最多处理的采样帧数。普通检测或分割任务范围为 `[1, 360]`；`hand_pose_estimation` 和 `robot_arm_segmentation` 的范围均为 `[1, 18000]`。Hand Pose 的源视频时长不得超过 600 秒（10 分钟）；机械臂 Grounding 的源视频时长不得超过 1800 秒（30 分钟）。对应的帧数和时长限制需同时满足。 **prompts** array of SpatialPrompt 普通检测或分割任务必选，长度为 1～5，支持文本、点和框三种形式。`hand_pose_estimation` 和 `robot_arm_segmentation` 不接受该字段。 **type** string 必选 `示例值: text` Prompt 类型，支持 `text`、`point`、`box`。同一请求不能混用 text 与 point/box；`action=detect` 仅支持 text，`action=segment` 支持 text 或按 target 分组的 point/box；`grounded_segmentation` 仅支持 text。point/box 输入坐标以及返回的 bbox 和 mask 均基于源媒体坐标。 **text** string `示例值: robot gripper` 文本 Prompt 的目标名称、类别或可见外观描述。请尽量输入简洁的英文描述。完整 Prompt 示例：`{"type":"text","text":"robot gripper"}`。 **target** string `示例值: gripper_01` 调用方自定义的对象分组标识，长度 1～64，仅允许 ASCII 字母、数字、下划线和连字符。同一 target 的多个交互 Prompt 共同约束同一对象。 **point** array of float `示例值: [960,720]` 源媒体像素坐标 `[x,y]`。坐标必须为非负有限数。完整 Prompt 示例：`{"type":"point","target":"gripper_01","point":[960,720],"positive":true}`。 **positive** boolean `示例值: true` 仅对 point Prompt 生效，默认 `true`。`true` 表示“这个点在目标上”，用于帮助模型选中目标；`false` 表示“这个点不在目标上”，用于排除误选区域。未提供 box 时，同一 target 的 point 中至少有一个需要设置为 `positive=true`；已提供 box 时，其他 point 可以全部设置为 `positive=false`。 **box** array of float `示例值: [700,400,1180,920]` 源媒体像素坐标 `[x0,y0,x1,y1]`，必须满足 `x1>x0`、`y1>y0`。同一 target 最多一个 box。完整 Prompt 示例：`{"type":"box","target":"gripper_01","box":[700,400,1180,920]}`。 **task_context** SpatialTaskContext 模板专用上下文。`hand_pose_estimation` 可通过 `camera` 提供相机内参，也可通过 `ownership` 启用佩戴者手部筛选；`robot_arm_segmentation` 可通过 `camera_view` 声明相机视角。不同模板的上下文字段不能混用。 **ownership** HandPoseOwnership 仅 `hand_pose_estimation` 支持。配置头戴双目设备佩戴者手部筛选。 **enabled** boolean `示例值: true` 是否启用佩戴者手部筛选，默认 `false`。设为 `false` 时不得传 `stereo`。 **stereo** HandPoseStereoInput `enabled=true` 时必选。仅视频支持，并要求 `media.fps >= 10`。 **right_media_uri** string 必选 `示例值: tos://example-bucket/right.mp4` 与 media.uri 左目视频配对的右目视频地址，支持 HTTP(S) 和 TOS。 **left_timestamps** OwnershipDocument 必选 `示例值: {"uri":"tos://example-bucket/left.txt"}` 左目时间戳。文本每行对应原视频一帧，填写严格递增的纳秒整数。 **uri** string `示例值: tos://example-bucket/calibration.json` 远程文档地址，支持 `http://`、`https://`、`tos://`。与 `content` 必须且只能提供一个。 **content** string `示例值: "1000000000\n1033333333\n"` UTF\-8 内联文档内容。与 `uri` 必须且只能提供一个。 **right_timestamps** OwnershipDocument 必选 `示例值: {"uri":"tos://example-bucket/right.txt"}` 右目时间戳，格式与左目相同，并使用相同时间基准。 **left_intrinsic** OwnershipDocument 必选 `示例值: {"uri":"tos://example-bucket/left.json"}` 左目鱼眼相机内参，JSON 字段包括 `Fx/Fy/Cx/Cy`、`k1`～`k4`、`width/height`。 **right_intrinsic** OwnershipDocument 必选 `示例值: {"uri":"tos://example-bucket/right.json"}` 右目鱼眼相机内参，格式与左目相同。 **uri** string `示例值: tos://example-bucket/calibration.json` 远程文档地址，支持 `http://`、`https://`、`tos://`。与 `content` 必须且只能提供一个。 **content** string `示例值: "1000000000\n1033333333\n"` UTF\-8 内联文档内容。与 `uri` 必须且只能提供一个。 **extrinsic** OwnershipDocument 必选 `示例值: {"uri":"tos://example-bucket/extrinsic.json"}` 从左目到右目的外参，JSON 包含四元数 `rotation{x,y,z,w}` 和米制 `translation{x,y,z}`。 **camera** HandPoseCameraInput `示例值: {"model":"pinhole","intrinsics":[636.66,636.25,635.29,366.87]}` 仅 `hand_pose_estimation` 支持，为输入图片或视频提供相机内参。不传时默认使用模型的虚拟相机。 **model** string `示例值: pinhole` 相机模型，默认且当前仅支持 `pinhole`。不支持畸变参数。 **intrinsics** array of float 必选 `示例值: [636.66,636.25,635.29,366.87]` 针孔相机内参 `[fx,fy,cx,cy]`，单位为像素，必须是 4 个有限数值，且 `fx`、`fy` 大于 0。一条请求中的所有帧共用该内参；暂不支持逐帧内参。内参必须与输入媒体的实际画面一致，媒体经过缩放、裁剪或旋转时需同步调整。没有可靠内参时应省略整个 `camera`，不要填写估算值。 **camera_view** string `示例值: wrist` 仅 `robot_arm_segmentation` 支持，默认 `auto`。可选值：`auto`（由模型判断）、`wrist`（腕部相机）、`head_body`（头部或身体相机）、`external`（外部相机）。显式填写时作为已知相机安装信息使用；模型结果与该值冲突时，本次结果校验失败。`auto` 依赖模型判断，不保证所有画面都能正确识别视角。 **output** SpatialOutput `示例值: {"destination":"tos://bucket/results"}` 视频结果 manifest 的可选发布目录。 **destination** string `示例值: tos://customer-bucket/spatial-results` 视频 manifest 的发布前缀，仅支持 `tos://`。 ### 返回数据 **metadata** metadata 请求元信息。 **task_id** string `示例值: task-xxx` 异步任务 ID，用于 Poll 查询。 **task_status** string `示例值: PENDING` 异步任务状态：PENDING、RUNNING、COMPLETED、FAILED、TIMEOUT。 **business_code** string `示例值: 0` 业务码，提交成功时通常为 `0`。 **error_msg** string 异常信息。 ### 示例 #### 请求示例目标识别示例： ```Bash # Grounded Segmentation curl --location "https://operator.las.cn-beijing.volces.com/api/v1/submit" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $LAS_API_KEY" \ --data '{ "operator_id": "las_spatial_perception", "operator_version": "v1", "data": { "task_template": "grounded_segmentation", "media": { "uri": "https://example.com/input.mp4", "type": "video", "fps": 5, "max_frames": 360 }, "prompts": [ {"type": "text", "text": "robot gripper"}, {"type": "text", "text": "cucumber"} ] } }' ``` 机械臂检测与分割示例 ```Bash # Embodied Robot Arm Grounding curl --location "https://operator.las.cn-beijing.volces.com/api/v1/submit" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $LAS_API_KEY" \ --data '{ "operator_id": "las_spatial_perception", "operator_version": "v1", "data": { "task_template": "robot_arm_segmentation", "media": { "uri": "https://example.com/robot-arm.mp4", "type": "video", "fps": 2, "max_frames": 3600 }, "task_context": { "camera_view": "wrist" } } }' ``` 手部姿态估计示例： ```Bash # Hand Pose curl --location "https://operator.las.cn-beijing.volces.com/api/v1/submit" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $LAS_API_KEY" \ --data '{ "operator_id": "las_spatial_perception", "operator_version": "v1", "data": { "task_template": "hand_pose_estimation", "media": { "uri": "tos://example-bucket/left.mp4", "type": "video", "fps": 10, "max_frames": 1200 }, "task_context": { "camera": { "model": "pinhole", "intrinsics": [636.66, 636.25, 635.29, 366.87] }, "ownership": { "enabled": true, "stereo": { "right_media_uri": "tos://example-bucket/right.mp4", "left_timestamps": {"uri": "tos://example-bucket/left.txt"}, "right_timestamps": {"uri": "tos://example-bucket/right.txt"}, "left_intrinsic": {"uri": "tos://example-bucket/left.json"}, "right_intrinsic": {"uri": "tos://example-bucket/right.json"}, "extrinsic": {"uri": "tos://example-bucket/extrinsic.json"} } } } } }' ``` #### 返回示例 ```JSON { "metadata": { "task_id": "task-20260818163544-abc123", "task_status": "PENDING", "business_code": "0", "error_msg": "" } } ``` ### 错误码 |HttpStatusCode |错误码 |错误信息 |描述 | |---|---|---|---| |400 |Parameter.Invalid |The parameter is invalid. |字段、Prompt、坐标、fps、帧数、媒体尺寸或资源预算不合法。 | |400 |Video.DownloadFailed |Failed to download input media. |输入媒体无法下载、无读取权限或签名失效。 | |400 |Video.Timeout |Spatial perception processing timed out. |空间感知处理超时。 | |400 |Video.ModelFailed |Spatial perception model inference failed. |模型推理或结果校验失败。 | |400 |Video.UploadFailed |Failed to publish spatial perception result. |视频 manifest 发布失败。 | |401 |Authorization.Missing |Missing Authorization. |缺少鉴权信息。 | |401 |ApiKey.InValid |The api key is invalid. |API Key 不合法。 | |500 |InternalError |Internal error. |服务内部异常。 | ## Poll ### 接口说明查询空间感知任务的执行状态和结果。图片任务完成后通过 `data.frames` 内联返回逐帧结果；视频任务通过 `data.result_manifest_url` 返回 manifest 地址，Poll 响应不直接内联视频逐帧结果。只有任务成功完成时才返回 `data`；PENDING、RUNNING、FAILED、TIMEOUT 和任务不存在等状态不返回 `data`。 ### 请求参数 |名称 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |operator_id |string |是 |las_spatial_perception |算子 ID，固定为 `las_spatial_perception`。 | |operator_version |string |是 |v1 |算子版本，固定为 `v1`。 | |task_id |string |是 |task\-xxx |Submit 返回的任务 ID。 | ### 返回数据 **metadata** metadata 请求元信息。 **task_id** string `示例值: task-xxx` 异步任务 ID。 **task_status** string `示例值: COMPLETED` 异步任务状态：PENDING、RUNNING、COMPLETED、FAILED、TIMEOUT。应结合 `task_status=COMPLETED` 与 `business_code=0` 判断任务成功完成。 **submit_time** string `示例值: 2026-08-18T16:04:06+08:00` 任务提交时间，ISO 8601 时间戳。 **end_time** string `示例值: 2026-08-18T16:04:10+08:00` 任务结束时间，ISO 8601 时间戳。 **business_code** string `示例值: 0` 业务码，处理成功时通常为 `0`。 **error_msg** string 异常信息。 **data** SpatialPerceptionResult 任务成功完成时返回的空间感知结果。 **clazz** string `示例值: las_spatial_perception` 结果类型标识（如有）。 **frame_count** integer `示例值: 60` 模型实际完成处理的采样帧数。已处理但未识别到对象的帧仍计入；未实际传播的帧不计入。视频结果中该值等于 manifest 的 `frame_count` 和 `frames` 数组长度。 **prompt_frame_count** integer `示例值: 120` 计费数量，表示各有效 Prompt 目标实际处理的采样帧数之和。文本 Prompt 按每条统计；同一 target 的 point/box 合并为一个有效目标。`hand_pose_estimation` 按请求 `fps` 选择 5、7 或 10 fps 档位，按 `ceil(frame_count × 档位 fps ÷ 请求 fps)` 折算，因此可高于或低于 `frame_count`：`fps ≤ 5` 使用 5 fps 档，`5 < fps ≤ 10` 使用 7 fps 档，`10 < fps ≤ 30` 使用 10 fps 档。`robot_arm_segmentation` 返回实际处理的有效 prompt\-frame 累计值，没有选中机械臂时可为 `0`，帧费按该值计收。 **video_duration** float `示例值: 12.0` 仅视频返回，源视频时长，单位为秒。 **resolution** string `示例值: 1920x1080` 源媒体分辨率，格式为 `宽x高`。 **frames** array of SpatialFrame 仅图片返回。图片的检测、分割或手部姿态结果直接包含在接口返回内容中，无需另外下载结果文件。 **result_manifest_url** string `示例值: https://example.com/manifest.json` 仅视频返回。未指定 `output.destination` 时为有效期 259200 秒的 LAS 托管签名 HTTPS；指定时返回对应的 TOS URI。 **token_usage** object of SpatialTokenUsage `示例值: {"doubao-seed-2-1-turbo-260628":{"prompt_tokens":4458,"completion_tokens":249,"total_tokens":4707}}` 仅 `robot_arm_segmentation` 返回。按模型名汇总本次任务中所有 VLM 调用的 token 用量，包括首次调用以及格式校验失败后触发的补试。 **token_usage_complete** boolean `示例值: true` 仅 `robot_arm_segmentation` 返回。表示所有 VLM 调用是否都提供了 `prompt_tokens`、`completion_tokens` 和 `total_tokens`；不表示识别准确或任务处理成功。 ### 示例 #### 请求示例 ```Bash curl --location "https://operator.las.cn-beijing.volces.com/api/v1/poll" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $LAS_API_KEY" \ --data '{ "operator_id": "las_spatial_perception", "operator_version": "v1", "task_id": "task-20260818163544-abc123" }' ``` #### 返回示例 ```JSON { "metadata": { "task_id": "task-20260818163544-abc123", "task_status": "COMPLETED", "submit_time": "2026-08-18T16:04:06+08:00", "end_time": "2026-08-18T16:04:10+08:00", "business_code": "0", "error_msg": "" }, "data": { "frame_count": 60, "prompt_frame_count": 120, "video_duration": 12.0, "resolution": "640x480", "result_manifest_url": "https://example.com/manifest.json" } } ``` 视频 manifest 示例： ```JSON { "version": "1.0", "frame_count": 60, "video_duration": 12.0, "resolution": "640x480", "frames": [ { "source_frame_index": 0, "timestamp": 0.0, "objects": [ { "object_id": "obj_000_001", "prompt_index": 0, "bbox": [233, 178, 393, 409], "track_id": "track_000_001", "mask": { "format": "rle", "size": [480, 640], "counts": "WkX13..." }, "mask_area": 12477 } ] } ] } ``` 机械臂 Grounding 视频任务返回示例： ```JSON { "metadata": { "task_id": "task-20260916120000-robot-arm", "task_status": "COMPLETED", "business_code": "0" }, "data": { "frame_count": 6, "prompt_frame_count": 12, "video_duration": 3.0, "resolution": "640x480", "result_manifest_url": "https://example.com/robot-arm-manifest.json", "token_usage": { "doubao-seed-2-1-turbo-260628": { "prompt_tokens": 4458, "completion_tokens": 249, "total_tokens": 4707 } }, "token_usage_complete": true } } ``` 机械臂 Grounding manifest 中的对象示例： ```JSON { "object_id": "w0_p0", "label": "robot_arm", "bbox": [281, 31, 640, 208], "mask": { "format": "rle", "size": [480, 640], "counts": "WkX13..." }, "mask_area": 29720 } ``` Hand Pose 视频任务返回示例： ```JSON { "metadata": { "task_id": "task-20260818163544-handpose", "task_status": "COMPLETED", "business_code": "0" }, "data": { "clazz": "las_spatial_perception", "frame_count": 120, "prompt_frame_count": 84, "video_duration": 12.0, "resolution": "1920x1080", "result_manifest_url": "https://example.com/hand-pose-manifest.json" } } ``` ### 错误码 |HttpStatusCode |错误码 |错误信息 |描述 | |---|---|---|---| |400 |Task.NotFound |The task is not found. |任务不存在。 | |400 |Parameter.Invalid |The parameter is invalid. |参数或媒体不满足约束。 | |400 |Video.DownloadFailed |Failed to download input media. |输入媒体下载失败。 | |400 |Video.Timeout |Spatial perception processing timed out. |空间感知处理超时。 | |400 |Video.ModelFailed |Spatial perception model inference failed. |模型推理或结果校验失败。 | |400 |Video.UploadFailed |Failed to publish spatial perception result. |视频 manifest 发布失败。 | |401 |Authorization.Missing |Missing Authorization. |缺少鉴权信息。 | |401 |ApiKey.InValid |The api key is invalid. |API Key 不合法。 | |500 |InternalError |Internal error. |服务内部异常。 | # 参考 ## 输出 manifest.json 字段说明调用算子输出的 manifest.json 文件包含以下关键字段，示例与说明如下。 |字段 |示例值 |含义 | |---|---|---| |`version` |`1.0` |结果格式版本 | |`frame_count` |`142` |输出结果覆盖的帧数 | |`video_duration` |`5.9167` |视频时长，单位秒 | |`resolution` |`1920x1080` |原视频分辨率 | |`frames` |数组 |每一帧的 HandPose 结果 | 每个 `frames[]` 代表一帧： |字段 |含义 | |---|---| |`source_frame_index` |原视频帧序号，从 `0` 开始 | |`timestamp` |当前帧时间戳，单位秒 | |`objects` |当前帧检测到的对象列表 | 每个 `objects[]` 代表一个检测对象，以手部姿态估计场景为例，每个`objects[]`代表一只手： |字段 |含义 | |---|---| |`object_id` |手部对象 ID | |`track_id` |跨帧跟踪 ID，用于把不同帧中的同一只手关联起来 | |`label` |手部类别，如 `left_hand` / `right_hand` | |`handedness` |左右手判断结果，如 `left` / `right` | |`handedness_score` |左右手判断置信度 | |`score` |当前手部检测置信度 | |`bbox` |手部检测框，格式为 `[x_min, y_min, x_max, y_max]` | |`bbox_space` |检测框坐标系，本结果为 `source_pixel`，即原视频像素坐标 | |`observation` |观测状态，本结果为 `observed`，表示该帧实际检测到手 | |`pose` |手部姿态结果 | `pose` 里是核心手部关键点参数： |字段 |含义 | |---|---| |`skeleton` |骨架类型，本结果为 `hand_21` | |`joint_names` |21 个手部关节点名称 | |`edges` |关节点连线关系，可用于绘制手部骨架 | |`root_joint_index` |根节点索引，本结果为 `0`，对应手腕 `wrist` | |`keypoints_2d` |2D 手部关键点 | |`keypoints_3d` |3D 手部关键点 | 21 个关节点顺序固定如下： ```Plain 0 wrist 1 thumb_mcp 2 thumb_pip 3 thumb_dip 4 thumb_tip 5 index_mcp 6 index_pip 7 index_dip 8 index_tip 9 middle_mcp 10 middle_pip 11 middle_dip 12 middle_tip 13 ring_mcp 14 ring_pip 15 ring_dip 16 ring_tip 17 pinky_mcp 18 pinky_pip 19 pinky_dip 20 pinky_tip ``` `keypoints_2d`： |字段 |含义 | |---|---| |`space` |`source_pixel`，表示原视频像素坐标 | |`values` |21 个 `[x, y]` 坐标点，与 `joint_names` 一一对应 | |`in_frame` |21 个布尔值，表示对应关键点是否在画面内 | `keypoints_3d`： |字段 |含义 | |---|---| |`space` |`wrist_relative_camera_axes`，表示以手腕为原点、相机轴向为参考的相对 3D 坐标 | |`unit` |`meter` | |`metric_calibrated` |`false`，3D 关键点为相对三维坐标，适合表达手部姿态和相对运动，不建议作为绝对测距结果使用 | |`values` |21 个 `[x, y, z]` 三维点，与 `joint_names` 一一对应 | 下面是一个 manifest 实际统计结果： ```Plain 总帧数：142 每帧检测手部数量：4 总手部对象记录数：568 输出类型：left_hand / right_hand 骨架类型：hand_21 2D 坐标：原视频像素坐标 3D 坐标：手腕相对相机坐标 ``` 可以总结为：HandPose 会返回每一帧中每只手的检测框、左右手类别、检测置信度、跨帧跟踪 ID、21 点 2D 关键点、21 点相对 3D 关键点，以及用于绘制手部骨架的关节点连接关系。

AI 数据湖服务