Documentation
SuperBoard_backup Super Board (Full version)
Documentation
Demo APP
SDK Center
API Center
FAQ
Code Market
Console
Sign Up
Log In
中文站 English
  • Documentation
  • Super Board (Full version)
  • Server API V2
  • Request file transcoding

Request file transcoding

Last updated:2022-12-21 17:44

Description

Creates a file transcoding task.

To retranscode a file, set IsRestartTranscode to 1. Otherwise, the system does not retranscode the file by default but returns a message indicating the transcoding success.

Request method and endpoint

  • Request method: POST
  • Request endpoint: https://docs-api.zego.im/?Action=StartTranscode
  • Protocol: HTTPS
  • Rate limit: 10 requests/second

Request parameters

Listed below are the parameters specific to this request. For the complete list of public request parameters, see Accessing Server APIs - Public parameters..

Parameter Type Required Description
FileHash
String
Yes
Hash value of the source file, which must be a 32-bit MD5 hash value. For details about the calculation method, see Calculation examples for the file hash value.
FileName
String
Yes
Source file name.
FileType
Int64
Yes
Source file type. The options are as follows:
  • 1: .ppt or .pptx (The value of DestinationFileType for a static file is 256, and that for an animated file is 512.)
  • 2: .doc or .docx (The value of DestinationFileType is 256.)
  • 4: .xls or .xlsx (The value of DestinationFileType is 256.)
  • 8: PDF file (The value of DestinationFileType is 256.)
  • 16: .jpg, .jpeg, .png, .bmp (The value of DestinationFileType is 16.)
  • 32: .txt (The value of DestinationFileType is 256.)
DestinationFileType
Int64
Yes
Target file type. The options are as follows:
  • 16: .jpg, .jpeg, .png, or .bmp
  • 256: vector and image
  • 512: animated PowerPoint file
FileSize
Int64
Yes
Size of the source file, in bytes. For details about the calculation method, see File size calculation examples.
SourceFileUrl
String
Yes
Link for downloading the source file.
To ensure security, you are advised to use the download URL with authentication information and ensure that the validity period of the URL is longer than half an hour when calling the API.
IsRestartTranscode
Int64
No
Indicates whether to retranscode the file.
  • 0 (default value): no
  • 1: yes
ThumbnailDefinition
Int64
No
Thumbnail resolution. If this parameter is not transferred, the default resolution is used. The options are as follows:
  • 1 (default value): normal
  • 2: SD
  • 3: HD
This parameter is valid only when it is set before transcoding, and the value is used during transcoding. To change the resolution after transcoding, set IsRestartTranscode to 1 and send a transcoding request again.

Sample request

  • Request URL
    https://docs-api.zego.im/?Action=StartTranscode
    &AppId=1234567890
    &SignatureNonce=15215528852396
    &Timestamp=1234567890
    &Signature=7a2c0f11145fb760d607a07b54825013
    &SignatureVersion=2.0
    &IsTest=false
  • Request message body
    {
      "FileHash": "8cb1bccbdf2e655a3b45f4b126ef8392",
      "FileName": "demo.pptx",
      "FileType": 1,
      "DestinationFileType": 256,
      "FileSize": 1024,
      "SourceFileUrl": "url",
      "ThumbnailDefinition": 1,
      "IsRestartTranscode": 1
    }

Response parameters

Parameter Type Description
Code
Int64
Error code.
Message
String
Error description.
RequestId
String
Request ID.
Data
Object
Response object.
For details, see Data member list.

The following table lists data members.

Parameter Type Description
FileHash
String
Hash value of the source file.
FileType
Int64
Source file type. The options are as follows:
  • 1: .ppt or .pptx (The value of DestinationFileType for a static file is 256, and that for an animated file is 512.)
  • 2: .doc or .docx (The value of DestinationFileType is 256.)
  • 4: .xls or .xlsx (The value of DestinationFileType is 256.)
  • 8: PDF file (The value of DestinationFileType is 256.)
  • 16: .jpg, .jpeg, .png, .bmp (The value of DestinationFileType is 16.)
  • 32: .txt (The value of DestinationFileType is 256.)
DestinationFileType
Int64
Target file type. The options are as follows:
  • 16: .jpg, .jpeg, .png, or .bmp
  • 256: vector and image
  • 512: animated PowerPoint file
FileName
String
Source file name.
FileSize
Int64
Size of the source file, in bytes.
Status
Int64
File transcoding status. For details, see Status .
TaskId
String
File transcoding task ID.

The following table lists the values of Status.

Status code Description
1 Not uploaded.
2 Uploaded.
4 Queuing.
8 Transcoding.
16 Transcoding succeeded.
32 Transcoding failed.
64 Transcoding task canceled.
128 Password-protected file.
256 The file is too large, for example, containing too many pages.
512 The Excel file contains too many sheets.
1024 The file is empty. For example, the PowerPoint file contains no slide.
2048 The transcoding server failed to open the file.
4096 The target file type is not supported.
8192 The source file is read-only.
16384

The transcoding server failed to download the source file. The possible causes are as follows:

  • Unable to download the file from the source file URL in the request parameters.
  • The file hash value in the request parameters is not a 32-bit MD5 hash value.
  • The file hash value in the request parameters does not match the hash value obtained from file-based calculation.
32768 Elements that cannot be processed by transcoding tools detected in the source file, such as ink marks and graffiti. Remove the elements and transcode the file again.
32769 The file format of the Word, Excel, or PowerPoint file is invalid. Ensure that the source file can be opened by Office before transcoding the file.
32770 A security risk exists in the file to be transcoded. Ensure that no message indicating a computer damage risk for file editing is displayed when you attempt to open the file using Office.
32771 After transcoding an animated PowerPoint file, failures in exporting some images and audio and video files are detected. The transcoding server will transcode the file again.
32772 The file size is too large to transcode. Ensure that the file size meets the requirements.
32773 A dialog indicating that the file needs to be repaired (because the file is damaged) is displayed when you attempt to open the file.
32774 EOF error (incomplete file content).

Sample response

{
    "Code": 0,
    "Message": "succeed",
    "RequestId": "abcd123",
    "Data": {
        "FileHash": "abc",
        "FileName": "demo.pptx",
        "FileType": 1,
        "DestinationFileType": 256,
        "FileSize": 1024,
        "Status": 8,
        "TaskId": "task"
    }
}

Return codes

Listed below are the return codes related to this API. For the complete list of return codes, see Return codes.

Return code Description
60015
The source file type is not supported.
60016
The file size exceeds the upper limit. Default upper limit: 100 MB.
60017
The Excel file size exceeds the upper limit. Default upper limit: 10 MB.
60021
The source file type does not match the target file type.

Calculation examples for the file hash value and size

Calculation examples for the file hash value

The file hash value is a character string obtained during file content-based calculation, and is used to verify the file content. The server calculates the hash value of a received file and compares the obtained hash value with the hash value sent from the client to ensure that the file content is not tampered with.

Calculation example for the Go file hash value
import (
    "crypto/md5"
    "fmt"
    "io"
    "os"
)

// fileName File path+File name etc: /usr/local/aaa.sh
func main() {
    fileName := "/local/usr/test.go"
    str := GetFileMD5FromFile(fileName)
    fmt.Println(str)
}

func GetFileMD5FromFile(localFile string) (fileHash string) {
    fd, e := os.Open(localFile)
    if e != nil {
        return
    }
    defer fd.Close()
    fileHash = GetFileMD5(fd)
    return
}

func GetFileMD5(f io.Reader) string {
    h := md5.New()
    if _, err := io.Copy(h, f); err != nil {
        fmt.Println("%v", err)
    }
    return fmt.Sprintf("%x", h.Sum(nil))
}
Calculation example for the Python file hash value
import hashlib

# filename File path+File name etc: /usr/local/aaa.sh
def md5(filename):
    hash_md5 = hashlib.md5()
    with open(filename, "rb") as f:
        for chunk in iter(lambda: f.read(4096), b""):
            hash_md5.update(chunk)
    return hash_md5.hexdigest()
Calculation example for the Java file hash value

import java.io.File;
import java.io.FileInputStream;
import java.math.BigInteger;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

// fileName File path+File name etc: /usr/local/aaa.sh
public static String getFileMD5(File filename) {
    if (!filename.isFile()) {
        return null;
    }
    MessageDigest digest = null;
    FileInputStream in = null;
    byte buffer[] = new byte[1024];
    int len;
    try {
        digest = MessageDigest.getInstance("MD5");
        in = new FileInputStream(filename);
        while ((len = in.read(buffer, 0, 1024)) != -1) {
            digest.update(buffer, 0, len);
        }
        in.close();
    } catch (Exception e) {
        e.printStackTrace();
        return null;
    }
    return toHex(digest.digest());
}

private static final char[] HEX_DIGITS = "0123456789abcdef".toCharArray();
public static String toHex(byte[] data) {
    char[] chars = new char[data.length * 2];
    for (int i = 0; i < data.length; i++) {
        chars[i * 2] = HEX_DIGITS[(data[i] >> 4) & 0xf];
        chars[i * 2 + 1] = HEX_DIGITS[data[i] & 0xf];
    }
    return new String(chars);
}
Calculation example for the PHP file hash value
// fileName File path+File name etc: /usr/local/aaa.sh
$file = 'fileName';
echo 'MD5 file hash of ' . $file . ': ' . md5_file($file);
Calculation example for the Node.js file hash value
const fs = require("fs");
const path = require("path");
const crypto = require('crypto');

// fileName File path+File name etc: /usr/local/aaa.sh
function test() {
    const stream = fs.createReadStream(path.join('fileName'));
    const hash = crypto.createHash('md5');
    stream.on('data', chunk => {
        hash.update(chunk, 'utf8');
    });
    stream.on('end', () => {
        const md5 = hash.digest('hex');
        console.log(md5);
    });
}

Calculation examples for the file size

Calculation example for the Go file size
// fileName File path+File name etc: /usr/local/aaa.sh
package main

import (
    "fmt"
    "os"
)

func main() {
    fileName := "/local/usr/test.go"
    fileSize := GetFileSize(fileName)
    fmt.Println(fileSize)
}

func GetFileSize(fileName string) int64 {
    fi, err := os.Stat(fileName)
    if err != nil {
        return 0
    }
    return fi.Size()
}
Calculation example for the Python file size
# fileName File path+File name etc: /usr/local/aaa.sh
import os
fsize = os.path.getsize(filename)
print(fileSize)
Calculation example for the Java file size
// fileName File path+File name etc: /usr/local/aaa.sh
public static long getFileSIze(String filename) {
    File file = new File(filename);
    if (!file.exists() || !file.isFile()) {
        System.out.println("file not exist");
        return -1;
    }
    return file.length();
}
Calculation example for the PHP file size
// fileName File path+File name etc: /usr/local/aaa.sh
$filename = 'somefile.txt';
echo $filename . ': ' . filesize($filename) . ' bytes';
Calculation example for the Node.js file size
const fs = require("fs");

// fileName File path+File name etc: /usr/local/aaa.sh
function getFileSize() {
    const fsStat = fs.statSync(fileName);
    console.log(fsStat.size)
}
Page Directory
  • Free trial
  • 提交工单
    咨询集成、功能及报价等问题
    电话咨询
    400 1006 604
    Get Consulting
    Scan Wechat QR code