alibabacloud-oss-media-process

Alibaba Cloud OSS 媒体处理

使用 OSS 原生媒体处理功能，处理存储在 Alibaba Cloud OSS 中的图像、音频和视频文件。同步处理通过 x-oss-process 立即返回结果；异步处理通过 x-oss-async-process 处理耗时较长的任务，并通过轮询获取结果。

默认语言：默认中文回复。只有当用户明确使用英语时，才使用英语。

快速开始

工作目录

所有脚本命令都从技能包根目录运行。调用脚本时请使用绝对路径：

python /path/to/skill/scripts/process.py ...

请勿使用 cd 进入目录后再使用相对路径。如果脚本报错“No such file or directory”，请使用 Glob 查找 **/alibabacloud-oss-media-process/scripts/process.py，并使用其完整路径。

设置工作区输出目录（每个会话运行一次）：

WORKSPACE_OUTPUT=$(pwd)/outputs && mkdir -p "$WORKSPACE_OUTPUT"

所有 --output-path 参数都必须使用 $WORKSPACE_OUTPUT/<filename> — 保存在技能目录中的文件将无法渲染。

凭证（Aliyun CLI）

此技能使用 Aliyun CLI 管理凭证。Python 脚本会通过 alibabacloud-credentials 默认凭证链自动发现凭证（支持 ~/.aliyun/config.json、环境变量、ECS 实例角色等）。

安全规则：

• 切勿读取、回显、打印、使用 cat 查看或转储 ~/.aliyun/config.json、凭证文件，或包含 access_key_id、access_key_secret、sts_token、AccessKeyId、AccessKeySecret 或 SecurityToken 值的任何原始命令输出。
• 切勿要求用户在对话或命令行中直接输入 AK/SK。
• 指导用户使用 aliyun configure 安全地设置凭证。
• 切勿将 AccessKeyId、AccessKeySecret 或 SecurityToken 写入任何临时 Python/Shell 脚本、here-doc、环境变量导出语句或中间文件。所有凭证都必须通过 Aliyun CLI 或 SDK 默认凭证链发现。
• 排查凭证问题时，请使用 aliyun configure list、python scripts/load_env.py 或其他不会泄露机密的检查方式。如果必须检查配置结构，只检查非敏感字段，且不要在对话记录中打印机密或令牌值。
• 如果完整预签名 URL 包含 OSSAccessKeyId、accessKeyId、x-oss-credential、Signature、x-oss-signature、security-token、SecurityToken 或 sts_token 等签名参数，则应将其视为敏感信息。不要在对话记录、命令回显、Markdown 摘要或普通日志文件中打印这些完整 URL。
• 需要向用户提供签名 URL 时，请区分交付与展示：可以生成可用的签名 URL，但除非运行环境提供不会进入对话记录或日志的安全私密输出通道，否则在面向用户的常规文本中只能显示已删节的 URL 或 OSS 路径。

前置条件

步骤	操作	命令
1	安装 Aliyun CLI（>=3.3.3）	`curl -fsSL https://aliyuncli.alicdn.com/setup.sh
2	配置凭据	aliyun configure
3	运行阻断式预检 1	python scripts/load_env.py
4	运行阻断式预检 2	aliyun configure list
5	启用插件	aliyun configure set --auto-plugin-install true && aliyun plugin update
6	安装 Python 依赖	pip install -r scripts/requirements.txt
7	设置存储桶/区域（二选一）	export ALIBABA_CLOUD_OSS_BUCKET=<b> ALIBABA_CLOUD_OSS_REGION=<r>（添加到 ~/.bashrc/~/.zshrc 以持久保存），或在每条命令中传入 --bucket <b> --region <r>

阻断式预检策略：

• python scripts/load_env.py 可能会报告 SDK 缺失、凭据缺失、存储桶/区域缺失或 RAM 权限问题。
• aliyun configure list 必须显示可用的已配置 CLI 配置文件。
• 每当环境或运行时发生变化，预检结果都应视为已过期。如果安装了 Python 包、运行了 aliyun configure、更改了环境变量、编辑了 shell 配置文件、切换了用户，或以其他方式修改了凭据/运行时状态，则在下一条 python scripts/process.py ... 命令之前，必须重新运行 python scripts/load_env.py 和 aliyun configure list。
• 如果任一命令未通过这些检查，请立即停止。
• 不要运行 python scripts/process.py ...。
• 不要重试媒体处理。
• 不要模拟成功结果。
• 只有在两项检查都通过后，才返回配置指导。

AI 模式

在会话开始时启用：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-oss-media-process"

每次退出时都要禁用：成功、失败、出错、取消或会话结束时：

aliyun configure ai-mode disable

先预检，再执行

当用户请求媒体操作（调整大小、人脸检测、添加水印等）时，在运行任何 python scripts/process.py ... 命令前，先应用上述阻断式预检策略。process.py 还会执行运行时依赖预检；如果缺少所需 SDK，则会退出并提示运行 pip install -r scripts/requirements.txt。如果在失败尝试后更改了环境（例如安装依赖、编辑环境变量或重新运行 aliyun configure），不要假设先前的预检仍然有效——请先重新运行完整的阻断式预检。

首次设置

请指导用户运行 aliyun configure 设置凭据，然后使用以下命令验证：

aliyun configure list

Python 脚本使用 alibabacloud-credentials SDK，从 Aliyun CLI 配置中自动发现凭据。存储桶和区域从 ALIBABA_CLOUD_OSS_BUCKET / ALIBABA_CLOUD_OSS_REGION 环境变量或 --bucket / --region CLI 标志读取。load_env.py 会扫描 shell 配置文件（~/.bashrc、~/.zshrc）中的这些导出语句，并将其载入 os.environ。

推荐工作流

每次请求都遵循以下编号工作流：

1. 准备 确认可通过 --bucket / --region 或 ALIBABA_CLOUD_OSS_BUCKET / ALIBABA_CLOUD_OSS_REGION 环境变量获取存储桶和区域。在执行任何媒体命令之前，应用阻断式预检策略。每个会话创建一次 $WORKSPACE_OUTPUT，用于所有本地下载。

2. 选择来源 对于现有 OSS 对象键，使用 --source。对于需要在处理前临时上传的本地文件路径或 HTTP(S) URL，使用 --uri。

3. 确定执行路径 所有媒体处理和文件操作都使用 python scripts/process.py。如果请求涉及视频、音频、HLS 或图像智能功能，请先运行 python scripts/imm_admin.py auto-setup --bucket <b> --region <r>，以确保已建立 IMM 存储桶绑定。

4. 执行 构建且仅构建一个有效的操作链。对于同步图像输出，优先使用 --output-mode download --output-path $WORKSPACE_OUTPUT/<name>；对于异步媒体输出，优先使用 --output-mode save --target-key <key>；如果结果需要在远程使用，则使用 --output-mode url。

5. 验证 阅读返回的 JSON。检查 success、request_id、task_id（仅异步任务）、target_key、本地 path 以及任何 validation_warnings。如果命令下载了本地文件，请向用户提供绝对路径。 只有在文件确实已写入 $WORKSPACE_OUTPUT，且返回的绝对路径与实际下载的文件匹配时，才能报告本地输出路径。除非文件确实存在于 outputs/... 或其他本地路径中，否则不要声称文件已保存到该路径。 如果需要在日志、笔记或输出文件中记录 task_id、request_id、target_key、generated_keys 或类似字段，请直接从 process.py 的 JSON 响应中提取。不要转录、改写或手动重新输入这些值。 如果用户或评测明确要求验证任何可通过机器验证的输出属性（例如编解码器、比特率、采样率、声道数、时长、分辨率、帧率、宽度、高度或格式），请优先针对已持久化的 OSS 输出对象，再执行一个只读验证步骤，然后再完成摘要。音频/视频输出使用 audio/info 或 video/info，图像输出使用单独的 --operations info 命令。不要仅为此目的在本地下载文件。 对于图像宽度、高度、格式和文件大小的验证，应将对已保存目标对象执行的 OSS 端 --operations info 作为默认且优先的验证方式。info 是独立的只读图像元数据操作，不应作为后续步骤追加到基本图像处理链中。如果 info 可以回答问题，请勿改用本地图像库检查。 如果只读验证步骤的结果与请求值不同，请报告实际验证的输出值。不要用请求值替代实际值，也不要在验证结果显示未满足请求时声称请求已完全满足。 如果未执行只读验证步骤，请勿将可通过机器验证的输出属性描述为已独立确认。 不要假定已安装 PIL/Pillow、ffprobe 或类似的本地验证工具。如果某个工具不可用，不要声称执行了相应的本地像素级或媒体属性验证。 尤其是在验证图像属性时，除非工作流明确要求仅检查本地文件，且 OSS 端的 info 无法提供相关属性，否则不要引入临时的本地库检查，例如 PIL/Pillow。在常规技能使用和评测中，优先使用 OSS 端验证，并避免输出本地 PIL/Pillow 命令。 如果工作流只返回签名 URL，且未持久化可复用的 OSS 目标对象，则不要声称对最终输出对象执行了后续 info 检查，除非该对象确实存在。在这种情况下，应先将结果保存到 OSS 再进行验证，或者说明当前仅能获取即时处理结果，未执行持久化对象验证。 发送面向用户的最终摘要之前，请遵循「结果呈现」中的「语言规则」。

6. 恢复 如果命令失败，请使用下方的「错误恢复」表。只有在修正具体原因（例如缺少 IMM 绑定、参数错误或 RAM 权限不足）后才重试。

---

快速决策指南

所有处理都通过 process.py 执行

图像、视频和音频操作必须通过 python scripts/process.py --operations "..." 执行。Agent 不得编写自己的 SDK 或 CLI 调用来绕过 process.py 或 imm_admin.py 处理视频／音频／图像。由这些脚本在内部触发的底层 SDK 或 API 请求（包括 CreateMediaConvertTask 等 IMM 请求）属于预期的实现行为，不算作 Agent 直接使用 SDK。仅有的有意设置的脚本级 IMM 入口是用于项目设置的 imm_admin.py 和用于异步水印提取的 blindwatermark-extract。

不得创建自己的 Python 脚本或包装器来绕过 process.py。如果 process.py 不支持某项功能，请查阅 SKILL.md 和 references/ 文档，使用 --dry-run 预览；如果确实无法完成，请告知用户。

IMM 设置（IMM 相关操作前）

运行视频、音频、HLS 或图像智能操作前，先运行 imm_admin.py auto-setup，确保存储桶已绑定到 IMM 项目。仅在执行 blindwatermark-extract 时传入 --imm-project <project_name>，或者在有意覆盖该操作使用的可选回退值 ALIBABA_CLOUD_IMM_PROJECT 时传入。

源选择

• OSS 对象 → --source object-key
• 本地文件或 URL → --uri /path/to/file（自动上传、处理并清理）

同步与异步（自动检测）

• 同步（x-oss-process）：图像操作、video/snapshot、video/info、audio/info、hls/m3u8、AI 检测
• 异步（x-oss-async-process）：video/convert、video/animation、video/snapshots、video/sprite、video/concat、audio/convert、audio/concat、blindwatermark-extract

脚本会自动检测仅支持异步的操作，并自动处理路由和轮询——无需 --async 或 --wait 标志。

输出规则

操作类型	输出模式	命令模式
同步（图像）	download	--output-mode download --output-path $WORKSPACE_OUTPUT/<file>
异步（视频/音频）	save，然后 download	1. --output-mode save --target-key output/<file> → 2. --operations download --output-path $WORKSPACE_OUTPUT/<file>
video/snapshots	save 并自动下载	--output-mode save --target-key output/frames/frame --output-path $WORKSPACE_OUTPUT/ — 脚本会自动轮询并下载所有帧
hls/m3u8	url	--output-mode url — 返回供浏览器/播放器使用的签名 URL（不是可下载文件）

所有 --output-path 都必须使用 $WORKSPACE_OUTPUT/<filename> — 保存在 skill 目录中的文件将无法渲染。

禁止下载到本地规则：如果用户明确表示不要下载到本地、只保存到 OSS，或只返回链接/URL，则不要传入 --output-path，也不要执行后续下载以进行验证。对于需要远程使用的同步结果，使用 --output-mode url；对于应保留在 OSS 中的异步媒体结果，使用 --output-mode save --target-key ...。切勿仅为验证成功而下载到 $WORKSPACE_OUTPUT、/tmp 或任何本地路径；请依赖 process.py 的 JSON 响应。

含糊的保存措辞规则：如果用户说“保存”“保存下来”“存起来”或类似表述，但没有明确说“下载到本地”“本地查看”“给我本地文件”或其他清楚表明本地存储位置的说法，默认使用 --output-mode save --target-key ... 将结果保存回 OSS。只有用户明确要求本地文件时，才使用 --output-mode download --output-path ...。如果用户只是想查看结果，并不需要持久保存一份本地副本，则同步输出优先使用 --output-mode url，异步输出优先使用 --output-mode save，并提供 OSS 路径。

签名 URL 交付规则：--output-mode url 的目的是让远程结果可访问，而不是强行将完整签名查询字符串写入对话记录。普通文本回复中，优先提供 OSS 路径或已删减敏感信息的 URL。只有当运行环境提供安全的私密输出通道、能够避免原始 URL 出现在对话记录/日志中时，才提供完整的预签名 URL。如果没有此类通道，请简要说明限制，并避免打印完整的签名查询参数。已删减敏感信息的 URL 应保留路径和非敏感查询参数，同时将敏感签名值替换为 ***，例如：https://bucket.oss-cn-hangzhou.aliyuncs.com/output/result.webp?OSSAccessKeyId=***&x-oss-credential=***&Signature=***&security-token=***&Expires=1700000000。

唯一后缀规则：对于评估、重试或并行运行需要唯一的 OSS 目标键后缀时，优先使用 Python 生成的 UUID，或时间戳加随机后缀。不要假设 uuidgen 可用。如果必须通过 shell 命令生成后缀，请先确认该命令存在；否则改用时间戳加随机数字。安全的 shell 示例：SUFFIX=$(python3 -c "import uuid; print(uuid.uuid4().hex[:8])" 2>/dev/null || date +%Y%m%d_%H%M%S_$RANDOM)。

链接规则

完整的链接指南请参阅下方专门的 Chaining Rules 部分。

---

核心参数规则

1. 仅传递用户指定的参数 — 不要自行编造默认值。对于未指定的参数，OSS 使用官方默认值（例如，保持原始宽度/高度、原始比特率、原始帧率）。
2. 配方是示例，不是默认值 — 配方表中的参数值（例如 w=800、vb=2000000）适用于特定场景，不应作为默认值使用。
3. video/convert — 重新封装与重新编码：省略 vcodec 意味着 OSS 只进行重新封装（流复制，不重新编码）。videoslim、vb、crf、s、fps 等参数在重新封装模式下会被静默忽略。用户说“转码”“压缩”或“瘦身”时，务必指定 vcodec（默认值为 h264）。只有在纯重新封装（例如 AVI→MP4 容器转换）或提取音频时，才省略 vcodec。
4. video/concat — 输入参数不同时：如果输入视频的分辨率、帧率或编解码器不同，必须询问用户要以哪个视频为准（选项 A：第一个视频，B：第二个视频，C：自定义参数）。绝不能自动决定。
5. video/concat — 验证范围：process.py 在提交异步任务前始终会执行输入兼容性检查。只有在命令同时通过 --output-path 下载结果时，才会额外进行本地 ffprobe 输出验证。如果使用 --output-mode save，且未指定本地下载路径，则不会执行下载后的媒体验证。
6. Snapshots 与 snapshot：多帧提取时使用 video/snapshots（异步）。绝不要通过多次调用 video/snapshot 来变通。video/snapshots 的 target-key 不得带文件扩展名。
7. 完整参数规范请参阅 references/ 中对应的参考文件。

---

结果呈现

每次成功执行 process.py 后，都按以下格式呈现结果：

语言规则：除非用户明确要求使用英语，否则本节面向用户的最终结果摘要必须使用中文。 使用与回复语言相匹配的结果模板。中文回复请使用 处理结果如下： 这样的中文引导语，以及 状态 / 请求 ID / 任务 ID / 源文件 / 输出 / 参数 / 文件大小 / OSS 路径 这样的中文字段标签。英文回复请使用 Result summary:，以及对应的英文标签 Status / RequestID / Task ID / Source / Output / Params / File Size / OSS Path。

1. 文件路径：在代码块中输出本地绝对路径（例如，/path/to/outputs/snapshot.jpg）。切勿使用 open 或 Read 工具显示文件。 仅当文件实际已下载或写入本地时，才包含此部分。不要呈现仅计划、推断或在对话记录中提及的 outputs/... 路径。

2. 结果表：

项目	详情
状态	✅ 已完成
请求 ID	<request_id>（或 N/A）
任务 ID	<task_id>（仅异步任务）
源文件	source/input.mp4
输出	output/result.mp4
参数	动态填写 — 取自你的命令（例如，MP4/H.264/2Mbps，或 800x600/JPEG）
文件大小	取自下载输出
OSS 路径	oss://<bucket>/<target-key>（仅保存模式）

字段取值规则：状态 和 参数 必须直接引用 process.py 的 JSON 响应。状态 必须取自返回的 success 字段，参数 必须取自返回的 operations 字段。绝不要手动改写、估算、规范化或概述数值/媒体值，包括置信度分数、比特率、分辨率、尺寸、帧率或编解码器详情。

如果需要文字摘要，请在围栏代码块中包含原始命令或处理字符串，并谨慎描述。若 process.py 响应中未明确给出参数值，不要编造参数值，也不要在自由文本中重述这些参数。 最终摘要约束：

• 不要插入固定的英文填充语，例如 Task Completed Successfully。
• 采样率、比特率、分辨率、时长、帧率和文件数等数值，必须直接从 process.py 的 JSON 字段或明确执行的只读验证结果中复制。
• 如果某个值并非直接从机器输出中获取，则应省略，不要手动改写、估算、取整或规范化。
• 如果明确执行的只读验证结果与请求的值不一致，应报告实际验证到的输出值，并在必要时说明请求仅部分满足。不要用请求的值替换已验证的值。
• 如果未获得只读验证结果，不要声称已独立确认可由机器验证的输出属性。

如果用户禁止本地下载，则完全省略 File path 行或部分，也不要创建临时本地文件进行验证。在这种情况下，只提供 process.py 返回的、由 JSON 支持的元数据，例如 success、request_id、task_id、target_key、generated_keys 或 url。

如果 process.py 返回签名 URL，则应将完整查询字符串视为敏感输出。在常规可见摘要中，优先使用 OSS 路径、目标键或已隐藏部分内容的 URL。除非运行时提供用于传递机密信息的安全私密输出通道，否则不要在最终摘要中展开原始签名参数。

如果用户要求独立验证，但工作流只返回了签名 URL，且未创建持久化的 OSS 目标对象，则不要声称已对最终输出对象执行后续 info 检查。应先保存结果再验证已保存的对象，或明确说明无法进行持久化对象验证。

对于图像输出以及水印、叠加层、模糊区域或人脸遮挡等视觉效果，应区分元数据验证与视觉验证。如果未在本地下载或渲染输出，则不要声称通过检查独立确认了视觉元素；除非确实执行了本地渲染或明确的检查步骤，否则应说明仅验证了服务报告的处理结果。 规则：

• 处理完成后，不要为常规结果报告运行 video/info、audio/info 或图像 --operations info。但是，如果用户明确要求验证具体且可由机器验证的输出属性，例如编解码器、比特率、采样率、声道数、时长、分辨率、帧率、宽度、高度或格式，或者评估／验收标准明确要求独立检查属性，则优先对已持久化的 OSS 输出对象额外执行一次只读验证步骤，并将该验证结果与主要的 process.py 结果分开报告。对于音频／视频输出，使用 audio/info 或 video/info；对于图像输出，使用单独的 --operations info 命令。
• 不要假设本地验证库或二进制工具（例如 PIL／Pillow、ffprobe 或类似工具）已预装。只有在这些工具确实可用且工作流确实需要检查本地文件时才使用；否则依赖 process.py JSON 输出以及允许的 OSS 只读端检查。
• 验证图像宽度／高度／格式时，即使本地文件已存在，也优先对已保存的目标对象使用 OSS 端 --operations info。不要在评估或常规技能运行中默认使用 PIL／Pillow 进行验证。
• 要求验证图像宽度、高度、格式或类似的可由机器验证的属性，本身并不授权下载到本地。如果用户没有明确要求本地文件，且可以通过 info 验证已保存的 OSS 目标对象，则不要仅为验证而切换到 --output-mode download。
• 不要用 head_object 替代媒体属性验证。
• 避免使用 sleep + 重试循环；脚本会在内部处理异步轮询。
• 所有媒体处理都通过 process.py；如果不支持，请检查 references/ 并报告，不要编写自定义脚本。

---

链式操作规则

图像操作

• 基本操作之间可以自由组合
• blindwatermark-embed 可以接在基本操作之后，但必须是最后一个操作
• blindwatermark-extract 必须单独使用，不得与其他操作组合
• AI 检测（faces、bodies、cars、codes、labels、score）必须单独使用

视频／音频操作

• 视频／音频操作不能与图像操作组合
• 每个请求只能执行一个视频／音频操作（不得组合）
• 对于复杂工作流，请使用多个独立请求

---

凭证与环境设置

凭证由 Aliyun CLI 管理（~/.aliyun/config.json）。Python 脚本通过 alibabacloud-credentials SDK 默认链自动发现凭证。设置步骤请参阅上方的 Prerequisites。

诊断检查：

python scripts/load_env.py

此检查会扫描旧版环境变量并验证 RAM 权限。如果操作因访问错误而失败，请使用此检查。

运行时依赖预检：process.py 会在执行前检查所需的 Python 包。基本 OSS／文件操作需要 oss2 和 alibabacloud-credentials；视频／音频／HLS／IMM 操作还需要 scripts/requirements.txt 中的 IMM SDK 包。如果缺少任何依赖，命令会快速失败并提示安装，而不会开始部分执行。

IMM 项目——通常由 imm_admin.py auto-setup 自动发现。对于 blindwatermark-extract，process.py 只使用 --imm-project／ALIBABA_CLOUD_IMM_PROJECT。

---

IMM 自动设置

视频／音频处理和图像智能功能需要将 IMM 项目绑定到存储桶。对于依赖 IMM 的操作，请按以下工作流执行：

步骤 1 — 检测 IMM 项目（在执行任何处理命令之前）：

python scripts/imm_admin.py auto-setup --bucket <bucket> --region <region>

这可确保存储桶已绑定到可用的 IMM 项目，并输出解析后的项目名称。

步骤 2 — 执行媒体操作：

python scripts/process.py --source video.mp4 \
  --operations "video/convert:f=mp4,vcodec=h264" \
  --output-mode save --target-key output/video.mp4

对于 blindwatermark-extract，如果不想依赖可选的 ALIBABA_CLOUD_IMM_PROJECT 回退值，请追加 --imm-project <project_name>。

步骤 3 — 按照上述“执行与输出工作流”呈现结果。

需要设置 IMM 存储桶的操作：所有视频／音频／HLS 操作、图像智能操作（faces、bodies、cars、codes、labels、score、blindwatermark-embed/extract）、智能裁剪（crop:g=auto／crop:g=face）、人脸模糊（blur:g=face／blur:g=faces）。只有 blindwatermark-extract 要求将项目名称作为直接的 process.py 输入。

---

可用操作

图像处理（同步）

操作	描述	参考
resize、crop、indexcrop、rotate、flip	基本变换	references/image-basic-operations.md
quality、format、interlace	质量与格式	references/image-basic-operations.md
watermark、blur、sharpen、bright、contrast	效果	references/image-basic-operations.md
auto-orient、circle、rounded-corners	实用工具	references/image-basic-operations.md
info、average-hue	元数据（JSON）	references/image-basic-operations.md

图像智能（IMM）

操作	模式	描述	参考
blindwatermark-embed	同步	嵌入不可见水印。必须放在处理链末尾。	references/image-imm-operations.md
blindwatermark-extract	异步	提取水印。单独使用。	references/image-imm-operations.md
faces、bodies、cars	同步	检测人脸／人体／汽车（JSON）。	references/image-imm-operations.md
codes、labels、score	同步	QR 码／条形码识别、标签、质量评分（JSON）。	references/image-imm-operations.md

视频处理

操作	模式	描述	参考
video/convert	异步	转码视频。重新编码时必须指定 vcodec。	references/video-operations.md
video/snapshot	同步	提取单帧。必须指定 t（时间，毫秒）。	references/video-operations.md
video/info	同步	视频元数据（JSON）。	references/video-operations.md
video/animation	异步	将视频转换为 GIF／WebP。	references/video-operations.md
video/snapshots	异步	提取多帧。target-key 不得带扩展名。	references/video-operations.md
video/sprite	异步	雪碧图。必须指定 num 或 inter。	references/video-operations.md
video/concat	异步	拼接视频（最多 11 个）。必须确认输入参数匹配。	references/video-operations.md

音频处理

操作	模式	描述	参考
audio/convert	异步	转码音频。	references/audio-operations.md
audio/concat	异步	拼接音频文件。	references/audio-operations.md
audio/info	同步	音频元数据（JSON）。	references/audio-operations.md

HLS 流媒体

操作	模式	描述	参考
hls/m3u8	同步	HLS 播放列表（返回的是播放列表，而非文件——使用 --output-mode url）。	references/video-operations.md

文件操作

操作	模式	描述
upload	同步	将本地文件／URL 上传到 OSS。与 --uri 和 --target-key 配合使用。
download	同步	下载 OSS 对象。与 --source 和 --output-path 配合使用。

处理模式

• 同步（x-oss-process）：图像基础处理、video/snapshot、video/info、audio/info、hls/m3u8、AI 检测——立即返回结果
• 异步（x-oss-async-process）：视频/音频转码、动画、雪碧图、快照、拼接、盲水印提取——自动检测，并自动轮询直至完成

---

用法

python scripts/process.py \
  [--bucket BUCKET_NAME] \
  [--region REGION_ID] \
  (--source OSS_OBJECT_KEY | --uri URI) \
  --operations OPERATION [OPERATION ...] \
  [--output-mode url|download|save] \
  [--expires SECONDS] \
  [--output-path LOCAL_PATH] \
  [--target-key OSS_TARGET_KEY] \
  [--endpoint CUSTOM_ENDPOINT] \
  [--imm-project IMM_PROJECT_NAME] \
  [--dry-run]

--imm-project 仅供 blindwatermark-extract 使用；其他操作依赖 IMM 存储桶绑定，不使用此标志。

--uri

无需预先上传，即可通过本地文件路径或 URL（http/https）处理文件。脚本会自动将文件上传到临时键，完成处理后进行清理。--uri 和 --source 不能同时使用。

--dry-run

将生成的处理字符串和操作详情以 JSON 格式打印到 stdout，然后退出，不连接 OSS。

操作字符串格式

每个操作的格式为：name:key=value,key=value。无参数的操作只使用名称（例如 info、video/info）。视频/音频操作使用斜杠表示：video/convert、audio/convert。

端到端示例

用户请求：

Resize `images/photo.jpg` in OSS to width 600px, add a bottom-right text watermark `Copyright 2026`, and download the result locally. The bucket is `my-media-bucket` in region `cn-shanghai`.

命令：

python scripts/process.py --bucket my-media-bucket --region cn-shanghai \
  --source images/photo.jpg \
  --operations "resize:w=600" "watermark:text=Copyright 2026,g=se,opacity=60,size=30" \
  --output-mode download \
  --output-path "$WORKSPACE_OUTPUT/photo-watermarked.jpg"

预期结果格式：

{
  "success": true,
  "mode": "download",
  "path": "/absolute/path/to/outputs/photo-watermarked.jpg",
  "size": 12345,
  "request_id": "xxxxxx"
}

说明：

• success: true 表示 OSS 处理已成功完成。
• path 是你应提供给用户的本地文件路径。
• request_id 是用于故障排查的服务端请求跟踪 ID。

更多示例

# HLS streaming (with IMM auto-setup)
python scripts/imm_admin.py auto-setup --bucket my-bucket --region cn-hangzhou
# → Capture project name from output
python scripts/process.py --bucket my-bucket --region cn-hangzhou \
  --source videos/input.mp4 \
  --operations "hls/m3u8:ss=15000,t=1800000,vcodec=h264,fps=25,s=1280x720,vb=2000000,acodec=aac,ab=128000" \
  --output-mode url

# Upload a local file to OSS
python scripts/process.py --bucket my-bucket --region cn-hangzhou \
  --uri /path/to/report.pdf --operations upload --target-key documents/report.pdf

# Download a file from OSS
python scripts/process.py --bucket my-bucket --region cn-hangzhou \
  --source documents/report.pdf --operations download --output-path $WORKSPACE_OUTPUT/report.pdf

边缘情况

• watermark 值包含逗号时应加引号。例如：preprocess="resize:w=200,text=demo,image/logo.png"。
• video/snapshots 的目标键不能包含文件扩展名。请使用 output/frames/frame，而不是 output/frames/frame.jpg。
• video/concat 在提交任务前总是会检查输入兼容性。仅当结果也通过 --output-path 下载时，才会额外验证本地 ffprobe 输出。
• 异步媒体轮询默认超时为 600 秒。使用 --timeout-seconds <n> 或 ALIBABA_CLOUD_ASYNC_TIMEOUT_SECONDS 可覆盖此设置。
• blindwatermark-extract 必须单独运行。blindwatermark-embed 可以接在图像基础操作之后，但必须是操作链中的最后一个操作。

---

错误恢复

错误	原因	恢复方法
连续两次出现 AccessDenied 或 InvalidArgument	配置或授权问题仍未解决；盲目重试可能导致诊断结果失实	立即停止。不要模拟输出，不要伪造日志，也不要继续重试 process.py。运行 aliyun configure list 验证当前生效的 CLI 配置文件，然后使用 python scripts/check_permissions.py 或相关 RAM 策略设置检查 RAM 权限。如果恢复过程中更改了依赖项、环境变量或 CLI 配置，请在再次尝试运行 process.py 之前重新运行 python scripts/load_env.py 和 aliyun configure list。
task_id: null	IMM 项目未绑定到存储桶，或 blindwatermark-extract 缺少 --imm-project / ALIBABA_CLOUD_IMM_PROJECT	先运行 python scripts/imm_admin.py auto-setup --bucket <b> --region <r>；对于 blindwatermark-extract，如有需要，也请传入 --imm-project <project>
NoSuchKey	OSS 中不存在源文件	检查 --source 路径，或先使用 --uri 和 upload 操作上传文件
AccessDenied / 403	RAM 策略缺少所需权限	运行 python scripts/check_permissions.py 进行诊断
异步超时 / 轮询超出限制	任务过大或队列积压	记录 task_id，告知用户稍后重试；不要使用 sleep 循环

---

Quick References

• Parameter details: references/image-basic-operations.md, references/image-imm-operations.md, references/video-operations.md, references/audio-operations.md
• RAM Permissions: references/ram-policies.md
• Format Support & Limitations: references/limitations.md
• IMM Administration: references/imm-admin.md