ApsaraVideo VOD:Upload from clients

Method 1: Upload URL and credential (recommended)

This method provides simpler configuration, higher security with per-video permission control, and more flexible response parameters. It is suitable for the majority of client upload scenarios.

Stage 1: Obtain upload URL and credential

The client sends an HTTP request to your AppServer with media metadata (such as Title, FileName, CateId, Tags). Your AppServer uses its AK/SK to call CreateUploadVideo on VOD, which returns three key values: UploadAuth (temporary upload token), UploadAddress (target OSS path, Base64-encoded), and VideoId (unique media identifier). Your AppServer forwards these to the client.

Stage 2: Construct upload parameters and upload directly to OSS

The client initializes the upload SDK with UploadAuth, UploadAddress, and VideoId, along with the local file path. The SDK automatically parses the UploadAddress to obtain the OSS Endpoint and Object Key, then uploads the file directly to OSS. This process supports multipart upload and resumable upload. Files go directly from the client to OSS without passing through your server.

Stage 3: Upload result

After OSS completes the upload, the SDK triggers the onUploadSucceed callback, carrying the VideoId. VOD automatically detects the upload completion and triggers transcoding and processing pipelines based on your configured TemplateGroupId or WorkflowId. You can also configure event callbacks (HTTP or MNS) to receive FileUploadComplete event notifications.

Method 2: STS Token

Stage 1: Obtain STS temporary credentials

The client requests temporary credentials from your AppServer. Your AppServer uses its AK/SK to call AssumeRole on STS, obtaining a time-limited set of AccessKeyId, AccessKeySecret, and SecurityToken (validity: 900 to 3,600 seconds), which are returned to the client.

Stage 2: Obtain upload credentials and upload (SDK handles automatically)

The client initializes the upload SDK with the STS Token. The SDK automatically carries the STS Token to call CreateUploadVideo (with Title, FileName, and other parameters), obtains UploadAuth, UploadAddress, and VideoId, then automatically executes multipart upload. The entire process is transparent to the developer — no manual VOD API calls are needed.

Stage 3: Upload result

Same as Method 1 — the SDK triggers onUploadSucceed with VideoId, and VOD processes the file automatically.

Multipart upload

Multipart upload splits large files into smaller parts and uploads them in parallel. This improves both upload speed and reliability for large media files, since a network failure only requires retrying the failed parts rather than re-uploading the entire file. Multipart upload is enabled by default across all client upload SDKs and requires no additional configuration.

Resumable upload

Resumable upload allows the SDK to continue an interrupted upload from the last successfully uploaded part instead of restarting from the beginning. When a network disconnection, app backgrounding, or device sleep interrupts an upload, the SDK stores checkpoint data internally. Once the connection is restored and the app resumes, the SDK automatically resumes from the checkpoint without developer intervention.

Upload control

The upload SDK provides programmatic APIs to start, stop, pause, and resume individual uploads. This is useful when you need to respect user-initiated actions, such as canceling an upload when the user navigates away, or manage upload concurrency in batch scenarios. You control the upload lifecycle entirely through SDK method calls.

Progress callbacks

The SDK exposes granular progress callbacks that report the percentage of data uploaded for each file. Use these callbacks to update progress bars, display upload speeds, or trigger conditional logic, such as disabling certain UI elements while an upload is in progress. Progress callbacks fire at regular intervals during the upload, providing real-time visibility into transfer status.

Network switching

Mobile clients frequently transition between Wi-Fi and cellular networks. The SDK supports pausing and resuming uploads to handle these transitions. To avoid consuming mobile data, call the pause method when the device switches to a mobile network and call the resume method when Wi-Fi is restored. Your application must implement the network transition detection logic.

Batch upload

The SDK manages an upload queue that supports adding, removing, canceling, resuming, and traversing multiple files. You can clear the entire queue or manipulate individual entries. Batch upload is useful in scenarios where users select multiple media files at once, such as a photo gallery upload, and the SDK schedules them sequentially or in parallel based on available resources.

Metadata support

When obtaining upload credentials, you can attach metadata to the media asset being uploaded. Supported metadata fields include Title, Tags, CateId, CoverURL, TemplateGroupId, and WorkflowId. Setting metadata at the credential stage ensures that the media asset is immediately associated with the correct category, tags, and processing workflow upon upload completion, eliminating the need for a separate API call to update media properties.

Privacy compliance

The client upload SDK is designed to be embedded in applications distributed through app stores. The SDK collects no personal data. For compliance requirements when distributing apps with SDK integrations, refer to the Service Agreement.

Billing

The client upload SDK itself is free to use. Costs are associated with the ApsaraVideo VOD resources consumed during and after upload: