面向智能體的入門指南 - ApsaraVideo VOD

本文檔面向希望通過AI智能體（Agent）接入阿里雲ApsaraVideo for VOD（VOD）服務的開發人員，提供LLM可消費的API文檔結構和快速入門指導。

你能完成什麼

通過本文檔，AI智能體可以：

理解 VOD 核心能力：通過結構化的模組概覽，快速瞭解 VOD 支援的功能（上傳、轉碼、播放、媒資管理等）。
擷取 API 呼叫知識：每個模組的 llms 檔案包含該模組的 API 巨集指令清單、參數說明和使用樣本，LLM 可直接從中學習如何調用 API。
掌握認證與鑒權：瞭解 VOD API 支援的認證方式（AccessKey 和 STS 臨時憑證），正確配置調用憑證。
處理常見錯誤：擷取常見錯誤碼及排查方法，使 AI 智能體具備自主排障能力。

前提條件

在使用 VOD API前，請確保已完成以下準備：

開通ApsaraVideo for VOD服務：在阿里雲控制台開通ApsaraVideo for VOD服務。
建立 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 拉取上傳。	媒體上傳概述
媒資管理	管理已上傳的音視頻、圖片和輔助媒資。支援查詢媒資資訊、更新中繼資料（標題、描述、分類、標籤）、刪除媒資、設定媒資狀態等操作。	媒資管理概述
ApsaraVideo for Media Processing	對音視頻進行轉碼、截圖、動圖產生、浮水印合成等處理。支援自訂轉碼模板組、工作流程編排和 AI 模板（智能審核、智能封面）。	ApsaraVideo for Media Processing概述
音視頻播放	通過控制台、播放器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	否	—	分類別識別碼。在控制台選擇組態管理> 媒資管理配置>分類管理查看。
Tags	String	否	—	標籤，最多 16 個，使用半形逗號分隔，單個標籤不超過 32 字元。
TemplateGroupId	String	否	—	轉碼模板組 ID。傳入後上傳完成自動觸發轉碼。在控制台選擇組態管理>ApsaraVideo for Media Processing>配置轉碼模板組查看.
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。

ApsaraVideo for Media Processing

ApsaraVideo for Media Processing模組提供音視頻的轉碼、截圖、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`（Global Acceleration）。

常見錯誤及排查

錯誤碼	描述	排查方法
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` 查看目前狀態後重試。