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

MUST（必須遵守，違反將導致錯誤或安全問題）

PREFER（推薦遵守，提升可靠性和安全性）

NEVER（禁止，將導致嚴重問題）

鏈路 1：媒體上傳

媒體上傳是使用 VOD 的第一步。VOD 提供多種上傳方式：

• 方式一：服務端上傳（適合本地檔案），通過調用 CreateUploadVideo 介面擷取上傳地址和憑證，然後使用 SDK 或 HTTP 方式上傳。適用於後端伺服器上傳情境。

  from alibabacloud_vod20170321.models import CreateUploadVideoRequest
  
  request = CreateUploadVideoRequest(
      file_name="video.mp4",       # 必須帶副檔名
      title="Demo Video",          # 必填，≤128字元
      template_group_id='xxx'      # 可選：指定轉碼模板組
  )
  response = client.create_upload_video(request)
  # 返回 VideoId + UploadAddress + UploadAuth
  # 使用 OSS SDK 上傳到 UploadAddress

  核心參數：調用 CreateUploadVideo 時，以下參數最為關鍵。

  參數	類型	必填	預設值	說明	約束層級
  FileName	String	是	—	待上傳的音視頻源檔案地址。[MUST] 必須帶副檔名（如 video_01.mp4），無副檔名導致上傳失敗。	MUST
  Title	String	是	—	音視頻標題。[MUST] 長度不超過 128 個字元。	MUST
  Description	String	否	—	音視頻描述，長度不超過 1024 個字元。	—
  CateId	Long	否	—	分類別識別碼。在控制台選擇組態管理 > 媒資管理配置 > 分類管理查看。	—
  Tags	String	否	—	標籤，最多 16 個，使用半形逗號分隔，單個標籤不超過 32 字元。	—
  TemplateGroupId	String	否	—	轉碼模板組 ID。[PREFER] 傳入後上傳完成自動觸發轉碼，無需額外 API 呼叫。	PREFER
  WorkflowId	String	否	—	工作流程 ID。傳入後上傳完成自動觸發工作流程。[NEVER] 不要同時依賴 WorkflowId 和 TemplateGroupId——同時傳入時僅 WorkflowId 生效。	—
  StorageLocation	String	否	—	儲存地址。不傳則上傳到預設儲存地址。在控制台選擇組態管理 > 媒資管理配置 > 儲存管理查看。	—
  CoverURL	String	否	—	自訂視頻封面的 URL。	—
  AppId	String	否	app-1000000	應用 ID。多應用體系下指定應用。	—

• 方式二：URL 拉取上傳（適合有公網 URL 的情境），調用 UploadMediaByURL 介面，傳入源檔案 URL，VOD 服務端自動拉取並上傳。適用於批量遷移或從第三方 URL 匯入媒體。[MUST] URL 必須經過 URL 編碼。[MUST] 僅支援華東 2（上海）地區。單次最多 20 個 URL。

  from alibabacloud_vod20170321.client import Client
  from alibabacloud_vod20170321.models import UploadMediaByURLRequest
  from alibabacloud_tea_openapi.models import Config
  import urllib.parse, os
  
  config = Config(
      access_key_id=os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'],
      access_key_secret=os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
      region_id=os.environ.get('ALIBABA_CLOUD_REGION_ID', 'cn-shanghai')
  )
  client = Client(config)
  
  # URL 必須編碼！
  source_url = "https://example.com/video.mp4"
  encoded_url = urllib.parse.quote(source_url, safe='')
  
  request = UploadMediaByURLRequest(
      upload_urls=encoded_url,
      upload_metadatas=f'[{{"SourceURL":"{encoded_url}","Title":"Demo Video"}}]',
      template_group_id='your_template_group_id'  # 可選：指定後自動轉碼
  )
  response = client.upload_media_by_url(request)
  print(f"VideoId: {response.body.upload_jobs[0].video_id}")

• 方式三：用戶端上傳（適合大檔案）：通過 AccessKey 或 STS 臨時憑證，在前端直接上傳視頻。

鏈路2：ApsaraVideo for Media Processing

ApsaraVideo for Media Processing模組提供音視頻的轉碼、截圖、AI 審核等處理能力。

• 轉碼：通過轉碼模板組（AddTranscodeTemplateGroup）配置轉碼參數，上傳視頻時指定 TemplateGroupId 或使用工作流程觸發自動轉碼。支援設定視頻編碼格式（H.264）、解析度（如 640×360）、碼率（如 400 kbps）等參數。

  觸發條件	機制
  上傳時指定 TemplateGroupId	上傳完成後自動按模板組轉碼
  上傳時指定 WorkflowId	上傳完成後觸發工作流程（優先順序高於 TemplateGroupId）
  均未指定	使用預設範本組（預設為"不轉碼"）

  事件通知（狀態感知）：

  事件類型	含義	Agent 應做的事
  FileUploadComplete	檔案上傳完成	記錄日誌
  StreamTranscodeComplete	單清晰度轉碼完成	最早可播放時機
  TranscodeComplete	全部清晰度轉碼完成	調用 GetPlayInfo

• 截圖：通過截圖模板（AddVodTemplate，TemplateType 為 Snapshot）配置截圖參數，支援普通截圖、雪碧圖等多種類型。

• 智能審核：通過 AI 模板（AddAITemplate，TemplateType 為 AIMediaAudit）組態稽核項（涉黃、涉暴、涉政等）和審核範圍（封面、視頻畫面、標題文本），上傳視頻後自動觸發審核。也支援調用 CreateAudit 進行人工審核。

  調用 AddAITemplate 建立 AI 審核模板時，核心參數如下：

  參數	類型	必填	預設值	說明	約束層級
  TemplateName	String	是	—	AI 模板名稱，最大 128 位元組。	MUST
  TemplateType	String	是	—	[MUST] 模板類型：AIMediaAudit（智能審核）、AIImage（智能封面）。值區分大小寫。	MUST
  TemplateConfig	String	是	—	[MUST] 模板配置（JSON 字串）。包含 AuditItem（審核項：terrorism、porn 等）、AuditRange（審核範圍：image-cover、text-title、video）、AuditAutoBlock（是否自動屏蔽：yes/no）。	MUST

• 智能封面：通過 AI 模板（TemplateType 為 AIImage）自動產生視頻封面圖。

鏈路3：分發播放

分發播放模組提供視頻的播放地址擷取和安全播放能力。

• 擷取播放地址：GetPlayInfo 擷取視頻播放 URL，支援指定輸出格式（MP4、FLV、HLS 等）和清晰度。[MUST] 僅在視頻 Status=Normal（轉碼完成）後調用，否則返回空結果。

  from alibabacloud_vod20170321.models import GetPlayInfoRequest
  
  request = GetPlayInfoRequest(
      video_id='your_video_id',    # 從上傳或回調獲得
      formats='mp4,m3u8',          # 可選：指定格式
      auth_timeout=3600            # 播放地址有效期間（秒）
  )
  response = client.get_play_info(request)
  for play_info in response.body.play_info_list.play_info:
      print(f"[{play_info.definition}] {play_info.play_url}")

• 擷取播放憑證：GetVideoPlayAuth 擷取播放憑證，用於加密播放（HLS 標準加密或阿里雲私人加密）。

• 網域名稱管理：AddVodDomain 添加加速網域名稱，BatchStartVodDomain 啟用網域名稱，BatchStopVodDomain 停用網域名稱。

  調用 AddVodDomain 添加加速網域名稱時，核心參數如下：

  參數	類型	必填	預設值	說明	約束層級
  DomainName	String	是	—	加速網域名稱，支援泛網域名稱（如 *.example.com）。[MUST] 網域名稱需已完成 ICP 備案（中國內地加速時）。	MUST
  Sources	String	是	—	[MUST] 回源地址清單（JSON 數組）。格式：[{"content":"1.1.X.X","type":"ipaddr","priority":"20","port":80}]。	MUST
  Scope	String	否	domestic	加速範圍：domestic（中國內地）、overseas（港澳台及海外）、global（Global Acceleration）。	—

媒資管理

媒資管理模組用於管理已上傳的音視頻和輔助媒資。核心操作包括：

• 查詢媒資資訊：GetVideoInfo（查詢單個視頻）、GetVideoInfos（批量查詢）、SearchMedia（搜尋媒資）

• 更新媒資資訊：UpdateVideoInfo（更新視頻資訊）、UpdateImageInfos（更新圖片資訊）

• 刪除媒資：DeleteVideo（刪除視頻）、DeleteAttachedMedia（刪除輔助媒資）

• 大量操作：BatchGetMediaInfos（批量擷取媒資資訊，最多 20 個）

媒資 ID（VideoId / MediaId / ImageId）是管理媒資的唯一標識。上傳視頻時 CreateUploadVideo 返回 VideoId；上傳輔助媒資時 CreateUploadAttachedMedia 返回 MediaId。[MUST] 儲存上傳返回的 ID，後續所有操作依賴此標識。