All Products
Document Center

Short video upload

Last Updated: Jul 11, 2019


The short video upload object VODUploadSVideoClient 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 VODUploadSVideoClient object. It must not be a local variable.

@property (nonatomic, strong) VODUploadSVideoClient *client;

Initialize the upload instance and set the callback for delegate.

self.client = [[VODUploadSVideoClient alloc] init];
self.client.delegate = self;

3. Set callbacks

As shown in the preceding initialization code snippet, you need to set the delegate to implement VODUploadSVideoClientDelegate by using the following methods:

 This callback is fired when the upload succeeds.

 @param result The upload result.
- (void)uploadSuccessWithResult:(VodSVideoUploadResult *)result;

 This callback is fired when the upload fails.

 @param code The error code.
 @param message The error description.
- (void)uploadFailedWithCode:(NSString *)code message:(NSString *)message;

 This callback is fired when the default or custom upload progress is reached.

 @param uploadedSize The size of uploaded parts.
 @param totalSize The total size of the uploading file.
- (void)uploadProgressWithUploadedSize:(long long)uploadedSize totalSize:(long long)totalSize;

 This callback is fired when the credential expires.
- (void)uploadTokenExpired;

 This callback is fired when the system retries the upload upon a network exception.
- (void)uploadRetry;

 This callback is fired when the system recovers from the exception and resumes the upload.
- (void)uploadRetryResume;

4. Start the upload

Short video upload does not support the upload list function. You need to call the upload operation to upload each short video.

NSString *videoPath = [[NSBundle mainBundle] pathForResource:@"svideo" ofType:@"mp4"];
    NSString *imagePath = [[NSBundle mainBundle] pathForResource:@"cover" ofType:@"png"];
    VodSVideoInfo *info = [VodSVideoInfo new];
    info.title = @"short video";
    info.desc = @"desc";
    info.cateId = @(10);
    info.tags = @"game";
    [self.client uploadWithVideoPath:videoPath imagePath:imagePath svideoInfo:info accessKeyId:self.keyId accessKeySecret:self.keySecret accessToken:self.token];

As shown in the sample code, calling the upload method requires you to specify the video URL, thumbnail URL, VodSVideoInfo, and the STS credential obtained in the first step.

Note: The size of the file to be uploaded cannot exceed 4 GB.

The structure of the VodSVideoInfo object is as follows:

// The title.
@property (nonatomic, copy) NSString* title;
// The tags.
@property (nonatomic, copy) NSString* tags;
// The description.
@property (nonatomic, copy) NSString* desc;
// The category ID.
@property (nonatomic, strong) NSNumber* cateId;

You can also set the following methods to control the upload: Pause the upload.

- (void)pause;

Resume the upload.

- (BOOL)resume;

Cancel the upload.

- (BOOL)cancel;

5. Handle callbacks

5.1 Upload progress

The uploadProgressWithUploadedSize: totalSize: 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 uploadSuccessWithResult callback is fired when the upload succeeds. The callback parameters include VodSVideoUploadResult (the upload result). The VodSVideoUploadResult parameter contains the following parameters:

@property (nonatomic, copy) NSString* videoId;
@property (nonatomic, copy) NSString* 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 uploadFailedWithCode: 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 uploadTokenExpired 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:

- (void)refreshWithAccessKeyId:(NSString *)accessKeyId
               accessKeySecret:(NSString *)accessKeySecret
                   accessToken:(NSString *)accessToken
                    expireTime:(NSString *)expireTime;

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.

Advanced settings

VODUploadSVideoClient supports the following advanced settings:

 Specifies whether to transcode a file after it is uploaded to the ApsaraVideo for VOD server. The default value is Yes.
@property (nonatomic, assign) BOOL transcode;

 Specifies the maximum number of retry times upon a timeout. The default value is INT_MAX.
@property (nonatomic, assign) uint32_t maxRetryCount;

 Specifies the timeout period.
@property (nonatomic, assign) NSTimeInterval timeoutIntervalForRequest;

 Specifies the path of the cache directory.
@property (nonatomic, copy) NSString * recordDirectoryPath;

 Specifies whether to record the upload progress for resumable upload. The default value is Yes.
@property (nonatomic, assign) BOOL recordUploadProgress;

 Specifies the size of each part in multipart upload. The default value is 1024 × 1024.
@property (nonatomic, assign) NSInteger uploadPartSize;

 Specifies the storage region in ApsaraVideo for VOD. The default value is cn-shanghai.
@property (nonatomic, copy) NSString *region;