All Products
Document Center

Short video upload

Last Updated: May 27, 2020


The short video upload object VODSVideoUploadClient is applicable for concurrent upload of a video and the video thumbnail, simplifying the process of calling API operations. The short video upload object is implemented by encapsulating the VODUploadClient object. The short video upload object supports upload through STS only. If you want to upload short videos to ApsaraVideo for VOD by using the upload URL and credential, use the VODUploadClient object to respectively upload the thumbnail and video.


  1. Request for the STS credential. For more information, see relevant documentation.
  2. Initialize the upload instance.
  3. Set callbacks for reporting the upload progress and all upload statuses, including upload success, upload failure, and credential expiration.
  4. Start the upload.
  5. Handle callbacks.

1. Request for the STS credential

The client sends an upload request to the AppServer. The AppServer sends a request to STS to obtain a temporary credential. If the request succeeds, the AppServer receives the STS credential and returns it to the client.

2. Initialize the upload instance

First, declare a VODSVideoUploadClient object. It must not be a local variable.

  1. // 1. Initializes the short video upload object.
  2. VODSVideoUploadClient vodsVideoUploadClient = new VODSVideoUploadClientImpl(this.getApplicationContext());
  3. vodsVideoUploadClient.init();
  1. // 2. Constructs upload parameters.
  2. // Ensure that the parameter settings are valid. Otherwise, an exception is thrown in the SDK.
  3. // Ensure that the path of the file to be uploaded is valid. In addition, you need to obtain the read and write permissions on the file because sensitive permissions need to be dynamically requested in Android 6.0 or later.
  4. VodHttpClientConfig vodHttpClientConfig = new VodHttpClientConfig.Builder()
  5. .setMaxRetryCount(2)// Specifies the maximum number of retry times.
  6. .setConnectionTimeout(15 * 1000)// Specifies the connection timeout period.
  7. .setSocketTimeout(15 * 1000)// Specifies the socket timeout period.
  8. .build();
  9. // Constructs the short video information, including the description, title, and details.
  10. SvideoInfo svideoInfo = new SvideoInfo();
  11. svideoInfo.setTitle(new File(videoPath).getName());// Specifies the title.
  12. svideoInfo.setDesc("");// Specifies the description.
  13. svideoInfo.setCateId(1);// Specifies the category ID.
  14. // Constructs parameters for uploading short videos to ApsaraVideo for VOD. This step is important.
  15. VodSessionCreateInfo vodSessionCreateInfo =new VodSessionCreateInfo.Builder()
  16. .setImagePath(imagePath)// Specifies the thumbnail path.
  17. .setVideoPath(videoPath)// Specifies the video path.
  18. .setAccessKeyId(accessKeyId)// Specifies a temporary AccessKey ID.
  19. .setAccessKeySecret(accessKeySecret)// Specifies a temporary AccessKey Secret.
  20. .setSecurityToken(securityToken)// Specifies the STS credential.
  21. .setExpriedTime(expriedTime)// Specifies the expiration time for the STS credential.
  22. .setRequestID(requestID)// Specifies the request ID. You can choose whether to obtain the request ID returned by STS.
  23. .setIsTranscode(true)// Specifies whether to enable transcoding. If transcoding is enabled, you must register a listener on the AppServer to receive notifications when transcoding is successful on the ApsaraVideo for VOD server.
  24. .setSvideoInfo(svideoInfo)// Specifies the short video information.
  25. .setVodHttpClientConfig(vodHttpClientConfig)// Specifies network parameters.
  26. .build();

3. Start the upload and set a callback for upload

As shown in the following code snippet, you need to set the VODSVideoUploadCallback callback to start the upload.

  1. vodsVideoUploadClient.uploadWithVideoAndImg(vodSessionCreateInfo, new VODSVideoUploadCallback() {
  2. @Override
  3. public void onUploadSucceed(String videoId, String imageUrl) {
  4. // This callback is fired when the upload succeeds. The video ID and image URL are returned.
  5. Log.d(TAG,"onUploadSucceed"+ "videoId:"+ videoId + "imageUrl" + imageUrl);
  6. }
  7. @Override
  8. public void onUploadFailed(String code, String message) {
  9. // This callback is fired when the upload fails. The error code and error message are returned. You must carefully read the error code and error message.
  10. Log.d(TAG,"onUploadFailed" + "code" + code + "message" + message);
  11. }
  12. @Override
  13. public void onUploadProgress(long uploadedSize, long totalSize) {
  14. // This callback is fired when the default or custom upload progress is reached. The current thread is not a UI thread.
  15. Log.d(TAG,"onUploadProgress" + uploadedSize * 100 / totalSize);
  16. progress = uploadedSize * 100 / totalSize;
  17. handler.sendEmptyMessage(0);
  18. }
  19. @Override
  20. public void onSTSTokenExpried() {
  21. Log.d(TAG,"onSTSTokenExpried");
  22. // This callback is fired when the STS credential expires. If the file was being uploaded when the STS credential expired, resumable upload is performed after the credential is updated.
  23. vodsVideoUploadClient.refreshSTSToken(accessKeyId,accessKeySecret,securityToken,expriedTime);
  24. }
  25. @Override
  26. public void onUploadRetry(String code, String message) {
  27. // This callback is fired when the system retries the upload upon a network exception.
  28. Log.d(TAG,"onUploadRetry" + "code" + code + "message" + message);
  29. }
  30. @Override
  31. public void onUploadRetryResume() {
  32. // This callback is fired when the system recovers from the exception and resumes the upload. You will be notified of the successful retry.
  33. Log.d(TAG,"onUploadRetryResume");
  34. }
  35. });

4. Pause, resume, and cancel upload

Commonly, the upload is paused when the application is switched to the background. When the application is switched back to the foreground, the upload resumes. This logic is implemented in the demo. You can customize the logic of pausing, resuming, and canceling upload.

Pause the upload.

  1. // This method must be set in pairs with the vodsVideoUploadClient.resume() method.
  2. vodsVideoUploadClient.pause();

Resume the upload.

  1. // This method must be set in pairs with the vodsVideoUploadClient.pause() method.
  2. vodsVideoUploadClient.resume();

Cancel the upload.

  1. // If you cancel uploading a file, the upload process ends and cannot be resumed.
  2. vodsVideoUploadClient.cancel();

5. Handle callbacks

5.1 Upload progress

The onUploadProgress callback is fired each time a part is uploaded. The callback parameters include uploadedSize (the size of uploaded parts) and totalSize (the total size of the uploading file).

5.2 Upload success

The onUploadSucceed callback is fired when the upload succeeds. The callback parameters include videoId or imageUrl.

After a video is uploaded, the videoId parameter is returned, indicating the video ID. Then, you need to obtain the playback URL to play the video. For more information, see Use playback URLs.After an image is uploaded, the imageUrl parameter is returned, indicating the image URL. The image URL will expire after a certain period of time if URL signing is enabled. For more information, see URL signing.

5.3 Upload failure

The onUploadFailed(String code, String message) callback is fired when the upload fails. You can view the cause of failure based on the callback parameters code and message. A prompt is displayed on the webpage accordingly.For more information about error codes, see ApsaraVideo for VOD error codes and OSS error codes.

5.4 Credential expiration

The onSTSTokenExpried callback is fired when the upload credential or STS credential expires. You can send a request to the AppServer to obtain a new upload credential or STS credential, and call the following method to resume the upload:

  1. refreshSTSToken(accessKeyId,accessKeySecret,securityToken,expriedTime);

5.5 Upload timeout

When the upload times out, the uploadRetry callback is fired and the system automatically retries to upload files. You can receive a prompt on the webpage or call the cancel method to stop the upload. In addition, you can set the maxRetryCount parameter to specify the maximum number of retry times.If the retry result indicates that the upload can be resumed, the uploadRetryResume callback is fired and the upload is resumed.