Quick start: Upload a video with the client upload SDK

Updated at:

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.

Warning

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.

Important

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 access

Install 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.py

Verify 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

  1. Download the Upload_Demo.

  2. In the project directory, run:

    npm install
    npm run dev
  3. Open http://localhost:5173 in Chrome.

  4. To upload to your own VOD account, modify src/get-auth.ts and replace the demo auth URL with your AppServer address (for example, http://<your-lan-ip>:8000).

  5. 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

ipconfig getifaddr en0(en0 is Wi-Fi,en1 is wired).

System Setup → Network → Wi-Fi → Details → TCP/IP.

Windows

ipconfig(Viewing the IPv4 Address under the WLAN of the Wireless LAN Adapter).

Settings → Network and Internet → Wi-Fi → Properties.

Android

  1. Download the Upload_Demo.

  2. Open the project in Android Studio.

  3. Update the SDK version in build.gradle to 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
    }
  4. 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), use http://10.0.2.2:8000 instead.

  5. 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

ipconfig getifaddr en0(en0 is Wi-Fi,en1 is wired).

System Setup → Network → Wi-Fi → Details → TCP/IP.

Windows

ipconfig(Viewing the IPv4 Address under the WLAN of the Wireless LAN Adapter).

Settings → Network and Internet → Wi-Fi → Properties.

iOS

  1. Download the Upload_Demo.

  2. Open VODUploadDemo.xcworkspace in Xcode.

  3. Use the LAN IP from the section above. If you are using the iOS Simulator, use http://localhost:8000 instead.

  4. Configure the demo to use your AppServer address. In the demo project configuration file, replace the demo auth URL with your AppServer address.

  5. 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

  1. Check the VOD console: Go to the VOD console > Media Library > Audio/Video. You should see the video you just uploaded.

  2. 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.