视频点播：面向智能体的入门指南

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	否	—	分类 ID。在控制台选择配置管理 > 媒资管理配置 > 分类管理查看。	—
  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：媒体处理

媒体处理模块提供音视频的转码、截图、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（全球加速）。	—

媒资管理

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

• 查询媒资信息：GetVideoInfo（查询单个视频）、GetVideoInfos（批量查询）、SearchMedia（搜索媒资）

• 更新媒资信息：UpdateVideoInfo（更新视频信息）、UpdateImageInfos（更新图片信息）

• 删除媒资：DeleteVideo（删除视频）、DeleteAttachedMedia（删除辅助媒资）

• 批量操作：BatchGetMediaInfos（批量获取媒资信息，最多 20 个）

媒资 ID（VideoId / MediaId / ImageId）是管理媒资的唯一标识。上传视频时 CreateUploadVideo 返回 VideoId；上传辅助媒资时 CreateUploadAttachedMedia 返回 MediaId。[MUST] 保存上传返回的 ID，后续所有操作依赖此标识。