`POST https://mediakit.cn-beijing.volces.com/api/v1/tools/evaluate-aigc-video-quality` 本 API 用于提交一个异步的 AIGC 视频生成质量评估任务，面向 AIGC 视频规模化生产场景，对待检视频（可选结合参考图）按需检查参考信息一致性、世界合理性、内容持续性、视觉保真度等质量问题，自动定位异常时间区间、输出问题说明与典型问题帧，帮助您快速完成采用、复核或重新生成决策。 > **说明** * > 公测说明：AIGC 视频生成质量评估工具当前处于公测阶段，预计 2026 年 11 月正式发布。公测期间，接口与能力可能存在微调，请以最新文档为准。 * > 如需了解完整的使用流程和应用示例，请参阅 [AIGC 视频生成质量评估](https://docs.volcengine.com/docs/6448/2722886)。 ## 前提条件 * **开通火山方舟大模型服务**：AIGC 视频生成质量评估工具依赖火山方舟（Ark）视觉大模型完成评估。请前往[火山方舟控制台](https://console.volcengine.com/ark)，确认本工具所需的大模型（如 Doubao 系列）已开通且可用。模型能力会影响检测效果，推荐使用 `doubao-seed` 系列中最新的 pro 模型，例如 `doubao-seed-2-1-pro-260628`。 * **完成跨服务授权**：首次使用 AIGC 视频生成质量评估工具前，请前往 AI MediaKit 控制台的[授权管理页面](https://console.volcengine.com/imp/ai-mediakit/settings?tab=authorization)，授权 AI MediaKit 访问您的 **ARK 火山方舟**资源，否则任务将因权限不足而失败。 ## 请求参数 ### Header 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`Authorization` |String |是 |`Bearer {Your_API_Key}` |格式为 `Bearer {Your_API_Key}`。请参考[基础概念及准备工作](https://docs.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`video_url` |String |是 |`https://example.com/your_aigc_video.mp4` |待评估的视频 URL。

* 视频来源：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、来源于火山引擎视频点播 (`vod://`) 和火山引擎对象存储 (`tos://`) 四种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://docs.volcengine.com/docs/6448/2536893)。

* 支持格式：`mp4`、`flv`、`ts`、`avi`、`mov`、`wmv`、`mkv` 等主流视频格式。

* 视频时长：单个视频时长不超过 3 分钟。 | |`modules` |Array |否 |`["world_plausibility", "visual_fidelity"]` |启用的检查模块列表，按场景自由组合，元素不可重复。不传或传空数组表示执行全部适用模块，但 `reference_consistency` 仍需在提供 `reference_images` 时才会启用。可选值：

* `reference_consistency`：参考信息一致性。对比视频中的元素与提供的参考图是否一致。**启用该模块时必须提供 ** **`reference_images`**。

* `world_plausibility`：世界合理性。检查画面是否符合物理与运动规律（如重力、碰撞、穿模、惯性等）。

* `content_continuity`：内容持续性。检查人物、商品等实体在时间维度上是否保持一致。

* `visual_fidelity`：视觉保真度。检查人体、物体、文字的结构与自然度。 | |`reference_images` |Array |否 |`-` |参考图列表，仅在启用 `reference_consistency` 模块时有效且必填。数组长度为 1~6（最少 1 张，最多 6 张）。每张图需标注其类型，用于对比视频中对应元素的一致性。详见下文 [Reference image 对象](https://docs.volcengine.com/docs/6448/2722887#reference-image-%E5%AF%B9%E8%B1%A1)。 | |`prefer_models` |Array |否 |`["doubao-seed-2-1-pro-260628"]` |优先使用的模型 ID (Model ID) 列表，当前必须传入且最多传入 1 项。模型能力会影响检测效果，推荐使用 `doubao-seed` 系列中最新的 pro 模型，例如 `doubao-seed-2-1-pro-260628`。您可以在[火山方舟控制台在线推理页面](https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint)查看您账号下可用的模型 ID。 | |`output_language` |String |否 |`zh-CN` |问题描述（即任务结果中的 `issues[].description` 字段）的输出语言。不传时默认使用中文（`zh-CN`）。可选值：`zh-CN`、`en-US`。 | |`client_token` |String |否 |`your_unique_request_id_135` |用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考[幂等性控制](https://docs.volcengine.com/docs/6448/2300661#672adae7)。 | |`callback_args` |String |否 |`your_custom_callback_args` |自定义回调参数。您提供的内容将在任务完成时，通过[事件回调](https://docs.volcengine.com/docs/6448/2288701)原样返回，方便您关联业务。字段长度最大为 512 字节。 | |`callback_url` |String |否 |`https://example.com/callback` |用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考[事件回调](https://docs.volcengine.com/docs/6448/2288701)了解回调接收机制和回调消息结构。 | |`queue_id` |String |否 |`q00a9731598092652e4a95292434198` |任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考[按项目或 API Key 分账](https://docs.volcengine.com/docs/6448/2519520)。 | #### Reference image 对象仅在启用 `reference_consistency` 模块时有效且必填。`reference_images` 数组中的每个元素结构如下： |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |`image_url` |String |是 |`https://example.com/character_ref.png` |参考图 URL。支持公网可访问的图片直链，或本地上传 (`mediakit://`)、火山引擎对象存储 (`tos://`) 平台资源链接。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://docs.volcengine.com/docs/6448/2536893)。 | |`category` |String |是 |`character` |参考图类型，用于标注该图代表的元素。可选值：

* `character`：人物。

* `clothing`：服饰。

* `product`：商品。

* `scene`：场景。

* `prop`：道具。

* `other`：其他（仅在无更明确类型时使用）。 | ## 请求示例 ### 示例 1：执行全部适用模块不传 `modules`，执行全部适用模块。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/evaluate-aigc-video-quality' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_aigc_video.mp4", "prefer_models": ["doubao-seed-2-1-pro-260628"] }' ``` ### 示例 2：结合参考图检查参考信息一致性启用 `reference_consistency` 模块时，必须提供 `reference_images`。以下示例结合商品参考图，检查参考信息一致性、世界合理性与内容持续性。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/evaluate-aigc-video-quality' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://example.com/your_aigc_video.mp4", "modules": ["reference_consistency", "world_plausibility", "content_continuity"], "reference_images": [ { "image_url": "https://example.com/product_ref.png", "category": "product" } ], "prefer_models": ["doubao-seed-2-1-pro-260628"] }' ``` ## 响应说明调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。 ### 响应参数 |参数 |类型 |描述 | |---|---|---| |`success` |Boolean |任务是否成功提交。

* `true`：任务已成功提交到后台处理队列。

* `false`：请求存在错误，任务提交失败。请检查 `error` 字段以获取详细信息。 | |`task_id` |String |任务的唯一标识符。仅在 `success` 为 `true` 时返回有效值。您可以使用此 ID 来查询任务状态和结果。 | |`request_id` |String |本次 API 请求的唯一标识符，可用于问题排查。 | |`error` |Object |错误详情对象，仅在 `success` 为 `false` 时返回。详见下文 [Error 对象](https://docs.volcengine.com/docs/6448/2722887#error-%E5%AF%B9%E8%B1%A1)。 | #### Error 对象 |参数 |类型 |描述 | |---|---|---| |`code` |String |具体的错误码。关于各错误码的详细信息，请参阅[错误码](https://docs.volcengine.com/docs/6448/2300662)。 | |`type` |String |错误的宏观类型。例如 `BadRequest`。 | |`message` |String |对错误的详细描述，可用于开发调试。 | |`param` |String |（可选）指出导致错误的具体参数。 | ### 响应示例 #### 成功响应 ```JSON { "success": true, "task_id": "amk-tool-evaluate-aigc-video-quality-123456789", "request_id": "20261012194945ABCDEF0123456789" } ``` #### 失败响应 ```JSON { "success": false, "task_id": "", "request_id": "20261012195005XYZW0123456789", "error": { "code": "InvalidParameter", "message": "reference_images must contain at least one non-empty image_url when modules contains reference_consistency", "param": "reference_images", "type": "BadRequest" } } ``` ## 异步任务结果 AIGC 视频生成质量评估是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果： * **方法一（轮询查询）：** 使用提交任务时获取的 `task_id`，定期调用[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532)，直到 `status` 字段变为 `completed` 或 `failed`。 * **方法二（事件回调）：** 在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 `callback_url` 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅[事件回调](https://docs.volcengine.com/docs/6448/2288701)。当任务成功完成后，您获取到的任务信息中的 `result` 字段将包含以下内容。 |参数 |类型 |示例 |描述 | |---|---|---|---| |`issues` |Array |见下方示例 |问题明细列表。未检查到问题时为空数组 `[]`。每个元素代表一个检出的问题，结构见下文 [Issue 对象](https://docs.volcengine.com/docs/6448/2722887#issue-%E5%AF%B9%E8%B1%A1)。 | |`duration` |Number |`12.5` |视频时长，单位为秒，用于计量计费。 | #### Issue 对象 |参数 |类型 |示例 |描述 | |---|---|---|---| |`module` |String |`world_plausibility` |问题所属检测模块，取值为 `reference_consistency`、`world_plausibility`、`content_continuity`、`visual_fidelity` 之一。 | |`type` |String |`gravity_plausibility` |具体问题类型（如 `gravity_plausibility`、`character_identity_consistency` 等），辅助问题统计。 | |`description` |String |`第 3~5 秒角色手臂出现穿模` |人类可读的问题描述。 | |`time_range` |Array |`[[3.2, 5.8], [12.0, 14.5]]` |问题出现的时间区间列表（单位：秒），供播放器定位跳转。为二维数组，每个元素是一个 `[起, 止]` 区间，支持返回多个时间区间。 | |`annotated_frames` |Array |`["https://.../frame_1.jpg", "https://.../frame_2.jpg"]` |典型问题帧的标注图片地址列表（选取最典型的一帧或多帧；实体持续性类问题至少返回 2 帧）。 | 以下是一个检出结果时的完整任务信息示例（对应[示例 2：结合参考图检查参考信息一致性](https://docs.volcengine.com/docs/6448/2722887#%E7%A4%BA%E4%BE%8B-2%EF%BC%9A%E7%BB%93%E5%90%88%E5%8F%82%E8%80%83%E5%9B%BE%E6%A3%80%E6%9F%A5%E5%8F%82%E8%80%83%E4%BF%A1%E6%81%AF%E4%B8%80%E8%87%B4%E6%80%A7)，启用了 `reference_consistency`、`world_plausibility` 与 `content_continuity`，并提供了 `product` 类参考图）： ```JSON { "success": true, "task_id": "amk-tool-evaluate-aigc-video-quality-123456789", "request_id": "20261012194945ABCDEF0123456789", "status": "completed", "result": { "duration": 15.134, "issues": [ { "module": "reference_consistency", "type": "reference_gate", "description": "在 3000ms、4000ms、5000ms 对应的视频帧中均可看到目标参考商品，与参考图中的商品外观一致，无可见明显不匹配。", "time_range": [[0, 0]], "annotated_frames": [ "https://example.volcvideo.com/evaluation/xxxxxxxx/frame_01.jpg?preview=1&auth_key=***", "https://example.volcvideo.com/evaluation/xxxxxxxx/frame_02.jpg?preview=1&auth_key=***", "https://example.volcvideo.com/evaluation/xxxxxxxx/frame_03.jpg?preview=1&auth_key=***" ] }, { "module": "world_plausibility", "type": "motion_rationality", "description": "人物动作及人与物品的交互过程连续合理，逻辑连贯：依次完成指向地面介绍地坪问题、取出地坪漆桶并开启桶盖、使用滚筒涂刷地面、展示涂刷完成的地坪效果等一系列动作，动作衔接符合现实行为逻辑，无不合理的运动断层。", "time_range": [[0, 15]], "annotated_frames": [ "https://example.volcvideo.com/evaluation/xxxxxxxx/frame_04.jpg?preview=1&auth_key=***", "https://example.volcvideo.com/evaluation/xxxxxxxx/frame_05.jpg?preview=1&auth_key=***" ] }, { "module": "content_continuity", "type": "product_consistency", "description": "0~15 秒内人物所穿的工装外观全程保持一致，展示的地坪漆从产品包装展示、开盖到涂刷后的成品效果连贯统一，无外观异常变化。", "time_range": [[0, 15]], "annotated_frames": [ "https://example.volcvideo.com/evaluation/xxxxxxxx/frame_06.jpg?preview=1&auth_key=***", "https://example.volcvideo.com/evaluation/xxxxxxxx/frame_07.jpg?preview=1&auth_key=***" ] } ] }, "expires_at": 1791892453, "created_at": 1791805785, "finished_at": 1791806054 } ```