AI agents: Getting started-ApsaraVideo VOD(VOD)-阿里云帮助中心

What you can achieve

An AI agent can use this document to:

Understand VOD core capabilities: Quickly explore core VOD features such as media upload, transcoding, playback, and media asset management through the structured module overview.
Learn to call APIs: Find module-specific documentation containing API operations, parameter descriptions, and usage examples through the llms.txt index.
Understand authentication and authorization: Configure credentials for VOD API calls by using supported authentication methods such as AccessKey and STS temporary credentials.
Handle common errors: Resolve issues independently by using the provided common error codes and troubleshooting methods.

Prerequisites

Before using the VOD API, complete the following steps:

Activate VOD: Activate Alibaba Cloud Video on Demand (VOD) in the Alibaba Cloud console.
Create an AccessKey: Create an AccessKey ID and AccessKey Secret in the RAM console. For security reasons, we recommend creating a dedicated RAM user for VOD API calls and granting the AliyunVODFullAccess permission.
Install an SDK: Use an Alibaba Cloud SDK to call the VOD API. The POP product code for VOD is vod, and the API version is 2017-03-21.

Default parameters and conventions

Before calling the VOD API, note the following default values and conventions:

Default application ID: app-1000000. If the multi-application system is not enabled, all API calls are associated with the default application.
Default storage: If you do not specify a StorageLocation, files are uploaded to the default storage address.
Default transcoding template group: If you do not specify a TemplateGroupId and no workflow is associated, the default transcoding template (a no-transcoding template group) is used.
API call protocol: Use HTTPS for all API calls to ensure secure data transfer.
Request signature: All API requests require signature verification. The signing method uses HMAC-SHA1. SDKs automatically handle signing.

llms.txt

The llms.txt file is an LLM-optimized index of VOD documentation hosted on Alibaba Cloud OSS. It reorganizes official documentation by scenario, API, and sub-document path, and includes a Common mistakes to avoid list to guide code generation. A coding agent can load the file all at once and expand sections on demand.

The base URL for accessing the index file is:

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

Relationship with the official documentation: llms.txt is an index. Sub-documents such as Media Upload/Upload from URL.md are condensed versions of key information from the official documentation. The VOD documentation team keeps their content consistent and synchronized with the official website.

VOD modules

VOD features are organized into modules, each corresponding to a set of API operations. The following table lists these modules with links to their documentation, also indexed in llms.txt. These links are designed for direct consumption by AI agents.

Module	Description	llms document link
Media upload	Upload audio, video, images, and auxiliary media assets using the console, client-side SDK, server-side API, or a URL.	Media Upload Overview
Media asset management	Manage uploaded media assets. Perform operations like querying information, updating metadata, deleting assets, and setting status.	Media Asset Management Overview
Media processing	Process audio and video files with features such as transcoding, snapshot capture, animated image generation, and watermark composition. Supports custom transcoding template groups, workflow orchestration, and AI templates for smart review and smart cover generation.	Media Processing Overview
Audio and video playback	Play audio and video content that has been uploaded and processed. Playback is available through the console, a Player SDK, or third-party players.	Audio and Video Playback
Media security	A security framework that prevents hotlinking, unauthorized downloads, and illegal distribution of audio and video content through access restriction, URL authentication, video encryption, and digital watermarks.	Media Security Overview
Media review	Smart review and manual review capabilities. Smart review automatically identifies non-compliant content (such as pornographic, violent, and political content) in audio and video, and supports custom AI review templates. Manual review provides APIs for creating review tasks and submitting results.	Smart review
Video AI	Automated analysis and processing of audio and video content, including smart review, tag recognition, DNA comparison, and cover generation.	Video AI Overview
Cloud editing	Cloud-based video editing capabilities. Use APIs to create editing projects, manage materials, and perform video composition.	Media Production (Cloud Editing)
CDN distribution and acceleration	Configure accelerated domain names, obtain playback URLs and playback credentials, and distribute and play audio and video. Supports secure playback features such as CDN acceleration, URL authentication, and DRM encryption.	CDN Distribution and Acceleration
Event notification	Receive notifications about media processing events, such as upload or transcoding completion, via HTTP callbacks or Message Service (MNS).	Event Notification
Data statistics	Query usage, monitor resource consumption, and perform statistical analysis to understand resource utilization.	Data Monitoring
Multi-application system	Create multiple applications under a single Alibaba Cloud account to logically isolate media assets, configurations, and permissions. Supports application-level control over media upload, playback, media asset management, and message callbacks.	Multi-application System
Server-side SDK	Use SDKs for Java, Python, PHP, and C/C++ to call APIs for media upload, management, and processing.	Server-side SDK
Live-to-VOD	Record a live stream in real time and automatically store it as an on-demand media asset for subsequent playback, management, and distribution.	Configure Live-to-VOD
Billing	Pay-as-you-go and subscription billing based on metrics such as storage capacity, traffic and bandwidth, transcoding duration, media management, and value-added services.	Billing Overview
Mini-series solution	A one-stop solution for mini-series production and operations based on VOD. It provides content production, media asset management, data insights, and efficient distribution and playback.	Mini-series Solution
Player SDK	An Alibaba Cloud-developed, full-platform audio and video playback tool for Web, Android, and iOS that provides stable and smooth on-demand and live streaming playback.	Player SDK Overview
AliPlayerKit	A low-code player UI framework for video services that offers extensible components and scenario-based solutions for quick integration with on-demand, live streaming, and other scenarios.	PlayerKits Overview
API reference	OpenAPI for the entire media asset lifecycle, supporting operations such as upload, management, processing, distribution, and playback.	API Overview

Media upload

VOD provides several methods for uploading media:

Server-side upload: Call the CreateUploadVideo operation to obtain an upload URL and credential, then upload the file using an SDK or via HTTP. This method is ideal for backend server uploads.
Client-side upload: Upload videos directly from the client by using an AccessKey or an STS temporary credential.
Upload from URL: Call the UploadMediaByURL operation and provide the source file URL. The VOD service automatically pulls and uploads the file. This method is ideal for bulk migrations or importing media from third-party URLs.

Key parameters

The following parameters are critical when calling CreateUploadVideo:

Parameter	Type	Required	Default	Description
FileName	String	Yes	—	The full path and file name of the source media file, including the extension (e.g., `video_01.mp4`).
Title	String	Yes	—	The media title. Maximum 128 characters.
Description	String	No	—	The description of the audio or video. Maximum length: 1,024 characters.
CateId	Long	No	—	The category ID. You can find this ID in the console: Configuration Management > Media Asset Management Configuration > Category Management.
Tags	String	No	—	Up to 16 comma-separated tags. Each tag can be a maximum of 32 characters.
TemplateGroupId	String	No	—	The transcoding template group ID. If you specify this parameter, transcoding is automatically triggered after the upload is complete. You can find this in the console by navigating to Configuration Management > Media Processing > Transcoding Template Groups.
WorkflowId	String	No	—	The workflow ID. If you specify this parameter, the workflow is automatically triggered after the upload is complete. If both `WorkflowId` and `TemplateGroupId` are specified, `WorkflowId` takes precedence.
StorageLocation	String	No	—	The storage address. If not specified, the file is uploaded to the default storage address. You can find this in the console by navigating to Configuration Management > Media Asset Management Configuration > Storage.
CoverURL	String	No	—	The URL of a custom video cover.
AppId	String	No	`app-1000000`	The application ID. Specifies the application in a multi-application system.

Media asset management

Manage uploaded audio, video, and auxiliary media assets. Core operations include:

Query media asset information: GetVideoInfo (queries a single video), GetVideoInfos (queries multiple videos in bulk), SearchMedia (searches for media assets)
Update media asset information: UpdateVideoInfo (updates video information), UpdateImageInfos (updates image information)
Delete media assets: DeleteVideo (deletes videos), DeleteAttachedMedia (deletes auxiliary media assets)
Bulk operations: BatchGetMediaInfos (retrieves information for up to 20 media assets at a time)

Note

The media ID (VideoId, MediaId, or ImageId) is the unique identifier for managing media assets. When you upload a video, CreateUploadVideo returns a VideoId. When you upload an auxiliary media asset, CreateUploadAttachedMedia returns a MediaId.

Media processing

Audio and video transcoding, snapshot capture, and AI review capabilities.

Transcoding: Configure transcoding parameters by using a transcoding template group (AddTranscodeTemplateGroup). You can trigger automatic transcoding by specifying a TemplateGroupId during upload or by using a workflow. You can set parameters such as video codec (for example, H.264), resolution (for example, 640×360), and bitrate (for example, 400 kbps).
Snapshot capture: Configure snapshot parameters by using a snapshot template (AddVodTemplate with TemplateType set to Snapshot). It supports various types, including standard snapshots and sprites.
Smart review: Configure review items (such as pornographic, violent, and political content) and scopes (cover image, video content, and title text) by using an AI template (AddAITemplate with TemplateType set to AIMediaAudit). The review is automatically triggered after a video is uploaded. You can also call CreateAudit for manual review.
Smart cover: Automatically generate a video cover by using an AI template (with TemplateType set to AIImage).

Smart review parameters

When calling AddAITemplate to create an AI review template:

Parameter	Type	Required	Default	Description
TemplateName	String	Yes	—	The name of the AI template. Maximum length: 128 bytes.
TemplateType	String	Yes	—	The template type: `AIMediaAudit` (smart review) or `AIImage` (smart cover).
TemplateConfig	String	Yes	—	The template configuration as a JSON string. It includes `AuditItem` (review items such as `terrorism` and `porn`), `AuditRange` (review scopes such as `image-cover`, `text-title`, and `video`), and `AuditAutoBlock` (whether to automatically block content: `yes`/`no`).

Distribution and playback

Video playback URL retrieval and secure playback capabilities.

Get playback URLs: Call GetPlayInfo to get video playback URLs. You can specify the output format (such as MP4, FLV, or HLS) and definition.
Get playback credential: Call GetVideoPlayAuth to get a playback credential for encrypted playback (either HLS standard encryption or Alibaba Cloud proprietary encryption).
Domain name management: Call AddVodDomain to add an accelerated domain name, BatchStartVodDomain to enable it, and BatchStopVodDomain to disable it.

Domain configuration parameters

When calling AddVodDomain to add an accelerated domain name:

Parameter	Type	Required	Default	Description
DomainName	String	Yes	—	The accelerated domain name. Wildcard domain names are supported, such as `*.example.com`.
Sources	String	Yes	—	The list of origin addresses as a JSON array. Format: `[{"content":"1.1.1.1","type":"ipaddr","priority":"20","port":80}]`.
Scope	String	No	`domestic`	The acceleration scope: `domestic` (Chinese mainland), `overseas` (regions outside the Chinese mainland, including Hong Kong, Macao, and Taiwan), or `global` (global acceleration).

Common errors and troubleshooting

Error code	Description	Troubleshooting
InvalidAccessKeyId.NotFound	The specified AccessKey ID does not exist.	Use `aliyun configure` to verify your AccessKey configuration, or check the AccessKey status in the RAM console.
SignatureDoesNotMatch	The signature does not match the calculated result.	Enable SDK debug logs to troubleshoot the signature issue: `export ALIBABA_CLOUD_LOG_LEVEL=debug`.
InvalidParameter	The parameter is invalid.	Check whether the request parameters meet the requirements (such as type, length, and whether they are required) by referring to the documentation for each API.
Forbidden.AccessDenied	Insufficient permissions.	Confirm that the RAM user has been granted the required VOD permissions, such as `AliyunVODFullAccess`. You can check the granted policies by running `aliyun ram ListPoliciesForUser --UserName <user>`.
ServiceUnavailable	The service is temporarily unavailable.	Temporary service issue. Retry the request with exponential backoff.
QuotaExceeded.UploadVideo	The number of uploaded videos has exceeded the quota.	Check your account's upload quota. You can submit a ticket to request a quota increase.
MediaNotFound	The media asset does not exist.	Confirm that the `VideoId` or `MediaId` is correct and that the media asset has not been deleted.
InvalidStatus.Media	The media asset is in a state that is invalid for this operation.	The asset is in a state that prevents this operation (e.g., 'under review'). Call `GetVideoInfo` to check the current status before retrying.