具身数据预检算子用于在标注和训练前筛查单路操作视频的技术质量，输出可追溯的质检结论、问题明细和视频元数据。 # 算子介绍 > 算子 ID：`las_embodied_collection_precheck` ## 适用场景 * 具身视频采集入库前，筛除黑屏、白屏、噪声、冻结、闪烁、抖动或卡顿的视频。 * 在分发标注任务前，确认视频可解析且基础元数据有效。 * 为具身数据清洗、复核和训练数据治理提供结构化质量结果。 ## 核心能力 * **七项默认检查**： * 为您预置提供了典型场景下的检查项（ `options.check_items`），支持检查视频完整性、黑白屏与噪声、画面冻结、闪烁、运动模糊、相机抖动和播放卡顿。 * 您可以设置检查全部检查项，或灵活指定需要检查的子项。 * **可配置质量策略**：支持调整事件时长、噪声、运动模糊、抖动和卡顿阈值，并控制运动类问题是否触发拒绝。 * **结构化结果**：返回业务判定、证据充分性、问题明细、问题统计和视频时长、分辨率、帧率、编码等信息。 * **可选报告发布**：设置 `output.uri_prefix` 后，将完整 JSON 报告发布到指定的 TOS 前缀。 ## 判定说明 * 任一高严重度问题会触发 `REJECT`。 * 没有问题时返回 `PASS / confirmed_consistent / sufficient`。 * 仅发现低或中严重度问题，或检查过程存在非阻断的不确定性时，可能返回 `PASS / no_confirmed_violation / insufficient`。此时 `PASS` 仅表示未触发阻断，不表示素材无缺陷。 ## 算子性能 |细分项 |限制 | |---|---| |最大 Submit RPM |60 | |最大 Poll RPM |120 | |最大并发度 |1 | |耗时 |视频越长或证据/复核越多，通常耗时越长。 | # 输入与输出要求 ## 输入要求 |细分项 |详细要求 | |---|---| |支持的数据模态 |* 视频

* 文本 | |输入模态：视频 |* 通过 `assets` 传入单路视频。

* 视频时长不超过 1 小时，文件大小不超过 1 GiB，且必须能够正常解码。 | |输入模态：文本 |\* 通过 `inputs.options` 配置检查项、采样频率和质量判定阈值；省略时使用默认七项检查及默认阈值。 | |输入路径 |* HTTP/HTTPS：必须是 LAS 服务可直接访问的公网地址；使用签名 URL 时，有效期应覆盖任务排队和执行过程。地址不能包含用户凭据或 URL fragment。

* TOS：使用 `tos://bucket/key` 格式。TOS Bucket 需与 LAS 服务属于同一主账号、同一地域，并确保 LAS 服务具备目标对象的读取权限。 | ## 输出要求 |细分项 |详细要求 | |---|---| |支持的数据模态 |* 文本（JSON）

Poll 返回业务判定、问题与证据、问题统计和视频元数据。 | |输出路径 |* API 返回：通过 Poll 获取内联质检结果。

* TOS：设置 `output.uri_prefix` 后，可将完整 JSON 报告发布到指定 TOS 前缀。TOS Bucket 需与 LAS 服务属于同一主账号、同一地域，并确保 LAS 服务具备目标目录的写入权限。路径格式为 `tos://bucket/prefix`，实际报告地址以 Poll 返回的 `artifacts[].uri` 为准。 | # 注意与前提 ## 申请开白当前功能处于白名单阶段，使用前需[提交工单](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)。 | |费用 |调用算子前，请先了解 LAS 算子相关费用，详情参见[大模型调用计费](https://www.volcengine.com/docs/6492/1544808)。本算子不调用视觉语言模型。 | |鉴权（API Key） |调用算子前，请先生成 LAS API Key，并建议配置为环境变量，详情参见[获取 API Key 并配置](https://docs.volcengine.com/docs/6492/2191994)。本算子无需传入方舟 API Key。 | |BaseURL |调用算子前，请根据 LAS 服务所在地域获取对应的 Base URL，详情参见[获取 Base URL](https://docs.volcengine.com/docs/6492/2191993)。下文示例仅供参考，实际调用时需替换为对应地域的地址。 | # Rest API 调用 ## Submit ### 接口说明提交具身数据预检异步任务。该算子固定使用 `template_name=video_precheck`，对单路视频执行确定性技术质量检查。 ### 请求参数 **operator_id** string 必选 `示例值: las_embodied_collection_precheck` 算子 ID，固定为 `las_embodied_collection_precheck`。 **operator_version** string 必选 `示例值: v1` 算子版本，固定为 `v1`。 **data** CollectionPrecheckInfo 必选预检参数。 **template_name** string 必选 `示例值: video_precheck` 模板名称，固定为 `video_precheck`。 **assets** list of AssetInput 必选必须且仅提供 `inputs.video_asset_id` 引用的一项 `kind=video` 资产，不得附带其他资产。 **asset_id** string 必选 `示例值: video` 资产 ID，长度 1～128，同一请求内必须唯一。 **kind** string 必选 `示例值: video` 资产类型，本算子固定为 `video`。 **uri** string 必选 `示例值: tos://bucket/input.mp4` 视频地址，支持公网可直接下载的 HTTP/HTTPS 和 `tos://bucket/key`。TOS Bucket 需与 LAS 服务属于同一主账号、同一地域，并确保 LAS 服务具备读取权限。地址必须包含对象键，不得包含用户凭据或 fragment；签名 URL 的有效期应覆盖排队和执行过程。 **inputs** PrecheckInputs 必选预检业务参数。 **video_asset_id** string `Optional` `示例值: video` 视频资产 ID，默认为 `video`，必须引用 `assets` 中 `kind=video` 的资产。 **options** PrecheckOptions `Optional` 检查项、采样和质量策略；省略时使用默认七项检查及默认阈值。 **check_items** list of string `Optional` `示例值: ["video_integrity","video_quality"]` 支持 `video_integrity`、`video_quality`、`video_freeze`、`video_flicker`、`motion_blur`、`camera_shake`、`playback_stutter`。省略或传空数组时执行全部七项。 **sampling_fps** float `Optional` `示例值: 2.0` 质量信号采样频率，必须为正有限数，默认值和上限均为 4 帧/秒。沿完整时间轴最多采样 7200 个质量信号样本；有效频率不高于请求值、4、`7200/视频秒数` 及源帧率，并至少保留一次全片采样机会。只选择 `video_integrity` 时不执行质量采样。 **quality_policy** VideoQualityPolicy `Optional` 视频质量判定阈值。 **decision_mode** string `Optional` `示例值: report_only` 支持 `report_only` 或 `reject_high`，默认 `report_only`。前者将运动模糊、相机抖动和播放卡顿报告为低严重度，后者将这三类问题提升为高严重度并触发 `REJECT`；冻结和闪烁仍为中严重度，完整性、黑白屏和持续噪声的高严重度不受该开关控制。 **min_event_duration_seconds** float `Optional` `示例值: 0.5` 时序候选累计命中时长门槛，范围 0～30 秒，默认 0.5。 **noise_score_threshold** float `Optional` `示例值: 10.0` 普通噪声阈值，大于 0 且不超过 255。 **low_light_luma_threshold** float `Optional` `示例值: 64.0` 低光亮度阈值，范围 0～255。 **low_light_noise_score_threshold** float `Optional` `示例值: 1.0` 低光噪声阈值，大于 0 且不超过 255。 **noise_frame_ratio_threshold** float `Optional` `示例值: 0.8` 噪声样本比例阈值，大于 0 且不超过 1。 **motion_blur_ratio_threshold** float `Optional` `示例值: 0.6` 运动模糊样本比例阈值，大于 0 且不超过 1。 **camera_shake_ratio_threshold** float `Optional` `示例值: 0.35` 相机抖动样本比例阈值，大于 0 且不超过 1。 **playback_stutter_ratio_threshold** float `Optional` `示例值: 0.3` 播放卡顿样本比例阈值，大于 0 且不超过 1。 **motion_blur_laplacian_threshold** float `Optional` `示例值: 35.0` 运动模糊清晰度阈值，范围 0～10000。 **camera_shake_jerk_threshold** float `Optional` `示例值: 0.018` 相邻运动向量变化阈值，大于 0 且不超过 1。 **output** OutputOptions `Optional` 完整 JSON 报告的可选发布位置。 **uri_prefix** string 必选 `示例值: tos://bucket/qc-results` 报告发布前缀，仅支持 `tos://bucket/prefix`。TOS Bucket 需与 LAS 服务属于同一主账号、同一地域，并确保 LAS 服务具备目标目录的写入权限。路径必须包含非空对象前缀，且不能包含用户凭据、query 或 fragment；报告地址以 Poll 返回的 `artifacts[].uri` 为准。 ### 返回数据 **metadata** metadata 必选异步任务元信息。 **task_id** string 必选 `示例值: task-xxx` 异步任务 ID，用于 Poll 查询。 **task_status** string 必选 `示例值: PENDING` 任务状态。提交成功时为 `PENDING`。 **business_code** string 必选 `示例值: 0` 业务码，提交成功时通常为字符串 `"0"`。 **error_msg** string 必选错误信息，提交成功时为空字符串。 ### 请求示例 ```bash 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_embodied_collection_precheck", "operator_version": "v1", "data": { "template_name": "video_precheck", "assets": [{"asset_id": "video", "kind": "video", "uri": "tos://your-bucket/embodied-operation.mp4"}], "inputs": { "video_asset_id": "video", "options": {"quality_policy": {"decision_mode": "report_only"}} } } }' ``` ## Poll ### 接口说明查询具身数据预检任务状态和最终结果。仅当 `metadata.task_status=COMPLETED` 且 `metadata.business_code="0"` 时读取 `data.result`；`data.result.verdict` 是独立的业务质检结论。排队、执行中、失败、过期、取消或查询错误时，`data` 为空或省略。 ### 请求参数 |名称 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |operator_id |string |是 |las_embodied_collection_precheck |算子 ID | |operator_version |string |是 |v1 |算子版本 | |task_id |string |是 |task\-xxx |Submit 返回的任务 ID | ### 返回数据 **metadata** metadata 必选平台任务状态和错误信息。 **task_id** string 必选 `示例值: task-xxx` 异步任务 ID。 **task_status** string 必选 `示例值: COMPLETED` `PENDING` 表示排队，`RUNNING` 表示执行中，`COMPLETED` 表示执行完成，此外还可能为 `FAILED`、`EXPIRED`、`CANCELLED` 或 `UNKNOWN`。仅 `COMPLETED` 且 `business_code` 为字符串 `"0"` 时读取 `data`。 **submit_time** string `Optional` `示例值: 2026-10-19T10:00:00+08:00` 任务提交时间，ISO 8601 格式。 **end_time** string `Optional` `示例值: 2026-10-19T10:01:00+08:00` 任务结束时间，ISO 8601 格式；未结束或时间不可用时省略。 **business_code** string 必选 `示例值: 0` 字符串 `"0"` 只表示本次查询或执行无错误，不表示任务已完成或业务质检通过；非零时读取 `error_msg`。 **error_msg** string `Optional` 安全处理后的错误信息。 **data** CollectionPrecheckResult `Optional` 仅 `COMPLETED` 且 `business_code="0"` 并有有效结果时返回；排队、执行中、失败、过期、取消或查询错误时为空或省略。 **template_name** string 必选 `示例值: video_precheck` 实际执行的模板，固定为 `video_precheck`。 **execution_status** string 必选 `示例值: completed` `completed` 或 `degraded`。报告交付失败但内联结果可用时为 `degraded`。 **result** AuditResult 必选预检业务结果。 **audit_id** string 必选 `示例值: audit-xxx` 审核实例 ID。 **audit_template** string 必选 `示例值: video_precheck` 固定为 `video_precheck`。 **annotation_format** string 必选 `示例值: auto` 预检未提供标注时为 `auto`。 **verdict** string 必选 `示例值: PASS` `PASS` 或 `REJECT`；任一 `high` 问题触发 `REJECT`，低、中严重度问题可策略放行。 **decision_basis** string 必选 `示例值: confirmed_consistent` `confirmed_consistent`、`confirmed_violation` 或 `no_confirmed_violation`。 **evidence_status** string 必选 `示例值: sufficient` `sufficient` 或 `insufficient`；证据不足的 `PASS` 仅表示未触发阻断，不表示素材无缺陷。 **summary** string 必选 `示例值: 质检通过，未发现违反审核要求的问题。` 统一中文业务摘要。 **issues** list of AuditIssue 必选技术质量问题列表。每项包含 `issue_type`、`issue_code`、`severity`、`reason`，并可包含 `target_id`、`expected`、`observed` 和 `evidence`。`evidence` 为 `AuditEvidence` 列表，时间单位均为秒。 **metrics** PrecheckMetrics 必选包含 `issue_count` 和 `rejected_issue_count`，后者统计 `severity=high` 的问题数。 **business_result** object 必选预检不支持自定义 `output_spec`，正常为空对象。 **usage** ReportDeliveryUsage 必选正常为空对象；报告交付失败时包含 `internal_output_status`、`internal_output_reason`、`internal_output_message` 和 `internal_output_retryable`。交付失败不会安排后台补传，重新 Submit 会重新执行任务。 **video_metadata** VideoMetadata `Optional` 可包含 `duration`、`resolution`、`fps`、`codec_name` 和 `rotation`；不可获得时相应字段省略。 **artifacts** list of Artifact 必选已成功交付的报告产物；未配置输出位置时为空数组，交付失败不返回未交付地址。每项包含 `artifact_id`、`kind`、`media_type`、`purpose` 和 `uri`。 ### 请求示例 ```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_embodied_collection_precheck", "operator_version": "v1", "task_id": "task-xxx" }' ``` ### 返回示例 ```json { "metadata": {"task_id": "task-xxx", "task_status": "COMPLETED", "business_code": "0", "error_msg": ""}, "data": { "template_name": "video_precheck", "execution_status": "completed", "result": { "verdict": "PASS", "decision_basis": "confirmed_consistent", "evidence_status": "sufficient", "summary": "质检通过，未发现违反审核要求的问题。", "issues": [], "metrics": {"issue_count": 0, "rejected_issue_count": 0}, "video_metadata": {"duration": 10.0, "resolution": "960x540", "fps": 30.0, "codec_name": "h264"} }, "artifacts": [] } } ``` ### 错误码 |HttpStatusCode |错误码 |错误信息 |描述 | |---|---|---|---| |400 |Parameter.Invalid |The parameter is invalid. |模板、资产、URI、输入字段、检查项或质量阈值不合法。 | |400 |Task.NotFound |The task is not found. |任务 ID 为空或不存在。 | |400 |QC_INPUT_TOO_LARGE |输入视频大小超过质检限制。 |视频文件超过 1 GiB（1,073,741,824 字节）。 | |400 |QC_VIDEO_TOO_LONG |输入视频时长超过质检限制。 |视频时长超过 1 小时。 | |401 |Authorization.Missing |Missing Authorization. |缺少 LAS 鉴权信息。 | |401 |ApiKey.InValid |The api key is invalid. |LAS API Key 不合法。 | |500 |QC_VIDEO_SCAN_FAILED |视频解析失败，质检未能完成。 |视频无法解码或质量信号扫描失败。 | |500 |DEADLINE_EXCEEDED |质检执行超时，请稍后重试。 |任务超过执行总预算。 | |500 |InternalError |Internal error. |任务上下文保存、凭证获取、队列提交、结果解析或查询失败。 |

AI 数据湖服务