Integrate AI agents with Alibaba Cloud Video on Demand (VOD) by using an API documentation structure and quick-start guide designed for Large Language Models (LLMs).
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
AliyunVODFullAccesspermission.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 is2017-03-21.
Authentication directives for AI agents:
| Level | Directive |
| MUST | Create a dedicated RAM user for VOD API calls. Do not use the Alibaba Cloud root account credentials. |
| MUST | Grant the AliyunVODFullAccess permission to the RAM user before making any VOD API call. |
| MUST | Store credentials in environment variables: ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. |
| NEVER | Hard-code AccessKey ID or AccessKey Secret in source code, configuration files, or prompts. |
| PREFER | Use STS temporary credentials (SecurityToken + short-lived AccessKey) instead of long-lived AccessKey pairs for production workloads. |
| PREFER | Use the Alibaba Cloud SDK rather than raw HTTP requests. The SDK handles signing, retries, and credential management automatically. |
Default parameters and conventions
Before calling the VOD API, observe the following default values and constraints:
Default application ID [MUST know]:
app-1000000. If the multi-application system is not enabled, all API calls are associated with the default application. NEVER passAppIdunless you have explicitly enabled the multi-application system for your account.
Default storage [PREFER explicit]: If you do not specify a
StorageLocation, files are uploaded to the default storage address. PREFER specifyingStorageLocationexplicitly in API calls to avoid relying on the default.
Default transcoding template group [MUST know]: If you do not specify a
TemplateGroupIdand no workflow is associated, the default transcoding template (a no-transcoding template group) is used. This means the uploaded video is stored as-is without transcoding. MUST specifyTemplateGroupIdorWorkflowIdif you need the video transcoded after upload.
API call protocol [MUST]: MUST use HTTPS for all API calls to ensure secure data transfer. HTTP is supported but not recommended.
Request signature [MUST]: All API requests MUST include a valid signature. The signing method uses
HMAC-SHA1. SDKs handle signing automatically. NEVER attempt to call the API without a valid signature.
Summary of default parameter constraints:
| Parameter | Default | MUST / PREFER / NEVER |
AppId | app-1000000 | NEVER pass unless multi-application system is enabled |
StorageLocation | Account default storage | PREFER specifying explicitly |
TemplateGroupId | No transcoding | MUST specify if transcoding is required |
| Protocol | HTTPS/HTTP | MUST use HTTPS |
| Signature | HMAC-SHA1 | MUST include; NEVER bypass |
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.
Directives for AI agents consuming llms.txt:
| Level | Directive |
| MUST | Load the full llms.txt file on first interaction with VOD. Do not skip or partially read it. |
| MUST | Treat every item in the Common mistakes to avoid section as a hard constraint when generating code. |
| MUST | URL-encode Chinese characters when constructing sub-document URLs. Append the relative path from llms.txt to the base URL: https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/{relative_path}. |
| PREFER | Load module-specific sub-documents on demand rather than all at once. Fetch only the sub-document relevant to the current task. |
| NEVER | Generate VOD API code without first reading the relevant module sub-document from llms.txt. |
| NEVER | Assume API behaviors not explicitly documented in llms.txt or its sub-documents. |
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
CreateUploadVideooperation 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
UploadMediaByURLoperation 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. MUST include 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 specified, transcoding is automatically triggered after upload. MUST specify this or WorkflowId if transcoding is required. You can find this in the console by navigating to Configuration Management > Media Processing > Transcoding Template Groups. |
| WorkflowId | String | No | — | The workflow ID. If specified, the workflow is automatically triggered after upload. 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. NEVER pass this parameter unless the multi-application system is enabled. |
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)
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. MUST persist the returned ID immediately after upload — it is the only way to reference the asset in subsequent operations.
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 aTemplateGroupIdduring 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 (
AddVodTemplatewithTemplateTypeset toSnapshot). 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 (
AddAITemplatewithTemplateTypeset toAIMediaAudit). The review is automatically triggered after a video is uploaded. You can also callCreateAuditfor manual review.
Smart cover: Automatically generate a video cover by using an AI template (with
TemplateTypeset toAIImage).
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). MUST be one of these two values exactly. |
| TemplateConfig | String | Yes | — | The template configuration as a JSON string. MUST include 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
GetPlayInfoto get video playback URLs. You can specify the output format (such as MP4, FLV, or HLS) and definition.
Get playback credential: Call
GetVideoPlayAuthto get a playback credential for encrypted playback (either HLS standard encryption or Alibaba Cloud proprietary encryption).
Domain name management: Call
AddVodDomainto add an accelerated domain name,BatchStartVodDomainto enable it, andBatchStopVodDomainto 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. MUST be a domain you own and have verified. |
| Sources | String | Yes | — | The list of origin addresses as a JSON array. Format: [{"content":"1.1.1.1","type":"ipaddr","priority":"20","port":80}]. MUST include at least one origin address. |
| 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. | MUST verify your AccessKey configuration by running aliyun configure, or check the AccessKey status in the RAM console. |
| SignatureDoesNotMatch | The signature does not match the calculated result. | MUST enable SDK debug logs to troubleshoot: export ALIBABA_CLOUD_LOG_LEVEL=debug. PREFER using the SDK (which handles signing automatically) over manual signing. |
| InvalidParameter | The parameter is invalid. | MUST check whether request parameters meet the requirements (type, length, required fields) by referring to the documentation for each API operation. |
| Forbidden.AccessDenied | Insufficient permissions. | MUST confirm that the RAM user has been granted AliyunVODFullAccess. Verify by running aliyun ram ListPoliciesForUser --UserName <user>. |
| ServiceUnavailable | The service is temporarily unavailable. | MUST implement exponential backoff retry. NEVER retry immediately in a tight loop. |
| QuotaExceeded.UploadVideo | The number of uploaded videos has exceeded the quota. | MUST check your account's upload quota. Submit a ticket to request a quota increase if needed. |
| MediaNotFound | The media asset does not exist. | MUST 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. | MUST call GetVideoInfo to check the current status before retrying. The asset may be under review or still being transcoded. |
Error handling directives for AI agents:
| Level | Directive |
| MUST | Implement exponential backoff retry for ServiceUnavailable errors. |
| MUST | Check the media asset status with GetVideoInfo before retrying InvalidStatus.Media errors. |
| MUST | Validate all required parameters against the API documentation before making a call. |
| NEVER | Retry InvalidAccessKeyId.NotFound or Forbidden.AccessDenied errors without fixing the credential or permission issue first. |
| NEVER | Retry QuotaExceeded errors in a loop. Check the quota and request an increase instead. |
| PREFER | Use descriptive error messages in agent responses rather than exposing raw error codes to end users. |