空间感知算子支持对图片和视频进行对象检测、实例分割、跨帧跟踪、手部关键点识别、手部世界坐标估计、具身机械臂自动分割和交互物品检测与分割。可通过自然语言、像素点或像素框指定目标，也可通过专用任务模板自动识别机械臂或交互物品；Hand Pose 支持输入或估计相机内参，并返回手部 21 点二维、腕部相对三维、相机坐标系三维关键点，以及请求内局部世界坐标系中的相机位姿和手部轨迹。结果还包括映射到源媒体坐标的 bbox、RLE mask 与视频轨迹标识，适用于具身操作、工业巡检、数据标注和视觉内容分析。 # **算子介绍** > 算子 ID：las_spatial_perception ## 适用场景 |**场景类型** |**典型目标** |**可用能力** | |---|---|---| |具身操作 |机械臂、夹爪、工具、交互物品 |机械臂自动分割、交互物品检测与分割、文本定位、点框分割、视频跟踪、手部姿态估计 | |工业巡检 |安全帽、零部件、缺失或异常对象 |目标检测、实例分割、逐帧结构化结果 | |数据标注 |为指定对象生成 bbox、mask 和轨迹 ID |交互式分割、跨帧传播、RLE mask | |内容分析 |在图片或视频中定位并持续跟踪目标 |多 Prompt 检测、分割与轨迹关联 | |头戴双目视频 |佩戴者手部 |手部姿态估计与佩戴者手部筛选 | ## 支持的任务 LAS 空间感知算子为您提供目标检测+目标分割的核心能力，您可以通过算子请求参数 `action` 指定任务类型为目标检测（`detect`）还是目标分割（`segment`），实现通用的目标检测、分割任务；同时，为提高典型场景下目标检测与分割的效率与质量，LAS 也为您预置了多类典型任务模板（`task_template`）。各类支持的任务详情如下。 ### 手部姿态估计预置任务模板 `hand_pose_estimation` 支持手部关键点识别、手部世界坐标估计，核心能力如下。 |核心能力 |能力说明 |适用的任务类型 | |---|---|---| |**手部姿态估计** |通过 `hand_pose_estimation` 识别图片或视频中的手部姿态。 |使用 `hand_pose_estimation` 处理图片或视频中的手部姿态。 | |**手部世界坐标** |Hand Pose 视频可结合调用方提供或 LAS 服务估计的针孔相机内参，返回逐帧相机位姿和 21 点手部世界坐标。 |用于分析同一请求内的手部相对位移和运动趋势；单目尺度为估计值，不适用于精密测量或跨视频直接对齐。 | |**佩戴者手部筛选** |Hand Pose 视频任务可结合头戴双目设备数据筛选佩戴者手部。 |Hand Pose 视频任务可按需启用佩戴者手部筛选。 | ### 机械臂识别与分割预置任务模板 `robot_arm_segmentation` 支持自动识别与分割具身机械臂。 |核心能力 |能力说明 |适用的任务类型 | |---|---|---| |**机械臂识别与分割** |* 通过预置任务模版`robot_arm_segmentation`自动识别视频中的机械臂及夹爪等可见部件，按机械臂实例合并后返回源画面坐标的 bbox 和 RLE mask。

* 无需 Prompt，可按需声明相机视角。部件归属和自动视角判断依赖模型，不保证所有画面均判断正确。 |适合用于机器人操作数据清洗、机械臂区域标注与跨帧跟踪，也可作为夹爪状态分析、交互关系理解等下游任务的前置输入 | ### 交互物品检测与分割预置任务模板 `active_object_grounding` 支持自动识别与分割通用交互物品。 |核心能力 |能力说明 |适用的任务类型 | |---|---|---| |**交互物品检测与分割** |* 通过预置任务模板 `active_object_grounding` 自动识别具身操作视频中的交互物品，返回物体名称、描述、交互区间、bbox 轨迹和帧级 RLE mask。

* 无需 Prompt；默认按交互区间分窗定位、分割与跟踪，也可开启全局发现和长程跟踪，或补充物品特定名称和已知实例信息。 |适合用于具身操作数据清洗、交互物品标注与跨帧跟踪。 | |**交互式实例分割** |使用正负点或像素框约束目标，返回源分辨率网格上的实例 mask。 |使用按 target 分组的 point/box Prompt 分割目标。 | ### 通用目标检测与分割您可通过算子请求参数 `action` 指定任务类型为目标检测（`detect`）还是目标分割（`segment`），通过输入 Prompt 来实现通用的目标检测、分割任务；也可使用预置任务 `grounded_segmentation` 来基于文本描述进行目标识别与分割。 |核心能力 |能力说明 |适用的任务类型 | |---|---|---| |**文本目标检测** |根据对象名称、类别或外观描述，在图片或视频采样帧中返回目标 bbox；视频结果带有跨帧轨迹标识。 |使用 text prompt 检测图片或视频中的目标。 | |**文本定位后分割** |通过 `grounded_segmentation@v1` 先根据文字描述找到目标，再沿目标轮廓将其从背景中精确圈出，并在后续视频帧中持续跟踪。 |使用 text prompt 直接对目标进行分割。 | |**视频目标跟踪** |在采样帧之间保持对象实例和轨迹身份，逐帧返回 bbox、mask 与时间信息。 |* 先使用文本定位候选对象，再执行分割和视频传播。

* 目标分割支持在视频场景进行跨帧跟踪。 | ## 效果展示 ### 通用目标检测与分割 * 示例场景： * 分割并追踪视频中的机械夹爪 * 输入视频 [video](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/7ffc11cabbcf40c99a1ecf5ce66478ca~tplv-goo7wpa0wc-image.image) * 任务代码\-核心参数示例 ```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) * 基于输出结果的视频标注展示 [video](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/c97980e29b3c49a280a42bc7a3914667~tplv-goo7wpa0wc-image.image) ——注意，本算子不直接返回视频结果，以上为基于算子处理结果 manifest 的 `bbox` 和 COCO RLE `mask`，在原视频上叠加标注后的示例。 ### 手部姿态估计 --- **【示例1：未开启佩戴者手部筛选（ownership）】** * 输入示例 * 左目视频 [video](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2ded157808ea437b86246dcd56a1849a~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 } } ``` * 输出结果示例 [manifest(1).json](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/712206c650c64f5a99db187d8ba36454~tplv-goo7wpa0wc-image.image) * 基于输出结果视频标注展示 [video](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/d4f3e59b2f1447dbad0bf0abe23a9cc9~tplv-goo7wpa0wc-image.image) ——注意，本算子不直接返回视频结果，以上为基于算子处理结果 manifest 在原视频上进行标注后的示例。 --- **【示例2：开启佩戴者手部筛选（ownership）】** * 输入示例 * 左目视频、时间戳、鱼眼相机参数 [video](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/2ded157808ea437b86246dcd56a1849a~tplv-goo7wpa0wc-image.image) [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) * 右目视频、时间戳、鱼眼相机参数 [video](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/8c003b7b636e4f1bb7fc3cdbd36aafbd~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) * 基于输出结果视频标注展示 [video](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/a0429b7aa5f04d02b3919596e47d4cdf~tplv-goo7wpa0wc-image.image) ——注意，本算子不直接返回视频结果，以上为基于算子处理结果 manifest 在原左视频上进行标注后的示例。 --- **【示例 3：手部世界坐标】** * 输入示例 * 单目头戴视频 [video](https://lf3-static.bytednsdoc.com/obj/eden-cn/fgeh7lpauhz/cc8ba1ec-0f97-4992-ba58-f17816542c80.mp4) * 任务代码\-核心参数示例 ```JSON { "data": { "task_template": "hand_pose_estimation@v1", "media": { "uri": "https://lxxxxxf17816542c80.mp4", "type": "video", "fps": 10, "max_frames": 50 }, "task_context": { "camera_estimation": { "enabled": true, "model": "pinhole" }, "world_coordinates": { "enabled": true, "quality": { "min_tracking_coverage": 0.8, "min_valid_hand_frame_coverage": 0.5 } } } } } ``` * 本示例由 LAS 估计针孔相机内参。如果已有与输入画面匹配的针孔相机内参，也可通过 `task_context.camera` 直接提供。 * 基于输出结果的世界坐标标注展示 [video](https://lf3-static.bytednsdoc.com/obj/eden-cn/fgeh7lpauhz/9e795648-6ec0-4160-9dbe-be8186b42c4f.mp4) * 输出的 Hand Pose manifest 1.1 包含逐帧相机位姿 `camera_pose` 和 21 点手部世界坐标 `keypoints_3d_world`。使用结果前，需检查 `world_coordinates.status` 和逐手 `keypoints_3d_world.valid`。 ——注意，本算子不直接返回视频结果，以上输出视频为基于 Hand Pose manifest 1.1 在原视频上叠加世界坐标标注后的示例。世界坐标以首个有效相机位姿为原点，单目尺度为估计值，仅适合分析同一请求内的相对位移和运动趋势。 --- ## 支持的地域 * 北京：cn\-beijing * 上海：cn\-shanghai ## 算子性能 |细分项 |性能影响说明 | |---|---| |最大 RPM |600 | |最大并发数 |10 | # 输入与输出要求 ## 输入要求 |细分 |详细要求 | |---|---| |支持的输入数据模态 |* 视频

* 图片

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

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

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

* 大小、时长等：

* 图片大小 ≤100 MiB；视频大小 ≤5 GiB，其中 `active_object_grounding` 视频大小不超过 2 GiB。

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

* 视频采样 fps 范围为 [0.1, 30]，且不得高于源视频 fps。 | |任务特殊要求：手部姿态预估 |* Hand Pose 任务：

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

* 开启佩戴者手部筛选时，视频帧采样 fps 不得低于 10。

* 开启手部世界坐标时，必须显式设置 `media.max_frames`，当前最多处理 10800 个采样帧，且不支持跨分片拼接世界轨迹。

* 不支持输入 Prompt。 | |任务特殊要求：机械臂任务 |* 机械臂 Grounding 任务：

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

* 视频帧采样 fps 默认为 2。

* 不支持输入 Prompt。 | |任务特殊要求：交互物品任务 |* 交互物品 Grounding 任务：

* 仅支持视频和 `segment`，视频时长不超过 600 秒。

* 视频帧采样 fps 默认为 0.5，支持范围为 `[0.1, 30]`。默认交互流程的物品清单固定按 2 FPS 生成，局部定位会根据时间窗口自适应抽帧；全局发现流程最多选取 150 帧进行 VLM 发现。请求中的 fps 不表示最终结果的输出帧率。

* `media.max_frames` 默认不传；传入时支持范围为 `[1, 360]`，但不限制该任务的总处理帧数或输出帧数。SAM 会按最多包含 360 个源帧的窗口分段处理。

* 不支持输入 Prompt。 | |任务特殊要求：通用目标检测与分割 |* 普通检测、分割和 grounded_segmentation 任务：

* 视频帧采样默认为 5；最高支持 3000 个采样帧；超过 360 帧时，需同时满足 `media.fps <= 10` 且源视频时长不超过 600 秒。

* 每个请求支持 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` 使用 Seed 2.1 Turbo，并按模型 Token 用量计费。 | |计费类型 |按量计费，按实际的计费用量每小时出账。 | |单价与计费公式 |不同计费项单价不一致详情见下表，计费公式为：`费用 = 目标检测与分割费用 + 模型调用费用`。 | * 计费单价 * **目标检测与分割费用**：`1.6 元/千帧` * **模型调用费用**： > **说明** > 本节单价仅适用于机械臂检测与分割任务（`task_template=robot_arm_segmentation`）。 |模型名称 |输入 |缓存命中 |输出 | |---|---|---|---| |Seed 2.1 Turbo |6 元/百万 tokens |1.2 元/百万 tokens |30 元/百万 tokens | ## 交互物品检测与分割任务 * 计费标准 |细分项 |计费标准说明 | |---|---| |计费项 |当前包含以下两个计费项：

* **目标检测与分割费用**：按任务实际处理的有效采样帧数计费，可通过 Poll 接口返回的 `prompt_frame_count` 查看。

* **模型调用费用**：`task_template=active_object_grounding` 使用 Seed 2.1 Lite，并按模型 Token 用量计费。 | |计费类型 |按量计费，按实际的计费用量每小时出账。 | |单价与计费公式 |`费用 = 目标检测与分割费用 + 模型调用费用`。 | * 计费单价 * **目标检测与分割费用**：`1.6 元/千帧` * **模型调用费用**： |模型名称 |输入 |缓存命中 |输出 | |---|---|---|---| |Seed 2.1 Lite |1.6 元/百万 tokens |0.32 元/百万 tokens |5.4 元/百万 tokens | ## 通用目标检测与分割任务 * 计费标准 |细分项 |计费标准说明 | |---|---| |计费项 |按有效目标实际处理的采样帧数计费。

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

* 您可以通过 poll接口返回的 `prompt_frame_count`参数查看当前任务的有效目标实际处理的采样帧数。 | |计费类型 |按量计费，按实际的计费用量每小时出账。 | |单价 |单价为 `1.6 元/千帧`，`费用 = 单价 * 用量`。 | # 注意与前提 ## 申请开白当前功能处于白名单阶段，使用前需[提交工单](https://console.volcengine.com/workorder/create?step=1)申请开通。 ## 其他 |细分项 |注意与前提 | |---|---| |开通 LAS |* 如果您是一个全新的火山引擎用户，此前未开通过 LAS 产品，您可先开通 LAS，不使用 LAS 的计费功能仅开通 LAS 产品不会产生费用。开通操作请参见[准备工作](https://docs.volcengine.com/docs/6492/1264537)。

* 开通完成后可查看算子介绍文档，了解算子能力、上手引导等，详情可参见：[LAS 智能数据处理算子](https://docs.volcengine.com/docs/6492/1798368)。 | |功能开通 |当前功能处于白名单阶段，使用前需[提交工单](https://console.volcengine.com/workorder/create?step=1)申请开通。 | |费用 |调用算子前，您需先了解使用算子时的模型调用费用，详情请参见[大模型调用计费](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` 自动分割视频中的机械臂，以及通过 `active_object_grounding` 检测并分割视频中的交互物品。图片结果通过 Poll 响应内联返回，视频结果通过结果 manifest 返回。 ### 请求参数 **operator_id** string 必选 `示例值: las_spatial_perception` 算子 ID，固定为 `las_spatial_perception`。 **operator_version** string 必选 `示例值: v1` 算子版本，固定为 `v1`。 **data** SpatialPerceptionInfo 必选空间感知任务参数。 **action** string `Conditional` `示例值: segment` 任务动作，枚举值包括`detect`、`segment`。`action` 与 `task_template` 至少传一个，两者同时传入时必须语义一致。 * `detect` 表示目标检测：根据文本 Prompt 找出目标位置并返回 bbox，视频结果包含跨帧轨迹。 * `segment` 表示目标分割：根据文本、点或框 Prompt 精确圈出目标区域并返回 bbox 和 mask，视频输入还会把同一目标的分割结果传播到后续采样帧。 * 当同时配置`action` 与 `task_template`请求参数时，`task_template=hand_pose_estimation` 仅支持 `detect`，省略时自动按 `detect` 处理；`task_template=robot_arm_segmentation` 和 `task_template=active_object_grounding` 仅支持 `segment`，省略时自动按 `segment` 处理。 **task_template** string `Conditional` `示例值: grounded_segmentation` 任务模板，与 `action` 至少传一个。支持 `grounded_segmentation`（文本定位后分割）、`hand_pose_estimation`（手部姿态估计）、`robot_arm_segmentation`（机械臂识别与分割）和 `active_object_grounding`（交互物品检测与分割）。 **ark_api_key** string `Optional` 仅机械臂识别与分割任务（`robot_arm_segmentation` ）、交互物品检测与分割任务（`active_object_grounding`）需要配置，配置为调用方舟模型的 Ark API Key。后续调用 LAS 算子处理对应任务时，会通过此 Ark API Key 调用方舟模型，产生的模型费用也会归属到此 Ark API Key 的账号中，LAS 不收取模型 Token 费用；不填写时由 LAS 调用模型，并按算子定价收取 Token 费用。两种方式均收取 LAS 帧费。 **media** SpatialMedia 必选输入图片或视频。 **uri** string 必选 `示例值: tos://example-bucket/input.mp4` 输入媒体地址。支持 `http://`、`https://`、`tos://`。HTTP(S) 地址必须可直接下载；TOS 对象由服务使用调用方权限读取。 **type** string `Conditional` `示例值: video` 设置当前输入数据类型，支持的类型：`image` 或 `video`。可根据 URI 后缀识别时可省略；无后缀或后缀不可识别时必须显式传入。支持的图片后缀：bmp、gif、jpeg、jpg、png、tif、tiff、webp；支持的视频后缀：avi、m4v、mkv、mov、mp4、mpeg、mpg、webm。 **fps** float `Optional` `示例值: 5` 设置输入视频的采样频率，仅视频类输入支持设置。采样频率范围为 `[0.1, 30]`，且不得高于源视频 fps。各预置任务模板的视频输入还需满足对应的采样帧数和视频时长限制。 * `hand_pose_estimation` 默认 10，启用佩戴者手部筛选（`ownership.enabled=true`）时不得低于 10。 * `robot_arm_segmentation` 默认 2、参数上限为 30。 * `active_object_grounding` 默认 0.5，支持范围为 `[0.1, 30]`。默认交互流程的物品清单固定按 2 FPS 生成，局部定位会根据时间窗口自适应抽帧；全局发现流程最多选取 150 帧进行 VLM 发现。该参数不表示最终结果的输出帧率。 * 普通任务采样频率默认 5。 **max_frames** integer `Optional` `示例值: 1200` 设置输入视频的最多处理的采样帧数，仅视频类输入支持设置。 * 手部姿态估计 `hand_pose_estimation` 任务：支持的范围为`[1, 18000]`，开启世界坐标时必须显式提供该参数，当前参考上限为 10800 个采样帧，且不支持跨分片世界轨迹拼接；同时源视频时长不得超过 600 秒。 * 机械臂识别与分割 `robot_arm_segmentation` 任务：支持的范围为 `[1, 18000]`。同时源视频时长不得超过 1800 秒。 * 交互物品识别 `active_object_grounding` 任务：默认不传；传入时支持范围为 `[1, 360]`，但不限制该模板的总处理帧数或输出帧数。SAM 会按最多包含 360 个源帧的窗口分段处理；同时源视频时长不得超过 600 秒。 * 普通检测、分割，和 `grounded_segmentation` 任务：最高支持 3000 帧；超过 360 帧时，需同时满足 `media.fps <= 10` 且源视频时长不超过 600 秒。 **prompts** array of SpatialPrompt `Conditional` 模板检测和分割的文本描述，普通检测或分割任务必选，长度为 1～5，支持文本、点和框三种形式。`hand_pose_estimation`、`robot_arm_segmentation` 和 `active_object_grounding` 不接受该字段。 **target** string `Conditional` `示例值: gripper_01` 调用方自定义的对象分组标识，长度 1～64，仅允许 ASCII 字母、数字、下划线和连字符。同一 target 的多个交互 Prompt 共同约束同一对象。 **type** string 必选 `示例值: text` Prompt 类型，支持 `text`（文本）、`point`（点坐标）、`box`（框坐标）。同一请求不能混用 text 与 point/box；point/box 输入坐标以及返回的 bbox 和 mask 均基于源媒体坐标。 * `action=detect` 仅支持 text； * `action=segment` 支持 text 或按 target 分组的 point/box； * `grounded_segmentation` 仅支持 text。 **label** string `Optional` `示例值: gripper` 可选的输出对象名称，text、point、box 三种 Prompt 均支持，返回在 `frames[].objects[].label` 中。该参数仅用于命名，不改变识别或分割目标，也不替代 `text` 或 `target`。 * 指定非空 `label` 时，输出原样使用该值，不会被检测结果中的名称覆盖。 * 未传 `label` 或传入空字符串时，point/box Prompt 使用 `target` 作为输出标签；原生 text 检测或分割使用 `text`；`grounded_segmentation` 使用从输入 `text` 中提取的匹配词组，无法提取时使用完整 `text`。 * 同一 `target` 的 point/box Prompt 共享一个输出标签。第一条 Prompt 设置非空 `label` 后，后续同一 `target` 的 `label` 必须省略、传空字符串或保持一致；第一条未设置时使用 `target`，后续不能改为其他名称。 **text** string `Conditional` `示例值: robot gripper` 文本 Prompt 的目标名称、类别或可见外观描述。请尽量输入简洁的英文描述。完整 Prompt 示例：`{"type":"text","text":"robot gripper","label":"gripper"}`。 **point** array of float `Conditional` `示例值: [960,720]` 源媒体像素坐标 `[x,y]`。坐标必须为非负有限数。完整 Prompt 示例：`{"type":"point","target":"gripper_01","label":"gripper","point":[960,720],"positive":true}`。 **positive** boolean `Optional` `示例值: true` 仅对 point 类型的 Prompt 对象生效，默认 `true`。`true` 表示“这个点在目标上”，用于帮助模型选中目标；`false` 表示“这个点不在目标上”，用于排除误选区域。未提供 box 时，同一 target 的 point 中至少有一个需要设置为 `positive=true`；已提供 box 时，其他 point 可以全部设置为 `positive=false`。 **box** array of float `Conditional` `示例值: [700,400,1180,920]` 源媒体像素坐标 `[x0,y0,x1,y1]`，必须满足 `x1>x0`、`y1>y0`。同一 target 最多一个 box。完整 Prompt 示例：`{"type":"box","target":"gripper_01","label":"gripper","box":[700,400,1180,920]}`。 **task_context** SpatialTaskContext `Conditional` 模板专用上下文。不同模板的上下文字段不能混用。`active_object_grounding` 任务必须传入该参数；如无需自定义配置，可传入空对象 `{}` 使用默认值。 `hand_pose_estimation` 可通过 `camera` 提供相机标定参数、通过 `camera_estimation` 请求估计内参、通过 `world_coordinates` 请求世界坐标，也可通过 `ownership` 启用佩戴者手部筛选； `robot_arm_segmentation` 可通过 `camera_view` 声明相机视角； `active_object_grounding` 可配置检测范围、掩码输出、长程跟踪、跟踪恢复、affordance 标注，以及物品特定名称或已知实例信息。 `active_object_grounding` 的 `task_context` 为必选参数，无需自定义配置时可传 `{}` 使用默认值。`long_track`、`all_interactable_objects`、`affordance_annotation` 均为 `false` 时走默认交互流程；任一参数为 `true` 时走全局发现流程。`bbox_only` 仅控制是否输出掩码，不切换流程。两种流程均通过 `result_manifest_url` 交付完整结果，请直接使用该地址，不要根据文件名拼接。 **camera** HandPoseCameraInput `Optional` `示例值: {"model":"pinhole","intrinsics":[636.66,636.25,635.29,366.87]}` 仅 `hand_pose_estimation` 支持，为 `media.uri` 中输入的图片或视频提供相机标定参数。不传且未启用内参估计（`camera_estimation.enabled=false`）时，使用模型的虚拟相机。 **model** string `Optional` `示例值: pinhole` 相机模型，支持 `pinhole` 和 `kb4`，默认 `pinhole`。如果开启世界坐标模式（`world_coordinates.enabled=true`）只接受已完成去畸变的针孔画面和对应的 `pinhole` 内参，或启用 `camera_estimation`。 **intrinsics** array of float 必选 `示例值: [636.66,636.25,635.29,366.87]` 相机内参 `[fx,fy,cx,cy]`，单位为像素，必须是 4 个有限数值，且 `fx`、`fy` 大于 0。一条请求中的所有帧共用该内参；暂不支持逐帧内参。内参必须与输入媒体的实际画面一致，媒体经过缩放、裁剪或旋转时需同步调整。没有可靠内参时应省略整个 `camera`，不要填写估算值。 **distortion_coefficients** array of float `Optional` `示例值: [-0.01,0.002,0.0,0.0]` KB4 鱼眼模型的 `[k1,k2,k3,k4]`，必须是 4 个有限数值。`model=kb4` 时必选；针孔模型必须省略或传空数组。 **calibration_resolution** array of integer `Conditional` `示例值: [1280,720]` 标定内参对应的 `[width,height]`，两个值均须为正整数。`model=kb4` 时必选，针孔模型可省略；提供时必须与服务解码到的媒体尺寸一致。 **camera_estimation** CameraEstimationInput `Optional` `示例值: {"enabled":true,"model":"pinhole"}` 仅 `hand_pose_estimation` 支持。未提供 `camera` 时，LAS 会自动进行服务内参估计，LAS 自动估计结果是否可用取决于视频本身配置。 **enabled** boolean `Optional` `示例值: true` 是否请求服务估计相机内参，默认 `false`。已提供 `camera` 时直接使用 `camera` 参数提供的相机内参数据。 **model** string `Optional` `示例值: auto` 估计目标模型，可选 `auto`、`pinhole`、`kb4`。仅当 `camera_estimation.enabled=true` 时可传；省略时使用部署策略，当前默认 `auto`。如果开启世界坐标模式（`world_coordinates.enabled=true`）建议配置为 `pinhole`，不可配置为 `kb4`；如果配置为 `auto` ，最终选择到 KB4、无法判定或估计失败时，服务使用假设针孔内参继续处理，并将世界坐标标记为降级。 **world_coordinates** WorldCoordinatesInput `Optional` `示例值: {"enabled":true}` 仅 `hand_pose_estimation` 视频支持，默认关闭。开启后计算相机轨迹及手部世界坐标，并发布 Hand Pose manifest 1.1；开启时，必须显式提供 `media.max_frames`。 **enabled** boolean `Optional` `示例值: true` 是否计算世界坐标，默认 `false`。设为 `false` 时不得传 `quality`。 **quality** WorldCoordinatesQuality `Optional` `示例值: {"min_tracking_coverage":0.8,"min_valid_hand_frame_coverage":0.5}` 世界坐标质量门。客户端参数只能在服务端最低门限基础上收紧，不能放宽。 **min_tracking_coverage** float `Optional` `示例值: 0.8` 相机轨迹有效帧占处理帧的最低比例，范围 `[0,1]`，默认 `0.8`。 **min_valid_hand_frame_coverage** float `Optional` `示例值: 0.5` 至少包含一只有效世界坐标手的帧，占所有检测到手的帧的最低比例，范围 `[0,1]`，默认 `0.5`。 **ownership** HandPoseOwnership `Optional` 仅 `hand_pose_estimation` 支持。配置头戴双目设备佩戴者手部筛选。 **enabled** boolean `Optional` `示例值: true` 是否启用佩戴者手部筛选，默认 `false`。设为 `false` 时不得传 `stereo`。 **stereo** HandPoseStereoInput `Conditional` `ownership.enabled=true` 时必选。启用佩戴者手部筛选时，需将请求参数 `media.uri` 设置为左目视频，并在 `stereo` 中配置右目视频、左右目时间戳等其他输入参考。 **right_media_uri** string 必选 `示例值: tos://example-bucket/right.mp4` 与 `media.uri` 左目视频配对的右目视频地址，支持 HTTP(S) 和 TOS。 **left_timestamps** OwnershipDocument 必选 `示例值: {"uri":"tos://example-bucket/left.txt"}` 左目时间戳。支持通过子参数 `uri` 配置为远程文档地址，或通过子参数 `content` 直接配置为时间戳文本，两者均要求时间戳正文文本每行对应原视频一帧，填写严格递增的纳秒整数。 **uri** string `Conditional` `示例值: tos://example-bucket/calibration.json` 远程文档地址，支持 `http://`、`https://`、`tos://`。与 `content` 必须且只能提供一个。 **content** string `Conditional` `示例值: "1000000000\n1033333333\n"` UTF\-8 内联文档内容。与 `uri` 必须且只能提供一个。 **right_timestamps** OwnershipDocument 必选 `示例值: {"uri":"tos://example-bucket/right.txt"}` 右目时间戳，格式与左目相同，并使用相同时间基准。 **uri** string `Conditional` `示例值: tos://example-bucket/calibration.json` 远程文档地址，支持 `http://`、`https://`、`tos://`。与 `content` 必须且只能提供一个。 **content** string `Conditional` `示例值: "1000000000\n1033333333\n"` UTF\-8 内联文档内容。与 `uri` 必须且只能提供一个。 **left_intrinsic** OwnershipDocument 必选 `示例值: {"uri":"tos://example-bucket/left.json"}` 左目鱼眼相机内参，JSON 字段包括 `Fx/Fy/Cx/Cy`、`k1`～`k4`、`width/height`。支持通过子参数 `uri` 配置为远程文档地址，或通过子参数 `content` 直接配置为相机内参文本。 **uri** string `Conditional` `示例值: tos://example-bucket/calibration.json` 远程文档地址，支持 `http://`、`https://`、`tos://`。与 `content` 必须且只能提供一个。 **content** string `Conditional` `示例值: "1000000000\n1033333333\n"` UTF\-8 内联文档内容。与 `uri` 必须且只能提供一个。 **right_intrinsic** OwnershipDocument 必选 `示例值: {"uri":"tos://example-bucket/right.json"}` 右目鱼眼相机内参，格式与左目相同。 **uri** string `Conditional` `示例值: tos://example-bucket/calibration.json` 远程文档地址，支持 `http://`、`https://`、`tos://`。与 `content` 必须且只能提供一个。 **content** string `Conditional` `示例值: "1000000000\n1033333333\n"` UTF\-8 内联文档内容。与 `uri` 必须且只能提供一个。 **extrinsic** OwnershipDocument 必选 `示例值: {"uri":"tos://example-bucket/extrinsic.json"}` 从左目到右目的外参，JSON 包含四元数 `rotation{x,y,z,w}` 和米制 `translation{x,y,z}`。支持通过子参数 `uri` 配置为远程文档地址，或通过子参数 `content` 直接配置为外参文本。 **uri** string `Conditional` `示例值: tos://example-bucket/calibration.json` 远程文档地址，支持 `http://`、`https://`、`tos://`。与 `content` 必须且只能提供一个。 **content** string `Conditional` `示例值: "1000000000\n1033333333\n"` UTF\-8 内联文档内容。与 `uri` 必须且只能提供一个。 **camera_view** string `Optional` `示例值: wrist` 仅 `robot_arm_segmentation` 支持，默认 `auto`。可选值：`auto`（由模型判断）、`wrist`（腕部相机）、`head_body`（头部或身体相机）、`external`（外部相机）。显式填写时作为已知相机安装信息使用；模型结果与该值冲突时，本次结果校验失败。`auto` 依赖模型判断，不保证所有画面都能正确识别视角。 **bbox_only** boolean `Optional` `示例值: false` 仅 `active_object_grounding` 支持，默认 `false`。设为 `true` 时仍执行 SAM 跟踪和分割，保留帧级 bbox 和轨迹，仅省略 `mask`、`mask_area` 输出；不改变处理流程。 **long_track** boolean `Optional` `示例值: false` 仅 `active_object_grounding` 支持，默认 `false`。设为 `true` 时走全局发现流程，跟踪物体首次到末次可见的范围；设为 `false` 时仅覆盖交互时间段。 **all_interactable_objects** boolean `Optional` `示例值: false` 仅 `active_object_grounding` 支持，默认 `false`。设为 `false` 时，仅识别实际被操作的物品和目标容器；设为 `true` 时，识别场景内全部可交互物品。 **tracking_recovery** boolean `Optional` `示例值: false` 仅 `active_object_grounding` 支持，默认 `false`，仅可与 `long_track=true` 搭配使用。根据已有 VLM 锚点检查跟踪异常，满足触发条件时每个窗口最多换种子补跟踪一次。 **affordance_annotation** boolean `Optional` `示例值: false` 仅 `active_object_grounding` 支持，默认 `false`。开启后走全局发现流程，在选定定位帧上增加可见部件及 affordance 标注。 **prompt_context** string `Optional` `示例值: 画面中的透明带盖塑料盒统一命名为“物料收纳盒”。` 仅 `active_object_grounding` 支持，默认为空。当需要补充物品特定名称或已知实例信息，以帮助模型理解视频内容时可配置；一般识别场景可不填写。 **output** SpatialOutput `Optional` `示例值: {"destination":"tos://bucket/results"}` 视频结果 manifest 的可选发布目录。 **destination** string `Optional` `示例值: 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 异常信息。 ### 示例 #### 请求示例1：目标识别示例 ```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", "label": "gripper"}, {"type": "text", "text": "cucumber", "label": "held_object"} ] } }' ``` #### 请求示例2：机械臂检测与分割示例 ```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" } } }' ``` #### 请求示例3：交互物品检测与分割示例 ```Bash # Active Object 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": "active_object_grounding", "media": { "uri": "https://example.com/input.mp4", "type": "video", "fps": 0.5 }, "task_context": { "all_interactable_objects": false, "bbox_only": false, "long_track": true, "tracking_recovery": true, "affordance_annotation": true, "prompt_context": "画面中的透明带盖塑料盒统一命名为‘物料收纳盒’。" } } }' ``` #### 请求示例4：手部姿态估计示例 ```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], "calibration_resolution": [1280, 720] }, "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"} } } } } }' ``` #### 请求示例5：手部世界坐标示例 ```Bash # Hand Pose World Coordinates 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/input.mp4", "type": "video", "fps": 10, "max_frames": 1200 }, "task_context": { "camera_estimation": { "enabled": true, "model": "pinhole" }, "world_coordinates": { "enabled": true, "quality": { "min_tracking_coverage": 0.8, "min_valid_hand_frame_coverage": 0.5 } } } } }' ``` 也可通过 `task_context.camera` 提供已标定且与输入画面一致的针孔相机内参。未提供 `camera` 时可启用 `camera_estimation`；估计失败或无法获得可用针孔内参时，基础 Hand Pose 数据仍会返回，世界坐标结果会标记为降级或不可用。当前世界坐标以首个有效相机位姿为原点，只适合分析同一请求内的相对位移和运动趋势。 #### 返回示例 ```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` 数组长度；`active_object_grounding` 的默认交互流程和全局发现流程均返回源视频总帧数，与 manifest 的 `frame_count` 一致，但不等于 `frames` 数组长度。 **prompt_frame_count** integer `示例值: 120` 计费数量，表示各有效 Prompt 目标实际处理的采样帧数之和。文本 Prompt 按每条统计；同一 target 的 point/box 合并为一个有效目标。没有选中目标时可为 `0`，帧费按该值计收。 `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` 和 `active_object_grounding` 返回任务实际处理的有效 prompt\-frame 累计值； **video_duration** float `示例值: 12.0` 仅视频返回，源视频时长，单位为秒。 **resolution** string `示例值: 1920x1080` 源媒体分辨率，格式为 `宽x高`。 **frames** array of SpatialFrame 仅图片通过 Poll 内联返回；视频 manifest 使用相同的逐帧结果结构。图片结果无需另外下载结果文件。 **source_frame_index** integer `示例值: 0` 源媒体帧序号，图片固定为 0。 **timestamp** float `示例值: 0.0` 相对视频开头的秒数，图片固定为 0。 **objects** array of SpatialObject 或 HandPoseObject 当前帧识别到的对象。普通检测/分割任务、`robot_arm_segmentation` 和 `active_object_grounding` 返回 `SpatialObject`；`hand_pose_estimation` 返回 `HandPoseObject`。普通任务未识别到对象时返回空数组；`active_object_grounding` 仅列出实际返回观测的帧，不保证为无结果帧补空记录。 **object_id** string `示例值: obj_000_001` 对象实例标识。`active_object_grounding` 两种流程均通过该字段关联顶层 `objects[].object_id`。 **prompt_index** integer `示例值: 0` 目标对应的 Prompt 序号；`active_object_grounding` 的该字段由模板生成，`robot_arm_segmentation` 不返回该字段。 **bbox** array of float `示例值: [233,178,393,409]` 源媒体像素坐标 `[x0,y0,x1,y1]`。 **label** string `示例值: gripper` 输出对象标签。普通检测/分割任务优先原样返回输入的非空 `label`；未设置时，point/box Prompt 使用 `target`，原生 text 检测/分割使用 `text`，`grounded_segmentation` 使用从输入 `text` 中提取的匹配词组，无法提取时使用完整 `text`。`robot_arm_segmentation` 固定返回 `robot_arm`；`active_object_grounding` 使用模型识别的物品名称，对应顶层 `objects[].name`，详细描述位于 `objects[].description`。 **detection_score** float `示例值: 0.92` 目标被检测出来时的置信度，范围 `[0,1]`。仅模型实际提供时返回。 **object_presence_score** float `示例值: 0.87` 分割或跟踪过程中，模型判断该目标仍在当前帧中的置信度，范围 `[0,1]`；不是 mask 质量分。 **track_id** string `示例值: track_000_001` 视频检测/分割对象的跨帧轨迹标识。普通视频任务、`robot_arm_segmentation` 和 `active_object_grounding` 均可能返回。 **mask** SpatialRleMask `segment`、`robot_arm_segmentation` 和 `active_object_grounding` 返回的实例分割掩码；`active_object_grounding` 设置 `bbox_only=true` 时不返回。 **format** string `示例值: rle` 固定为 `rle`，表示 COCO compressed RLE。 **size** array of integer `示例值: [480,640]` 掩码网格 `[height,width]`，使用源媒体分辨率。 **counts** string 可写入 JSON 的 ASCII 压缩字符串。 **mask_area** integer `示例值: 12477` mask 的前景像素数。`active_object_grounding` 两种流程中可能缺失或为 `null`，设置 `bbox_only=true` 时不返回。 **interacted** boolean `示例值: true` 仅 `active_object_grounding` 返回，两种流程均适用。表示当前帧时间戳是否位于该物体的交互区间 `[start,end)` 内；开启 `long_track=true` 后，非交互但物体可见的帧可返回 `false`。 **result_manifest_url** string `示例值: https://example.com/manifest.json` 仅视频返回。未指定 `output.destination` 时为有效期 259200 秒的 LAS 托管签名 HTTPS；指定时返回对应的 TOS URI。`active_object_grounding` 默认交互流程指向 `object.json`，全局发现流程指向 `manifest.json`；两者均为完整结果文件。 **objects** array of ActiveObjectGroundingObject 仅位于 `active_object_grounding` 完整结果文件顶层，两种流程均返回。 **object_id** string 本视频内的物体实例标识，与帧级对象一致。 **name** string 物体名称，对应帧级 `label`。 **description** string 物体的详细外观描述。 **interactions** array of object 交互区间数组；无交互区间时为空数组。 **start** float `示例值: 2.5` 相对视频开头的交互开始时间，单位秒。 **end** float `示例值: 5.5` 相对视频开头的交互结束时间，区间为 `[start,end)`，单位秒。 **arm** string `示例值: both_arms` 参与交互的操作侧：`left_arm`、`right_arm`、`both_arms` 或 `uncertain`；不表示已判定为人手还是机械臂。 **evidence** string `示例值: 双侧手共同握持门体侧边并向外拉开。` 交互动作及其视觉依据。 **trajectory** array of object 由实际帧级 bbox 观测按时间汇总的轨迹，不插值、不保证覆盖每一帧，不包含 mask；无有效观测时可为空数组。 **source_frame_index** integer `示例值: 75` 从 0 开始的源视频帧索引。 **timestamp** float `示例值: 2.5` 相对视频开头的时间戳，单位秒。 **bbox** array of float `示例值: [288.0,81.0,555.0,546.0]` 源视频像素坐标 `[x0,y0,x1,y1]`，与对应帧级观测一致。 **track_id** string `示例值: track_000_000001` 对应帧级观测的轨迹标识。 **grounding_quality** ActiveObjectGroundingQuality `active_object_grounding` 默认交互流程默认返回的质量与失败窗口信息；全局发现流程不保证返回。 **grounding_status** string `complete` 表示无窗口失败；`partial` 表示存在失败窗口并返回其余成功结果，不表示识别准确率。 **failed_window_count** integer 失败窗口数量。 **validation** string 结果校验方式。 **failed_windows** array of object 失败窗口详情；无失败时为空数组。 **token_usage** object of SpatialTokenUsage `示例值: {"doubao-seed-2-1-pro-260915":{"prompt_tokens":3940,"completion_tokens":2562,"total_tokens":6502,"cached_tokens":0}}` `robot_arm_segmentation` 和 `active_object_grounding` 返回。按模型名汇总本次任务中所有 VLM 调用的 token 用量，包括首次调用以及格式校验失败后触发的补试。 **prompt_tokens** integer 输入 token 数。 **completion_tokens** integer 输出 token 数。 **total_tokens** integer 总 token 数。 **cached_tokens** integer 缓存命中的输入 token 数，仅在服务返回时提供。 **token_usage_complete** boolean `示例值: true` `robot_arm_segmentation` 和 `active_object_grounding` 返回。表示所有 VLM 调用是否都提供了 `prompt_tokens`、`completion_tokens` 和 `total_tokens`；不表示识别准确或任务处理成功。 `hand_pose_estimation` 视频结果文件还包含以下专用字段。 **version** string Hand Pose 视频 manifest 版本，固定为 `1.1`。 **skeleton_definition** HandPoseSkeletonDefinition 21 点骨架名称、关键点顺序、连线和根节点定义。 **skeleton** string 骨架类型，固定为 `hand_21`。 **joint_names** array of string 21 个关键点名称，顺序与各类 `values` 一致。 **edges** array of array 骨架连线，元素为关键点下标对。 **root_joint_index** integer 根关节下标，固定为 0。 **coordinate_systems** HandPoseCoordinateSystems 检测框、各类关键点和相机位姿的统一坐标定义。 **bbox** object `示例值: {"space":"source_pixel"}` 手框坐标定义。 **space** string `示例值: source_pixel` 固定为源媒体像素坐标 `source_pixel`。 **keypoints_2d** object `示例值: {"space":"source_pixel"}` 2D 关键点坐标定义。 **space** string `示例值: source_pixel` 固定为源媒体像素坐标 `source_pixel`。 **keypoints_3d** object 手腕相对 3D 关键点坐标定义。 **space** string `示例值: wrist_relative_camera_axes` 固定为 `wrist_relative_camera_axes`。 **unit** string `示例值: model_meter_estimate` 固定为模型估计单位 `model_meter_estimate`。 **metric_calibrated** boolean `示例值: false` 是否已进行真实米制标定，当前为 `false`。 **keypoints_3d_camera** object 相机坐标系 3D 关键点定义。 **space** string `示例值: camera` 使用有效相机内参时为 `camera`，使用默认虚拟内参时为 `virtual_camera`。 **unit** string `示例值: model_meter_estimate` 固定为模型估计单位 `model_meter_estimate`。 **metric_calibrated** boolean `示例值: false` 是否已进行真实米制标定，当前为 `false`。 **keypoints_3d_world** object 请求世界坐标时使用的局部世界坐标定义。 **space** string `示例值: local_world` 固定为当前任务局部世界坐标 `local_world`。 **unit** string `示例值: meter_estimate` 固定为单目估计尺度 `meter_estimate`。 **metric_calibrated** boolean `示例值: false` 是否已进行真实米制标定，当前为 `false`。 **camera_pose** object 请求世界坐标时使用的相机位姿坐标定义。 **space** string `示例值: local_world` 固定为 `local_world`。 **origin** string `示例值: initial_camera` 世界坐标原点，固定为首个有效相机帧 `initial_camera`。 **axis_convention** string `示例值: x_right_y_down_z_forward` 坐标轴方向，固定为 x 向右、y 向下、z 向前。 **unit** string `示例值: meter_estimate` 平移单位，固定为 `meter_estimate`。 **metric_calibrated** boolean `示例值: false` 是否已进行真实米制标定，当前为 `false`。 **pose** HandPose 21 点手部姿态。 **keypoints_2d** HandKeypoints2D 源媒体像素坐标系下的二维手部关键点。 **values** array of array 21 个 `[x,y]` 关键点坐标。 **in_frame** array of boolean 每个二维关键点是否位于源媒体画面范围内。 **keypoints_3d** HandKeypoints3D 以手腕为原点、相机轴为参考的 21 个三维关键点，数据位于 `values`。 **keypoints_3d_camera** HandKeypoints3D 相机坐标系下的 21 个三维关键点，当前单目尺度不得直接用作测量级距离。 **keypoints_3d_world** HandPoseWorldKeypoints3D 开启世界坐标时返回；使用前必须检查 `valid`。 **bbox_space** string 手框坐标空间，返回时固定为 `source_pixel`。 **handedness** string 手性，取值为 `left` 或 `right`。 **handedness_score** float 手性置信度，范围 `[0,1]`。 **score** float 手部检测置信度；`observation=infilled` 时可能省略。 **observation** string 观测状态：`observed`、`bbox_interpolated` 或 `infilled`。 **camera** HandPoseCameraMetadata 实际使用的相机参数及来源。 **model** string 实际使用的 `pinhole` 或 `kb4`。 **intrinsics** array of float 实际使用的 `[fx,fy,cx,cy]`，单位像素。 **source** string 内参来源：`provided`、`estimated` 或 `default`。 **intrinsics_calibrated** boolean 内参是否经过真实标定。 **estimation** object 内参估计失败并回退时返回，包含 `status=fallback`、`requested_model` 和失败原因。 **distortion_model** string 畸变模型；仅 KB4 相机返回。 **distortion_coefficients** array of float KB4 的 4 个畸变系数。 **image_rectified** boolean 仅 KB4 返回，固定为 `false`，表示输出对应未矫正源画面。 **calibration_resolution** array of integer KB4 标定内参对应的 `[width,height]`。 **camera_pose** HandPoseCameraPose 开启世界坐标时的逐帧相机位姿。 **position** array of float 相机光心在世界坐标系中的 `[x,y,z]`。 **rotation_matrix** array of array 相机姿态的 3×3 旋转矩阵。 **valid** boolean 当前帧相机位姿是否有效。 **reason** string 无效原因。 **world_coordinates** HandPoseWorldSummary 世界坐标整体状态与有效帧统计。 **status** string `applied` 表示通过质量门，`degraded` 表示降级，`unavailable` 表示不可用。 **usage_notice** string 固定使用提示：世界坐标为视觉估计，不用于精密测量；使用前须检查 `status` 和逐手 `valid`。 **reason** string `status` 不是 `applied` 时的原因。 **valid_frame_count** integer 至少包含一只有效世界坐标手的帧数。 **invalid_frame_count** integer 有手但未能生成有效世界坐标手点的帧数。 **ownership** object 请求佩戴者手部筛选时返回应用状态。 ### 示例 #### 请求示例 ```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" }' ``` #### 返回示例1：通用目标识别与分割 ```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, "label": "gripper", "bbox": [233, 178, 393, 409], "track_id": "track_000_001", "mask": { "format": "rle", "size": [480, 640], "counts": "WkX13..." }, "mask_area": 12477 } ] } ] } ``` #### 返回示例2：机械臂 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], "track_id": "track_000_001", "mask": { "format": "rle", "size": [480, 640], "counts": "WkX13..." }, "mask_area": 29720 } ``` #### 返回示例3：交互物品 Grounding 视频任务返回示例 ```JSON { "metadata": { "task_id": "task-20260923120000-active-object", "task_status": "COMPLETED", "business_code": "0" }, "data": { "clazz": "las_spatial_perception", "frame_count": 212, "prompt_frame_count": 74, "video_duration": 7.066667, "resolution": "640x400", "result_manifest_url": "https://example.com/object.json", "token_usage": { "doubao-seed-2-1-pro-260915": { "prompt_tokens": 3940, "completion_tokens": 2562, "total_tokens": 6502, "cached_tokens": 0 } }, "token_usage_complete": true } } ``` 交互物品 Grounding 默认交互流程的 `object.json` 示例（仅展示一帧观测）： ```JSON { "version": "1.0", "frame_count": 212, "video_duration": 7.066667, "resolution": "640x400", "objects": [ { "object_id": "obj_001", "name": "蓝色小型固态物件", "description": "蓝色小型固态物件。", "interactions": [ { "start": 3.0, "end": 4.0, "arm": "right_arm", "evidence": "右侧操作端接触并移动该物体。" } ], "trajectory": [ { "source_frame_index": 90, "timestamp": 3.0, "bbox": [221.0, 213.0, 246.0, 236.0], "track_id": "track_000_000001" } ] } ], "frames": [ { "source_frame_index": 90, "timestamp": 3.0, "objects": [ { "object_id": "obj_001", "label": "蓝色小型固态物件", "prompt_index": 0, "bbox": [221.0, 213.0, 246.0, 236.0], "track_id": "track_000_000001", "mask": { "format": "rle", "size": [400, 640], "counts": "nTf24V<7L4O0..." }, "mask_area": 451, "interacted": true } ] } ], "grounding_quality": { "grounding_status": "complete", "failed_window_count": 0, "validation": "interaction_seed_validation", "failed_windows": [] } } ``` #### 返回示例4：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" } } ``` 开启世界坐标后的 Hand Pose manifest 1.1 示例： ```JSON { "version": "1.1", "frame_count": 120, "video_duration": 12.0, "resolution": "1920x1080", "skeleton_definition": { "name": "hand_21", "joint_names": ["wrist", "thumb_cmc"], "edges": [[0,1]], "root_joint_index": 0 }, "coordinate_systems": { "bbox": { "space": "source_pixel" }, "keypoints_2d": { "space": "source_pixel" }, "keypoints_3d": { "space": "wrist_relative_camera_axes", "unit": "model_meter_estimate", "metric_calibrated": false }, "keypoints_3d_camera": { "space": "camera", "unit": "model_meter_estimate", "metric_calibrated": false }, "keypoints_3d_world": { "space": "local_world", "unit": "meter_estimate", "metric_calibrated": false }, "camera_pose": { "space": "local_world", "origin": "initial_camera", "axis_convention": "x_right_y_down_z_forward", "unit": "meter_estimate", "metric_calibrated": false } }, "camera": { "model": "pinhole", "intrinsics": [915.2, 914.8, 960.0, 540.0], "source": "estimated", "intrinsics_calibrated": false }, "world_coordinates": { "status": "applied", "usage_notice": "World coordinates are vision-based estimates for motion and relative spatial analysis, not precision measurement. Check status and valid before use.", "valid_frame_count": 118, "invalid_frame_count": 2 }, "frames": [ { "source_frame_index": 0, "timestamp": 0.0, "camera_pose": { "position": [0.0, 0.0, 0.0], "rotation_matrix": [[1,0,0],[0,1,0],[0,0,1]], "valid": true }, "objects": [ { "track_id": "track_000_001", "handedness": "left", "bbox": [233,178,393,409], "score": 0.92, "observation": "observed", "pose": { "keypoints_2d": { "values": [[320.5,240.0]], "in_frame": [true] }, "keypoints_3d": { "values": [[0.0,0.0,0.0]] }, "keypoints_3d_camera": { "values": [[0.01,0.02,0.45]] }, "keypoints_3d_world": { "values": [[0.01,0.02,0.45]], "valid": true } } } ] } ] } ``` 示例为便于阅读，只展示了一个世界坐标关键点；实际返回固定包含 21 个 `[x,y,z]`。使用结果前，应先检查 `world_coordinates.status`，再检查逐手 `keypoints_3d_world.valid`。`meter_estimate` 且 `metric_calibrated=false` 表示尺度来自单目估计，不应作为测量级真实距离。 ### 错误码 |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` / `1.1` |通用检测、分割类 manifest 使用 `1.0`；Hand Pose 视频使用 `1.1` | |`frame_count` |`142` |输出结果覆盖的帧数 | |`video_duration` |`5.9167` |视频时长，单位秒 | |`resolution` |`1920x1080` |原视频分辨率 | |`skeleton_definition` |对象 |Hand Pose manifest 1.1 的 21 点骨架名称、关键点顺序、连线和根节点定义 | |`coordinate_systems` |对象 |Hand Pose manifest 1.1 中 bbox、各类关键点和相机位姿的统一坐标定义 | |`camera` |对象 |Hand Pose 实际使用的相机模型、内参及来源；`source` 可为 `provided`、`estimated` 或 `default` | |`world_coordinates` |对象 |请求世界坐标时返回任务级状态、使用提示、降级原因和有效帧统计 | |`frames` |数组 |每一帧的 HandPose 结果 | 每个 `frames[]` 代表一帧： |字段 |含义 | |---|---| |`source_frame_index` |原视频帧序号，从 `0` 开始 | |`timestamp` |当前帧时间戳，单位秒 | |`camera_pose` |请求世界坐标时返回当前帧相机光心位置、3×3 旋转矩阵及有效性；坐标定义见顶层 `coordinate_systems.camera_pose` | |`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 手部关键点 | |`keypoints_3d_camera` |相机坐标系下的 21 个 3D 手部关键点；单目尺度不代表测量级真实距离 | |`keypoints_3d_world` |请求世界坐标时返回同一请求局部世界坐标系中的 21 个关键点及 `valid` 状态 | 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` 一一对应 | `keypoints_3d_world`： |字段 |含义 | |---|---| |`values` |21 个 `[x, y, z]` 世界坐标；有效时返回，无效时可能省略 | |`valid` |当前手在本帧的世界坐标是否可用 | |`reason` |`valid=false` 时的原因，例如相机位姿、轨迹、尺度或有效手部覆盖率不满足要求 | `world_coordinates.status` 可取以下值： * `applied`：世界坐标通过质量门。 * `degraded`：使用了假设内参等降级条件，仍可能返回相机位姿和世界坐标值，使用时需继续检查逐手 `valid`。 * `unavailable`：世界坐标不可用；基础 Hand Pose 数据仍会保留。下面是一个 manifest 实际统计结果： ```Plain 总帧数：142 每帧检测手部数量：4 总手部对象记录数：568 输出类型：left_hand / right_hand 骨架类型：hand_21 2D 坐标：原视频像素坐标 3D 坐标：手腕相对相机坐标 ``` 可以总结为：HandPose 会返回每一帧中每只手的检测框、左右手类别、检测置信度、跨帧跟踪 ID、21 点 2D 关键点、21 点相对 3D 关键点，以及用于绘制手部骨架的关节点连接关系。

AI 数据湖服务