alibabacloud-bailian-videoanalysis 是什么？

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

alibabacloud-bailian-videoanalysis 怎么安装？

打开本页上方的「安装命令」标签页，复制命令到终端运行即可完成安装。

alibabacloud-bailian-videoanalysis 适合哪些场景？

主要用于「AI与自动化」等场景，适合需要阿里云百炼-视频理解，基于先进通义多模态大模型。可生成视频标题、大纲、总结、分镜信息。可通过自定义 prompt，实现标签抽取、时间线总结等。的任务。

alibabacloud-bailian-videoanalysis 收费吗？

本站收录的 Skill 安装包可免费获取使用；部分 Skill 依赖的第三方服务（如外部 API）可能需单独申请或订阅，以官方说明为准。

alibabacloud-bailian-videoanalysis：阿里云百炼-视频理解，基于先进通义多模态大模型。可生成视频标题、大纲、

Q: alibabacloud-bailian-videoanalysis 适合哪些场景？

主要用于「AI与自动化」等场景，适合需要 阿里云百炼-视频理解，基于先进通义多模态大模型。可生成视频标题、大纲、总结、分镜信息。可通过自定义 prompt，实现标签抽取、时间线总结等。 的任务。

百炼视频分析

本 Skill 基于阿里云百炼视频分析轻应用提供视频分析功能。它使用百炼（QuanMiaoLightApp）API 进行智能视频理解，包括分镜分析、ASR 转录、标题生成、字幕提取和思维导图。

架构： CLI（凭证链）+ OSS（文件存储）+ 百炼工作空间 + 全妙视频分析服务 + Python SDK 脚本

输出语言策略

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

适用于： 所有面向用户的消息、摘要、错误解释和交互提示。

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

安装

1. Python 依赖

python -m pip install -r scripts/requirements.txt

某些系统上使用 python3 而非 python


### 2. 阿里云 CLI

> **前置检查：需要 Aliyun CLI >= 3.3.1**
> 运行 `aliyun version` 确认 >= 3.3.1。若未安装或版本过低，
> 见 `references/cli-installation-guide.md` 获取安装说明。
> 然后 **[必须]** 运行 `aliyun configure set --auto-plugin-install true` 启用插件自动安装。

> **aliyun CLI 的 AI-Mode 配置**
>
> 在本 Skill 中使用 aliyun CLI 时，你必须配置 AI-Mode 设置：
>
> ```bash
> # 启用 AI-Mode（使用 CLI 命令前必需）
> aliyun configure ai-mode enable
>
> # 设置 User-Agent 用于追踪（必需）
> aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis
>
> # 更新插件到最新版本（推荐）
> aliyun plugin update
> ```
>
> **注意：** 完成任务后，可禁用 AI-Mode：
> ```bash
> aliyun configure ai-mode disable
> ```

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

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

1. 访问[百炼 Video_Analysis 页面](https://bailian.console.aliyun.com/cn-beijing#/app/app-market/quanmiao/video-comprehend)
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. 访问[阿里云百炼权限管理](https://bailian.console.aliyun.com/cn-beijing?tab=app#/authority)
2. 如果 AK 对应的 RAM 用户不存在，点击页面右上角**"添加用户"**，选择对应 RAM 用户并点击确认添加。
3. 配置后有 30 秒生效时间，请耐心等待一会儿。

---

鉴权

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

参数确认

重要：参数确认 —— 执行任何命令或 API 调用前，
确认用户提供或可自定义的参数（视频源、OSS bucket、oss object key）。
系统自动解析的参数（workspace_id、默认 OSS bucket）不需要显式确认，
除非用户想覆盖它们。

参数	类型	说明	默认值 / 解析
`video_source`	必填	本地文件路径或可下载的视频 URL	无（用户必须提供）
`workspace_id`	自动解析	百炼工作空间 ID	自动检测（用户可覆盖）
`ossBucket`	可选	文件上传的 OSS bucket 名	从第一个可用 bucket 自动检测；用户可指定（例如 `--ossBucket my-bucket`）
`ossObjectKey`	可选	上传文件的 OSS object key	`/temp/quanmiao/YYYYMMDD/filename`
`expireSeconds`	可选	临时 URL 过期时间（秒）	`14400`（4 小时）

确认工作流：

先自动检测：Skill 在可能时自动检测 workspace_id 和 ossBucket
用户覆盖：如果用户想指定自定义值，使用前确认
本地 vs 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
凭证缺失或无效 → 遵循权限失败处理流程：

阅读 references/ram-policies.md 获取所需权限
使用 ram-permission-diagnose skill 引导用户申请权限
等待用户确认后再继续
不要用本地分析工具继续

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

步骤 2：获取工作空间 ID

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

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

工作空间选择逻辑：

返回单个工作空间 → 直接使用，无需提示用户
返回多个工作空间 → 显示编号列表并按以下处理：

默认行为：自动使用列表中第一个工作空间以避免不必要的交互
用户明确要求选择：如果用户说"让我选工作空间"、"显示工作空间列表"或类似，呈现完整列表并请他们选一个

无工作空间返回 → 告知用户没有可用的百炼工作空间，引导他们在百炼控制台创建
记录用户选择 在会话中以避免重复询问

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

基于输入资源验证中的输入资源类型：

情况 A：用户提供了可下载的 URL

→ 验证 URL 可访问性：用适合你操作系统的方法测试 URL 是否可下载

→ 跳过此步骤。用 video_source 作为步骤 4 中的 file_url。

情况 B：用户提供了本地文件路径

→ 自动检测 OSS bucket、上传本地文件到 OSS 并获取临时 URL（file_url）用于步骤 4：

(1) 自动检测或使用用户指定的 OSS bucket：
如果用户指定 --ossBucket <bucket_name>，尝试使用该 bucket
如果指定 bucket 返回 403 AccessDenied 或 BucketAlreadyExists：不要自动切换到另一个 bucket。而是：

告知用户指定 bucket 不可访问
遵循 RAM 策略章节中的权限失败处理流程
引导用户授予 OSS bucket 访问权限或指定他们拥有的替代 bucket
等待用户确认后再继续

如果未指定 bucket，从第一个可用 bucket 自动检测

aliyun ossutil ls --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

(2) 上传文件到 OSS：为上传文件生成唯一 key（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 可访问性：用适合你操作系统的方法测试生成的 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
- ✅ Action：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：停止并遵循权限失败处理流程
不要尝试替代 API 或本地工具
告知用户："视频分析需要开通百炼服务和正确的 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

轮询循环：

提交后等待 10 秒
运行：python scripts/quanmiao_get_videoAnalysis_task_result.py --workspace_id <workspace_id> --task_id <task_id> --save_path <result_json_path>
检查返回的 status 字段：

SUCCESSED → 脚本自动保存 JSON 到 result_json_path，向 index_file 追加条目，显示保存位置，然后进入步骤 6
FAILED 或 CANCELED → 检查错误消息，告知用户，停止
PENDING 或 RUNNING → 显示任何可用部分结果，等待 10s，从步骤 2 重复

最多 180 次重试（约 30 分钟）

当 taskStatus = SUCCESSED 时：

追加到索引文件（index_file）：

    {"task_id": "<task_id>", "video_source": "<original_path_or_url>", "workspace_id": "<workspace_id>", "result_file": "<result_json_path>", "timestamp": "<ISO8601>"}

显示保存位置：

✅ 文件保存成功：
- 原始 JSON 结果：<result_json_path>
- 索引已更新：<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。

清理

清理本 Skill 创建的资源：

删除上传的 OSS 对象：

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

清理最佳实践：

删除前确认 bucket 名和 oss object key
只删除带 /temp/quanmiao/ 前缀的对象以避免意外数据丢失
~/.quanmiao/videoanalysis/ 的缓存结果可保留供未来参考或手动删除

最佳实践

始终先验证环境 —— 在任何其他操作前运行 check_env.py 以尽早捕获缺失依赖或凭证。
自动检测 workspace_id —— 始终通过 list-workspaces 获取工作空间；默认用第一个结果，但用户明确要求选择时呈现选择列表。
使用默认 OSS 设置 —— 除非用户指定特定 bucket，让脚本自动检测 bucket 并生成 oss object key。
轮询期间显示部分结果 —— 当任务状态为 RUNNING 时，显示可用结果（标题、字幕）给用户实时反馈。
保存完整结果用于总结 —— 状态变为 SUCCESSED 时，直接使用完整结果载荷进行步骤 6，无需重新调用 API。
尊重 URL 过期 —— 临时 OSS URL 在 expireSeconds（默认 14400s）后过期；确保在 URL 过期前提交任务。
优雅处理权限错误 —— 遵循 RAM 策略章节中的权限失败处理流程；绝不临时拼凑凭证修复。

命令表

可用脚本及其参数的完整列表见 references/related-commands.md。

参考链接

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

故障排查

常见场景：

权限拒绝 → 见 ram-policies.md
CLI 未找到 → 见 cli-installation-guide.md
工作空间未找到 → 在百炼控制台创建
上传失败 → 检查 OSS bucket 权限
任务超时 → 视频过大或网络问题

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