面向智能体的入门指南-视频点播(VOD)-阿里云帮助中心

本文档面向希望通过AI智能体（Agent）接入阿里云视频点播（VOD）服务的开发者，提供LLM可消费的API文档结构和快速入门指导。

你能完成什么

通过本文档，AI智能体可以：

理解 VOD 核心能力：通过结构化的模块概览，快速了解 VOD 支持的功能（上传、转码、播放、媒资管理等）。
获取 API 调用知识：每个模块的 llms 文件包含该模块的 API 操作列表、参数说明和使用示例，LLM 可直接从中学习如何调用 API。
掌握认证与鉴权：了解 VOD API 支持的认证方式（AccessKey 和 STS 临时凭证），正确配置调用凭证。
处理常见错误：获取常见错误码及排查方法，使 AI 智能体具备自主排障能力。

前提条件

在使用 VOD API前，请确保已完成以下准备：

开通视频点播服务：在阿里云控制台开通视频点播服务。
创建 AccessKey：在RAM 控制台创建 AccessKey ID 和 AccessKey Secret。出于安全考虑，建议为 VOD API 调用创建专用的 RAM 用户，并授予 AliyunVODFullAccess 权限。
安装 SDK：推荐使用阿里云SDK调用 VOD API。VOD 的 POP 产品代码为 vod，API 版本为 2017-03-21。

默认参数与约定

在调用 VOD API 前，需了解以下默认值和约定：

默认应用 ID：app-1000000。未开通多应用体系时，所有 API 调用归属到默认应用。
默认存储：不指定 StorageLocation 时，上传到默认存储地址。
默认转码模板组：不指定 TemplateGroupId 且未绑定工作流时，使用默认转码模板（不转码模板组）。
API 调用协议：支持 HTTPS，推荐使用 HTTPS 以保证传输安全。
请求签名：所有 API 请求需要进行签名验证，签名方法使用 HMAC-SHA1。SDK 会自动处理签名。

llms.txt简介

llms.txt 是VOD团队针对大语言模型（LLM）优化的文档索引文件，托管于阿里云OSS。它将官方VOD文档按场景、API、子文档路径重组，并提取Common mistakes to avoid清单作为代码生成的硬性约束，供Coding Agent一次性加载、按需展开。

索引文件的访问基础URL：

https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/llms.txt

与官方帮助文档的关系：llms.txt 是索引层，子文档（如 媒体上传/URL拉取上传.md）是对官方帮助文档关键信息的提炼，与官网上的同名文档内容一致，由VOD文档团队同步维护。

VOD 模块概览

VOD 功能按模块组织，每个模块对应一组相关的 API 操作，你可以在llms.txt查看完整文件列表，或从下表获取。下表列出各模块及对应的 llms 文档链接，供 AI 智能体直接读取：

模块	介绍	llms 文档链接
媒体上传	提供多种方式将音视频文件、图片及辅助媒资（水印、字幕、素材）上传至点播存储。支持控制台上传、客户端 SDK 上传、服务端 API 上传和 URL 拉取上传。	媒体上传概述
媒资管理	管理已上传的音视频、图片和辅助媒资。支持查询媒资信息、更新元数据（标题、描述、分类、标签）、删除媒资、设置媒资状态等操作。	媒资管理概述
媒体处理	对音视频进行转码、截图、动图生成、水印合成等处理。支持自定义转码模板组、工作流编排和 AI 模板（智能审核、智能封面）。	媒体处理概述
音视频播放	通过控制台、播放器SDK或第三方播放器，对已上传并处理完成的音视频内容进行播放。	播放音视频
媒体安全	通过访问限制、URL鉴权、视频加密、数字水印等机制，防止音视频内容被盗链、非法下载和传播的安全保护体系。	媒体安全概述
媒体审核	提供智能审核和人工审核能力。智能审核可自动识别音视频中的违规内容（涉黄、涉暴、涉政等），支持自定义 AI 审核模板。人工审核提供审核任务创建和审核结果提交接口。	智能审核
视频AI	对音视频内容进行智能审核、标签识别、DNA比对、封面生成等自动化分析与处理。	视频AI概述
云剪辑	提供云剪辑能力，支持通过 API 创建剪辑工程、管理素材、合成视频。	媒体生产（云剪辑）
CDN分发加速	配置加速域名、获取播放地址和播放凭证，实现音视频的分发与播放。支持 CDN 加速、URL 鉴权、DRM 加密等安全播放能力。	CDN分发加速
事件通知	媒资上传、转码、审核等处理完成后，通过HTTP回调或轻量消息队列（MNS）向用户主动推送处理结果。	事件通知
数据统计	查询用量、监控资源使用情况、统计分析等，帮助了解服务使用量和资源消耗。	数据监控
多应用体系	同一阿里云账号下创建多个应用，实现音视频等媒资、配置及权限的逻辑隔离，支持媒体上传、播放、媒资管理和消息回调的分应用管控。	多应用体系
服务端SDK	面向Java、Python、PHP、C/C++等语言提供的开发工具包，用于调用API实现媒资上传、管理及处理等功能。	服务端SDK
直播转点播	将直播流实时录制并自动存储为点播媒资，便于后续回看、管理与分发。	配置直播转点播
计费	基于存储容量、流量带宽、转码时长、媒体管理及增值服务等维度按量计费或包年包月。	计费概述
微短剧解决方案	基于点播服务，提供内容生产、媒资管理、数据洞察、高效分发及播放的一站式短剧内容生产与运营方案。	微短剧解决方案
播放器SDK	阿里云自研的全端音视频播放工具，支持Web、Android、iOS等多平台，提供稳定流畅的点播与直播播放能力。	播放器 SDK 概述
AliPlayerKit	面向视频业务的低代码播放器UI架构，提供可扩展的组件与场景化解决方案，支持点播、直播等多场景快速接入。	PlayerKits概述
API参考	媒资全生命周期的OpenAPI，支持上传、管理、处理、分发与播放等操作。	API概览

媒体上传

媒体上传是使用 VOD 的第一步。VOD 提供多种上传方式：

服务端上传：通过调用 CreateUploadVideo 接口获取上传地址和凭证，然后使用 SDK 或 HTTP 方式上传。适用于后端服务器上传场景。
客户端上传：通过 AccessKey 或 STS 临时凭证，在前端直接上传视频。
URL 拉取上传：调用 UploadMediaByURL 接口，传入源文件 URL，VOD 服务端自动拉取并上传。适用于批量迁移或从第三方 URL 导入媒体。

核心参数

调用 CreateUploadVideo 时，以下参数最为关键：

参数	类型	必填	默认值	说明
FileName	String	是	—	待上传的音视频源文件地址，必须带扩展名（如 `video_01.mp4`）。
Title	String	是	—	音视频标题，长度不超过 128 个字符。
Description	String	否	—	音视频描述，长度不超过 1024 个字符。
CateId	Long	否	—	分类 ID。在控制台选择配置管理> 媒资管理配置>分类管理查看。
Tags	String	否	—	标签，最多 16 个，使用半角逗号分隔，单个标签不超过 32 字符。
TemplateGroupId	String	否	—	转码模板组 ID。传入后上传完成自动触发转码。在控制台选择配置管理>媒体处理>配置转码模板组查看.
WorkflowId	String	否	—	工作流 ID。传入后上传完成自动触发工作流。如果同时传递了 WorkflowId 和 TemplateGroupId，以 WorkflowId 为准.
StorageLocation	String	否	—	存储地址。不传则上传到默认存储地址。在控制台选择配置管理>媒资管理配置>存储管理查看。
CoverURL	String	否	—	自定义视频封面的 URL。
AppId	String	否	`app-1000000`	应用 ID。多应用体系下指定应用。

媒资管理

媒资管理模块用于管理已上传的音视频和辅助媒资。核心操作包括：

查询媒资信息：GetVideoInfo（查询单个视频）、GetVideoInfos（批量查询）、SearchMedia（搜索媒资）
更新媒资信息：UpdateVideoInfo（更新视频信息）、UpdateImageInfos（更新图片信息）
删除媒资：DeleteVideo（删除视频）、DeleteAttachedMedia（删除辅助媒资）
批量操作：BatchGetMediaInfos（批量获取媒资信息，最多 20 个）

说明

媒资 ID（VideoId / MediaId / ImageId）是管理媒资的唯一标识。上传视频时 CreateUploadVideo 返回 VideoId；上传辅助媒资时 CreateUploadAttachedMedia 返回 MediaId。

媒体处理

媒体处理模块提供音视频的转码、截图、AI 审核等处理能力。

转码：通过转码模板组（AddTranscodeTemplateGroup）配置转码参数，上传视频时指定 TemplateGroupId 或使用工作流触发自动转码。支持设置视频编码格式（H.264）、分辨率（如 640×360）、码率（如 400 kbps）等参数。
截图：通过截图模板（AddVodTemplate，TemplateType 为 Snapshot）配置截图参数，支持普通截图、雪碧图等多种类型。
智能审核：通过 AI 模板（AddAITemplate，TemplateType 为 AIMediaAudit）配置审核项（涉黄、涉暴、涉政等）和审核范围（封面、视频画面、标题文本），上传视频后自动触发审核。也支持调用 CreateAudit 进行人工审核。
智能封面：通过 AI 模板（TemplateType 为 AIImage）自动生成视频封面图。

智能审核核心参数

调用 AddAITemplate 创建 AI 审核模板时：

参数	类型	必填	默认值	说明
TemplateName	String	是	—	AI 模板名称，最大 128 字节。
TemplateType	String	是	—	模板类型：`AIMediaAudit`（智能审核）、`AIImage`（智能封面）。
TemplateConfig	String	是	—	模板配置（JSON 字符串）。包含 AuditItem（审核项：`terrorism`、`porn` 等）、AuditRange（审核范围：`image-cover`、`text-title`、`video`）、AuditAutoBlock（是否自动屏蔽：`yes`/`no`）。

分发播放

分发播放模块提供视频的播放地址获取和安全播放能力。

获取播放地址：GetPlayInfo 获取视频播放 URL，支持指定输出格式（MP4、FLV、HLS 等）和清晰度。
获取播放凭证：GetVideoPlayAuth 获取播放凭证，用于加密播放（HLS 标准加密或阿里云私有加密）。
域名管理：AddVodDomain 添加加速域名，BatchStartVodDomain 启用域名，BatchStopVodDomain 停用域名。

域名配置核心参数

调用 AddVodDomain 添加加速域名时：

参数	类型	必填	默认值	说明
DomainName	String	是	—	加速域名，支持泛域名（如 `*.example.com`）。
Sources	String	是	—	回源地址列表（JSON 数组）。格式：`[{"content":"1.1.1.1","type":"ipaddr","priority":"20","port":80}]`。
Scope	String	否	`domestic`	加速范围：`domestic`（中国大陆）、`overseas`（港澳台及海外）、`global`（全球加速）。

常见错误及排查

错误码	描述	排查方法
InvalidAccessKeyId.NotFound	指定的 AccessKey ID 不存在	使用 `aliyun configure` 验证 AK 配置，或在 RAM 控制台检查 AccessKey 状态。
SignatureDoesNotMatch	签名与计算结果不匹配	开启 SDK DEBUG 日志排查签名问题：`export ALIBABA_CLOUD_LOG_LEVEL=debug`。
InvalidParameter	参数不合法	检查请求参数是否符合要求（类型、长度、必填等），参考各 API 的文档说明。
Forbidden.AccessDenied	权限不足	确认 RAM 用户已被授予 VOD 相关权限（如 `AliyunVODFullAccess`），可通过 `aliyun ram ListPoliciesForUser --UserName <user>` 检查已授权策略。
ServiceUnavailable	服务暂时不可用	VOD 服务临时异常，建议实现指数退避重试后重试。
QuotaExceeded.UploadVideo	上传视频数量超过配额	检查账号的上传配额限制，可提交工单申请提升配额。
MediaNotFound	媒资不存在	确认 VideoId/MediaId 正确，确认媒资未被删除。
InvalidStatus.Media	媒资状态不合法	媒资可能处于审核中、转码中等状态，调用 `GetVideoInfo` 查看当前状态后重试。