Quick start: Upload a video with the client upload SDK
This quickstart shows you how to upload a video using the ApsaraVideo VOD client upload SDK. You will set up a local AppServer, run an SDK demo on your chosen platform, upload a video file, and verify that it appears in the VOD console.
Prerequisites
An Alibaba Cloud account with ApsaraVideo VOD activated.
An AccessKey ID and AccessKey secret. Create one in the RAM console if you do not have one.
The AccessKey secret is displayed only once during creation. Save it immediately.
Your VOD region (for example,
cn-shanghai). Check the region selector in the top-right corner of the VOD console. The region must match the one configured in the AppServer.Python 3 installed (for the AppServer).
Node.js and npm installed (for the Web demo).
Android Studio installed (for the Android demo).
Xcode installed (for the iOS demo).
Limits
Supported formats — MP4 is fully supported. Other video formats may not be transcoded correctly. Verify your workflow with an MP4 file first.
SDK version — Use the latest stable version of the upload SDK for your platform. Check the release notes linked in each platform section below for the current version.
Step 1: Set up the AppServer
The AppServer is a backend service you deploy locally. It holds your AccessKey pair and exchanges it for short-lived upload credentials, which are then passed to the client. This avoids embedding credentials in client-side code.
This example uses hardcoded credentials for demonstration only. For a production environment, use environment variables or a secrets manager.
Create a file named app_server.py with the following content:
from flask import Flask, request, jsonify
from aliyunsdkcore.client import AcsClient
from aliyunsdkvod.request.v20170321 import CreateUploadVideoRequest, RefreshUploadVideoRequest
app = Flask(__name__)
ACCESS_KEY_ID = "your-access-key-id"
ACCESS_KEY_SECRET = "your-access-key-secret"
REGION_ID = "cn-shanghai" # Replace with your VOD region
client = AcsClient(ACCESS_KEY_ID, ACCESS_KEY_SECRET, REGION_ID)
@app.route("/upload/auth")
def create_upload_auth():
title = request.args.get("title", "test")
filename = request.args.get("filename", "test.mp4")
req = CreateUploadVideoRequest.CreateUploadVideoRequest()
req.set_Title(title)
req.set_FileName(filename)
req.set_accept_format("JSON")
resp = client.do_action_with_exception(req)
return app.response_class(resp, mimetype="application/json")
@app.route("/upload/refresh")
def refresh_upload_auth():
video_id = request.args.get("videoId")
req = RefreshUploadVideoRequest.RefreshUploadVideoRequest()
req.set_VideoId(video_id)
req.set_accept_format("JSON")
resp = client.do_action_with_exception(req)
return app.response_class(resp, mimetype="application/json")
if __name__ == "__main__":
app.run(host="0.0.0.0", port=8000) # host must be 0.0.0.0 for device accessInstall dependencies and start the server:
python3 -c "import sys; print(sys.executable)"
python3 -m pip install flask aliyun-python-sdk-core aliyun-python-sdk-vod
python3 app_server.pyVerify the server is running by visiting http://localhost:8000/upload/auth?title=test&filename=test.mp4 in a browser. A successful response returns JSON containing UploadAuth and UploadAddress fields. If you see a connection error, check that the AppServer terminal shows no Python import errors.
Step 2: Run the client demo
Choose a platform below based on your development environment. If you are unsure, start with the Web demo — it requires the fewest prerequisites.
Web
Web
Download the Upload_Demo.
In the project directory, run:
npm install npm run devOpen
http://localhost:5173in Chrome.To upload to your own VOD account, modify
src/get-auth.tsand replace the demo auth URL with your AppServer address (for example,http://<your-lan-ip>:8000).Select a video file and click Start Upload. The demo displays "Upload Complete" with the video ID when the upload succeeds.
Android
Obtain the AppServer address
The client-side demo must know the AppServer’s network address in order to obtain the upload credentials.
Emulator scenarios: The Android Studio AVD emulator uses 10.0.2.2, while the Genymotion emulator uses 10.0.3.2.
Real-device scenario: You need to obtain the computer’s local network IP address, and both the phone and the computer must be on the same Wi‑Fi subnet. For Wi‑Fi debugging, use the computer’s LAN IP; for USB debugging, use localhost (you must first run `adb reverse tcp:8000 tcp:8000`).
Query the computer’s local network IP:
System | Command-line mode | Graphical user interface mode |
macOS |
| System Setup → Network → Wi-Fi → Details → TCP/IP. |
Windows |
| Settings → Network and Internet → Wi-Fi → Properties. |
Android
Download the Upload_Demo.
Open the project in Android Studio.
Update the SDK version in
build.gradleto the latest stable release. See the Release notes for the upload SDK for Android for the current version.repositories { mavenCentral() maven { url "https://maven.aliyun.com/repository/public" } } dependencies { implementation 'com.aliyun.vodupload:upload:latest-version' // Replace with the version from the release notes }Configure the demo to use your AppServer address. In the demo project configuration file, replace the demo auth URL with
http://<your-lan-ip>:8000, using the LAN IP from the section above. If you are using an Android emulator (AVD), usehttp://10.0.2.2:8000instead.Build and run. Select a video file and click Start Upload. The demo displays "Upload Complete" with the video ID when the upload succeeds.
iOS
Obtain the AppServer address
The client-side demo must know the AppServer’s network address in order to obtain the upload credentials.
Emulator scenarios: iOS simulator using localhost or 127.0.0.1
Real-device scenario: The real machine http:// <computer LAN IP>:8000, the LAN IP address of the computer needs to be obtained, and the mobile phone/computer must be on the same Wi-Fi network segment.
Query the computer’s local network IP:
System | Command-line mode | Graphical user interface mode |
macOS |
| System Setup → Network → Wi-Fi → Details → TCP/IP. |
Windows |
| Settings → Network and Internet → Wi-Fi → Properties. |
iOS
Download the Upload_Demo.
Open
VODUploadDemo.xcworkspacein Xcode.Use the LAN IP from the section above. If you are using the iOS Simulator, use
http://localhost:8000instead.Configure the demo to use your AppServer address. In the demo project configuration file, replace the demo auth URL with your AppServer address.
Build and run. Select a video file and click Start Upload. The demo displays "Upload Complete" with the video ID when the upload succeeds.
Step 3: Verify the upload
Check the VOD console: Go to the VOD console > Media Library > Audio/Video. You should see the video you just uploaded.
Verify playback:
Option A: Click the video in the console to play it directly.
Option B: In the video's Actions column, click Manage > Video URL > Copy URL, and play it in any player.
Option C: Call the GetPlayInfo API to retrieve the playback URL.
FAQ
Q1: The official demo fails to build.
The demo dependencies and Gradle versions may be outdated. We recommend building a minimal project from scratch following the SDK integration guide, or check that your Gradle, AGP, and dependency versions match.
Q2: I lost my AccessKey secret.
The secret is shown only once during creation. If lost, create a new AccessKey pair in the RAM console and replace the credentials in your AppServer.
Q3: How do I confirm my VOD region?
Check the region selector in the top-right corner of the VOD console. The region you configure as REGION_ID in the AppServer must match (for example, cn-shanghai), otherwise authentication will fail.
Q4: No module named ... error when running AppServer.
macOS may have multiple Python installations. pip3 install may install to one interpreter, while python3 app_server.py runs another. Use python3 -c "import sys; print(sys.executable)" to confirm the interpreter, then use python3 -m pip install with the same interpreter, or run /usr/bin/python3 app_server.py directly.
Q5: Device cannot connect to AppServer.
See the LAN IP guidance in Step 1. AppServer logs print to the terminal where you started it — incoming requests will show access records. If no records appear, the request never reached the server.
Q6: Non-MP4 video shows no status change after upload or fails to play.
Some uncommon formats may not be supported and the console may not give clear format hints. Verify the workflow first with an MP4 file, then troubleshoot the source format.