byted-airesearch-videoeval

Byted Airesearch Videoeval

使用此技能提交和查询耗时较长的素材评估任务。

适用场景

当用户想要执行以下操作时，使用此技能：

• 评估视频素材或创意资产
• 提交素材评估任务并获取任务标识符
• 稍后检查现有评估任务的状态
• 获取之前创建的评估任务的最终详情或结果

不要将此技能用于通用视频上传请求。

当前工作流

1. 在开始任何上传之前，验证完整的输入批次。
2. 上传本地视频文件并记录返回的 attachment_id 值。
3. 使用上传所得的附件 ID 创建任务。
4. 创建任务后立即返回成功。
5. 如果用户想查看进度或结果，请让其稍后查询任务列表或任务详情。

此工作流有意采用非阻塞方式。创建任务后不要自动轮询。

强制行为

• 不要将上传 API 作为独立的面向用户功能公开。
• 对于“上传这个视频”“存储此文件”或“发送这个视频”等通用请求，不要触发此技能。
• 只有当用户明确表示要创建新的素材评估任务时，才调用上传 API。
• 创建新任务时，优先使用 scripts/submit_evaluation_task.py，以便在同一受控流程中完成验证、上传和任务创建。
• 将 scripts/upload_video.py 视为编排流程使用的内部辅助脚本，而不是主要的用户入口。除非使用内部编排标记调用，否则该脚本会拒绝直接使用。

提交多个文件时，使用编排入口点，以便在开始首次上传前验证整个批次。

提交限制

• 单个任务最多可包含 10 个视频。
• 未启用的用户在滚动 24 小时内最多可免费提交 10 个视频。
• 新任务的视频数量会计入过去 24 小时内已提交的视频数量。如果总数超过 10，服务会拒绝该任务，并要求用户联系 Volcengine 销售以开通访问权限。
• 已启用的用户不受此滚动 24 小时免费额度限制。
• 额度按每个任务实际提交的视频数量计算，不去重。
• 过去 24 小时内创建的任何任务都会计入滚动额度，包括正在运行的任务。
• 基于登录和基于 API key 的访问共用同一额度池。
• 技能会在开始上传前在本地执行单任务限制。滚动 24 小时额度由服务执行限制；技能应清楚说明服务拒绝请求的原因。

身份验证

当前 API 使用 API key 身份验证。

此技能发送的所有 API 请求都必须包含以下标头：

• x-product-version: 20
• Authorization: bearer {API_KEY}

首选输入方式：

• --api-key "<api-key>"
• BYTED_AIRESEARCH_VIDEOEVAL_API_KEY

如果没有可用的 API key，请让用户前往以下地址创建或查看：

• https://console.volcengine.com/datatester/ai-research/audience/list?tab=apikey

然后让用户提供 API key，再调用 API。

如果缺少 API key，脚本必须立即失败，并清楚提示用户前往上述 API key 页面。

已知 API 覆盖范围

上传附件

• 端点：POST https://console.volcengine.com/datatester/compass/api/v3/survey/attachment
• 请求：multipart/form-data
• 文件字段：file
• 上传限制：
  • 每个上传请求恰好包含一个视频文件
  • 每个视频不得超过 50MB
  • 文件格式必须为 mp4
  • MIME 类型必须为 video/mp4
• 输出映射：
  • 保留原始附件负载
  • 将附件对象的 id 字段映射为 attachment_id

upload_video.py 脚本是创建任务工作流的内部辅助工具，不是主要的面向用户入口。

创建任务

• 端点：POST https://console.volcengine.com/datatester/compass/api/v3/survey/task
• 固定请求字段：
  • form_id: 0
  • agent_id: 125
  • audience_id: 3664529
• 当前公开的可选请求字段：
  • prompt
  • language
  • is_typical_user_enabled
  • typical_user_count
  • typical_user_selection_mode
  • is_report_enabled
  • attachment_ids
• 创建约束：
  • 单次任务提交最多可包含 10 个视频
  • 每个请求中的 attachment_ids 最多包含 10 项

创建步骤应将上传的 attachment_id 作为仅含一个元素的 attachment_ids 数组发送，除非明确提供了多个附件 ID。

列表和详情

任务详情已接通，可直接查询现有任务：

• 端点：GET https://console.volcengine.com/datatester/compass/api/v3/survey/task/{id}
• 当前身份验证：API 密钥 Bearer 令牌
• 输出映射：
  • 将任务对象的 id 字段映射为 task_id
  • 将任务对象的 status 字段映射为 task_status
  • 解析 task.detail
  • 仅保留 key == video_structured_result 且 sub_tab != null 的项目
  • 提供精简的 summary 区块，供下游 Agent 使用

任务列表已接通，可直接查询现有任务：

• 端点：GET https://console.volcengine.com/datatester/compass/api/v3/survey/task
• 当前身份验证：API 密钥 Bearer 令牌
• 当前固定查询参数：
  • page=1
  • page_size=100
  • agent_id=125
• 输出映射：
  • 将每个任务项映射为 task_id、name、status、created_at、updated_at
  • 在 data.page 中保留分页信息

命令

# Validate a whole batch before upload, then upload all files and create the task
python scripts/submit_evaluation_task.py \
  --file /path/to/video-1.mp4 \
  --file /path/to/video-2.mp4 \
  --api-key "<api-key>"

# Single-video create flow
python scripts/submit_evaluation_task.py \
  --file /path/to/video.mp4 \
  --prompt "Evaluate this material for audience fit and content quality." \
  --api-key "<api-key>"

# Query task list later
python scripts/list_evaluation_tasks.py

# Query task detail later
python scripts/get_evaluation_task_detail.py --task-id 12345

响应处理

所有脚本都会向 stdout 输出 JSON，并使用相同的顶层封装：

• status
• message
• request_id
• data
• error

重要的规范化字段：

• 提交任务：data.task_id、data.task_status、data.submitted_video_count
• 列表：data.items
• 详情：data.detail、data.summary

最终答复规则

• 将详情端点返回的结构化 JSON 作为内部事实来源。
• 使用人类可读的自然语言呈现最终答复。
• 任务完成后，优先使用简洁的报告式答复，而不是原始数据转储。
• 不要向用户转储原始 JSON。
• 不要公开 video_eval、video_user_report、distribution、field_desc 等内部字段名或类似的面向实现的键。
• 对任务列表响应也遵循相同规则：将列表结果用作内部数据来源，以自然语言摘要呈现结果，而不是原始字段。
• 对于任务列表答复，可以在人类可读的文本中包含任务 ID、任务名称、状态、创建时间和更新时间，因为这些字段有助于用户选择任务以查询后续详情。
• 存在多个视频时，分别进行摘要。
• 对于已完成任务的详情结果，优先采用易读的报告结构，例如：先给出任务结论，再为每个视频提供一个简短章节，最后在源数据支持的情况下给出总体建议。
• 如果任务尚未完成，不要捏造报告。应明确说明当前状态，并请用户稍后再查看。
• 只有用户明确要求原始结果时，才提供原始结构化数据。

实用指南

• 对于新的提交，请使用编排流程，而不是将上传作为单独步骤展示给用户。
• 上传前验证本地文件。对于非 MP4 文件、MIME 类型不是 video/mp4 的文件，或大于 50MB 的文件，直接给出明确且可执行的错误消息。
• 调用 API 前验证任务创建输入。对于包含超过 10 个附件 ID 的请求，直接给出明确且可执行的错误消息。
• 对于多视频提交流程，在开始任何上传前验证完整的批次大小。如果批次包含超过 10 个文件，请立即失败，不要上传任何文件。
• 如果服务因超出滚动 24 小时免费额度而拒绝创建任务，请使用以下标准中文措辞向用户显示消息：免费版用户每24小时最多提交10个评估视频，如需购买请联系火山引擎销售人员
• 创建成功后，告知用户任务已成功提交，之后可以查看。
• 用户想浏览或查找历史任务时，使用任务列表。
• 用户已知道任务 ID 并想查看最终结果时，使用任务详情。