返回技能市场
内容创作 安全

阿里云百炼-视频理解

@aliyun/alibabacloud-bailian-videoanalysis

阿里云百炼-视频理解，基于先进通义多模态大模型。可生成视频标题、大纲、总结、分镜信息。可通过自定义prompt，实现标签抽取、时间线总结等。

云Skills门户 热度 213v0.0.2

百炼视频分析

此 skill 基于阿里云百炼视频分析轻应用提供视频分析功能。它通过百炼（QuanMiaoLightApp） API 实现视频智能理解，包括镜头分析、ASR 转写、标题生成、字幕提取和思维导图生成。

架构： CLI (Credential Chain) + OSS (File Storage) + Bailian Workspace + Quanmiao Video Analysis Service + Python SDK Scripts

---

输出语言策略

检测优先级： 用户输入语言 → 环境语言 → 默认：中文

适用范围： 所有面向用户的消息、摘要、错误说明和交互式提示。

保持原始语言： 代码片段、API 响应、文件路径、技术标识符和 HTTP 状态码。

---

安装

1. Python 依赖项

python -m pip install -r scripts/requirements.txt
# On some systems, use pyhon3 instead of python

2. 阿里云 CLI

预检查：阿里云 CLI 必须 >= 3.3.1
运行 aliyun version，验证版本是否 >= 3.3.1。如果尚未安装或版本过低，
请参阅 references/cli-installation-guide.md 获取安装说明。
然后 [必须] 运行 aliyun configure set --auto-plugin-install true，以启用插件自动安装。
阿里云 CLI 的 AI-Mode 配置
在此 skill 中使用阿里云 CLI 时，必须配置 AI-Mode 设置：
```bash
# Enable AI-Mode (required before using CLI commands)
aliyun configure ai-mode enable
# Set User-Agent for tracking (required)
aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis
# Update plugins to latest versions (recommended)
aliyun plugin update
```
注意： 完成任务后，可以禁用 AI-Mode：
```bash
aliyun configure ai-mode disable
```

3. 重要前提条件：开通百炼和视频分析服务

使用此 skill 前，必须先在阿里云百炼控制台中开通视频分析服务！

  1. 访问 百炼 Video_Analysis 页面
  2. 单击 “付费开通” 按钮
  3. 确认开通并等待服务生效（通常需要 1-2 分钟）

4. 重要前提条件：引导用户在阿里云访问控制和百炼中授予权限

使用此 skill 前，必须为之前配置的 AK 授予以下权限，否则调用将失败，并可能产生 403 错误

1) RAM 权限授予

有关所需 RAM 权限的完整列表和授权说明，请参阅 [references/ram-policies.md](references/ram-policies.md)。

[必须] 权限失败处理： 在执行过程中的任何阶段，如果任何命令或 API 调用因权限错误而失败，必须遵循以下流程：
1. 读取 references/ram-policies.md，获取此 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose skill 引导用户申请必要权限
3. 暂停并等待，直到用户确认已授予所需权限

2) 百炼工作空间权限授予

  1. 访问 阿里云百炼权限管理
  2. 如果与 AK 对应的 RAM 用户不存在，请单击页面右上角的 “添加用户”，选择对应的 RAM 用户，然后单击确认进行添加。
  3. 配置后需要等待 30s 才能生效，请耐心等待片刻。

---

身份认证

预检查：必须具备阿里云凭证
安全规则：
- 严禁读取、回显或打印 AK/SK 的值（例如，严禁执行 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
- 严禁要求用户直接在对话或命令行中输入 AK/SK
- 严禁通过 aliyun configure set 设置明文凭证值
- 只能使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否存在有效的配置文件（AK、STS 或 OAuth 身份）。
如果不存在有效的配置文件，请在此停止。
1. 从 阿里云控制台 获取凭证
2. 在本次会话之外配置凭证（在终端中通过 aliyun configure 配置，或在 shell 配置文件中通过环境变量配置）
3. 当 aliyun configure list 显示有效的配置文件后，返回并重新运行

---

参数确认

重要：参数确认——在执行任何命令或 API 调用之前，
确认用户提供或可自定义的参数（视频源、OSS 存储桶、OSS 对象键）。
系统自动解析的参数（workspace_id、默认 OSS 存储桶）无需
要求明确确认，除非用户希望覆盖这些参数。

| 参数 | 类型 | 描述 | 默认值 / 获取方式 | |------------------|---------------|-------------------------------------------|------------------------------------------------------------------------------------------| | video_source | 必填 | 本地文件路径或可下载的视频 URL | 不适用（必须由用户提供） | | workspace_id | 自动解析 | 百炼工作空间 ID | 自动检测（用户可覆盖） | | ossBucket | 可选 | 用于上传文件的 OSS 存储桶名称 | 自动检测第一个可用的存储桶；用户也可指定（例如 --ossBucket my-bucket） | | ossObjectKey | 可选 | 上传文件的 OSS 对象键 | /temp/quanmiao/YYYYMMDD/filename | | expireSeconds | 可选 | 临时 URL 的过期时间（秒） | 14400（4 小时） |

确认工作流：

  1. 优先自动检测：skill 会尽可能自动检测 workspace_id 和 ossBucket
  2. 用户覆盖：如果用户希望指定自定义值，请在使用前确认
  3. 本地文件与 URL：确认用户提供的是本地文件路径还是公共 URL

---

核心工作流

⚠️ 关键要求：强制使用云 API——此 skill 必须使用百炼（QuanMiaoLightApp）API 进行视频分析。严禁使用本地工具（ffmpeg、whisper、OpenCV、ffprobe、mediainfo 等）。如果因凭证或权限问题导致 API 调用失败，请遵循权限失败处理流程——不得回退到本地分析。

步骤 1：环境检查

运行 python scripts/check_env.py 以验证：

  • 已安装 Python 软件包
  • 已通过默认凭证链配置凭证

如果 check_env.py 失败或返回 {"ready": false}：

  • 缺少软件包 → 运行 python -m pip install -r scripts/requirements.txt
  • 凭证缺失或无效 → 遵循权限失败处理流程：
  1. 阅读 references/ram-policies.md 以获取所需权限
  2. 使用 ram-permission-diagnose skill 引导用户申请权限
  3. 等待用户确认后再继续
  4. 不得继续使用本地分析工具

预期输出： {"ready": true} 表示环境已正确配置。

步骤 2：获取工作空间 ID

不要预先向用户询问 workspace_id。 始终先自动获取可用的工作空间：

aliyun modelstudio list-workspaces --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

工作空间选择逻辑：

  • 返回一个工作空间 → 直接使用，无需提示用户
  • 返回多个工作空间 → 显示编号列表，然后按以下方式处理：
  1. 默认行为：自动使用列表中的第一个工作空间，以避免不必要的交互
  2. 用户明确要求选择：如果用户说“让我选择工作空间”、“显示工作空间列表”或类似内容，则展示完整列表并让用户选择一个
  • 未返回工作空间 → 告知用户当前没有可用的百炼工作空间，并引导用户前往 百炼控制台 创建
  • 记录用户选择并保存在会话中，以避免重复询问

步骤 3：将文件（video_source）上传到 OSS

根据“输入资源验证”中的输入资源类型：

情况 A：用户提供了可下载的 URL → 验证 URL 可访问性：使用适用于当前 OS 的方法测试该 URL 是否可下载 → 跳过此步骤。在步骤 4 中，将 video_source 用作 file_url。

情况 B：用户提供了本地文件路径 → 自动检测 OSS 存储桶、将本地文件上传到 OSS，并获取临时 URL（file_url），供步骤 4 使用：

  • （1）自动检测或使用用户指定的 OSS 存储桶：
  • 如果用户指定 --ossBucket <bucket_name>，则尝试使用该存储桶
  • 如果指定的存储桶返回 403 AccessDenied 或 BucketAlreadyExists：不得自动切换到其他存储桶，而应：
  1. 告知用户无法访问指定的存储桶
  2. 遵循 RAM 策略章节中的权限失败处理流程
  3. 引导用户授予 OSS 存储桶访问权限，或指定其拥有的其他存储桶
  4. 等待用户确认后再继续
  • 如果未指定存储桶，则自动检测第一个可用的存储桶
aliyun ossutil ls --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis
  • （2）将文件上传到 OSS：为上传的文件生成唯一对象键（oss_object_key）。

重要提示——上传路径限制：

  • 默认路径：必须使用 /temp/quanmiao/YYYYMMDD/filename 格式（根据当前日期自动生成）
  • 自定义路径：仅当用户明确指定自定义 oss_object_key 时才可使用；否则始终使用默认路径
  • 安全规则：除非用户明确要求，否则严禁将文件上传到 /temp/quanmiao/ 前缀之外
aliyun ossutil cp <video_source> oss://{oss_bucket}/{oss_object_key} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region {oss_region}
  • （3）生成临时 URL：使用 ossutil sign 命令为上传的文件生成临时 URL。
  • --expireSeconds：默认为 14400s（4 小时），如需使用其他值，请确认
aliyun ossutil sign oss://{oss_bucket}/{oss_object_key} --expires-duration {expire_seconds} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region {oss_region}
  • (4) 验证 URL 可访问性：使用适合您的 OS 的方法测试生成的 URL 是否可下载
  • 注意：验证时优先使用 GET 请求，而非 HEAD 请求，因为某些 OSS 签名版本可能会拒绝 HEAD 请求。

推荐的 URL 可下载性验证方法：

  • macOS/Linux：curl -L --connect-timeout 10 --max-time 30 -o /dev/null -w "%{http_code}" <file_url>（返回 HTTP 状态码）
  • Windows: Invoke-WebRequest -Uri <file_url> -Method Head -TimeoutSec 30 (PowerShell)

验证标准：

  • HTTP 200 → URL 有效且可访问，继续执行步骤 4
  • HTTP 403/404 → URL 已过期或无效，请使用 ossutil sign 重新生成
  • 其他错误 → 检查网络或 OSS 权限

步骤 4：提交视频分析任务

⚠️ 强制要求调用 API——必须在 QuanMiaoLightApp 产品（版本 2024-08-01）上调用 SubmitVideoAnalysisTask。不得使用 videorecog、Mts 或任何其他产品。不得尝试本地分析。
API 选择检查清单——调用前请验证：
- ✅ 产品：QuanMiaoLightApp（不得使用 videorecog，也不得使用 Mts）
- ✅ 版本：2024-08-01
- ✅ 操作：SubmitVideoAnalysisTask
- ✅ 参数：workspace_id、file_url
python scripts/quanmiao_submit_videoAnalysis_task.py --workspace_id <workspace_id> --file_url <file_url>

需要确认的参数：

  • --workspace_id：来自步骤 2（需与用户确认）
  • --file_url：来自步骤 3 的上传结果或用户提供的 URL（需确认其有效性）

错误处理：

  • 如果 API 返回 401 InvalidApiKey 或 403 AccessDenied：停止，并遵循权限失败处理流程
  • 不得尝试改用其他 APIs 或本地工具
  • 告知用户：“视频分析需要激活百炼服务并配置正确的 RAM 权限。请按照权限授予指南操作。”

返回 task_id，供轮询使用。

步骤 5：轮询任务结果

⚠️ 强制要求调用 API——必须轮询 QuanMiaoLightApp 产品（版本 2024-08-01）上的 GetVideoAnalysisTask，直至状态为 SUCCESSED。不得使用本地工具或根据文件名推断生成摘要。

视频分析是异步执行的。轮询直至完成：

任务状态： PENDING → RUNNING → SUCCESSED | FAILED | CANCELED

变量：

  • result_json_path: ~/.quanmiao/videoanalysis/<video_filename_without_ext>_<task_id>.json
  • index_file: ~/.quanmiao/videoanalysis/index.jsonl

轮询循环：

  1. 提交后等待 10 秒
  2. 运行：python scripts/quanmiao_get_videoAnalysis_task_result.py --workspace_id <workspace_id> --task_id <task_id> --save_path <result_json_path>
  3. 检查返回的 status 字段：
  • SUCCESSED → 脚本自动将 JSON 保存到 result_json_path，向 index_file 追加条目，显示保存位置，然后继续执行步骤 6
  • FAILED 或 CANCELED → 检查错误消息，通知用户，然后停止
  • PENDING 或 RUNNING → 显示当前可用的部分结果，等待 10s，然后从步骤 2 开始重复执行
  1. 最多重试 180 次（约 30 分钟）

当 taskStatus = SUCCESSED 时：

  1. 追加到索引文件（index_file）：

    2. ``json {"task_id": "<task_id>", "video_source": "<original_path_or_url>", "workspace_id": "<workspace_id>", "result_file": "<result_json_path>", "timestamp": "<ISO8601>"} ``

  1. 显示保存位置：
✅ Files saved successfully:
- Raw JSON result: <result_json_path>
- Index updated: <index_file>

需要确认的参数：

  • --workspace_id：与步骤 4 相同（确认一致性）
  • --task_id：来自步骤 4 的提交结果（轮询前验证）

步骤 6：总结视频内容

关键要求：必须直接使用步骤 5 的结果。不得再次调用 API。不得重新执行任何分析。

从步骤 5 获取的 SUCCESSED 响应中提取数据，并根据用户要求进行总结。

情况 A：如果用户有具体的分析请求（例如，“分析说话者的肢体语言”“提取关键业务洞察”“比较视频中的两个人”），回答应主要基于：

  • payload.output.videoGenerateResults——逐场景的分析、描述和解读
  • payload.output.videoAnalysisResult.text——视觉镜头分析、物体/人物识别、动作检测

    • 综合这些字段构建有针对性的回答。如有相关性，可使用其他字段（字幕、思维导图、标题）补充上下文。

情况 B：如果没有具体请求，使用标准输出格式：标题 → 大纲 → 摘要 → 字幕 → 镜头分析 → 时间线 → Token 使用量

---

重要约束

  • 仅限云端： 不得使用本地回退方案（ffmpeg、whisper 等）。如果云端 API 调用失败，请遵循权限失败处理流程。
  • 违规后果： 使用本地工具而非 QuanMiaoLightApp API 将导致任务失败。
  • 安全： 严禁在日志或提示信息中暴露凭据
  • 权限： 出现认证错误时，请参阅 ram-policies.md
  • 缓存： 重新分析同一视频前，检查 ~/.quanmiao/videoanalysis/index.jsonl

---

成功验证

有关分步验证命令和预期结果，请参阅 [references/verification-method.md](references/verification-method.md)。

---

清理

要清理由此 skill 创建的资源：

删除已上传的 OSS 对象：

aliyun ossutil rm oss://{oss_bucket}/{oss_object_key} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

清理最佳实践：

  • 删除前确认存储空间名称和 OSS 对象键
  • 仅删除带有 /temp/quanmiao/ 前缀的对象，以避免意外丢失数据
  • 位于 ~/.quanmiao/videoanalysis/ 的缓存结果可以保留以供日后参考，也可以手动删除

---

最佳实践

  1. 始终先验证环境——在执行任何其他操作之前运行 check_env.py，以尽早发现缺失的依赖项或凭证。
  2. 自动检测 workspace_id——始终通过 list-workspaces 获取业务空间列表；默认使用第一个结果，但当用户明确要求选择时，应提供选择列表。
  3. 使用默认 OSS 设置——除非用户指定特定存储桶，否则由脚本自动检测存储桶并生成 OSS 对象键。
  4. 轮询期间显示部分结果——当任务状态为 RUNNING 时，显示已有结果（标题、字幕），为用户提供实时反馈。
  5. 保存完整结果以用于总结——当状态变为 SUCCESSED 时，直接将完整结果数据用于步骤 6，且不再调用 API。
  6. 遵守 URL 有效期限制——临时 OSS URL 会在经过 expireSeconds 指定的时长后过期（默认值为 14400s）；确保在该 URL 过期前提交任务。
  7. 妥善处理权限错误——遵循 RAM 策略部分中的权限失败处理流程；不得擅自采用凭证修复方案。

---

命令表

有关可用脚本及其参数的完整列表，请参阅 [references/related-commands.md](references/related-commands.md)。

---

参考链接

| 参考资料 | 用途 | |------------------------------------------|----------------------------------------------------------| | references/cli-installation-guide.md | 安装和升级阿里云 CLI | | references/ram-policies.md | RAM 权限检查清单和授权指南 | | references/acceptance-criteria.md | 验收标准及正确/错误的使用模式 | | references/related-commands.md | 可用脚本和 CLI 命令参考 | | references/verification-method.md | 分步成功验证命令 |

---

故障排除

常见场景：

  • 权限被拒绝 → 参见 [ram-policies.md](references/ram-policies.md)
  • 未找到 CLI → 参见 [cli-installation-guide.md](references/cli-installation-guide.md)
  • 未找到业务空间 → 前往 百炼控制台 创建
  • 上传失败 → 检查 OSS 存储桶权限
  • 任务超时 → 视频过大或存在网络问题

---

qianwen skills install @aliyun/alibabacloud-bailian-videoanalysis