Calling APIs

Usage instructions

ZEGOCLOUD Server API supports HTTPS network request protocol, allowing GET or POST methods. You can call the Server API in the following ways:

• Write code according to the API documentation to access the corresponding API.
• Refer to How to debug Server API online to quickly debug the corresponding interface on the documentation page.

Overview of request methods

Server API requests consist of different contents and have a fixed request structure:

• Access Address: The access address of the ZEGOCLOUD server, which varies according to different products and regions.
• Common Parameters: Each request must have a series of common parameters.
• Signature: The signature is also a common parameter and needs to be generated according to the corresponding signature algorithm.
• Request parameters: You need to specify the target operation through the Action parameter, such as Action = StartMix; you also need to specify other parameters of the interface.

After we verify your request based on your signature, we will return the result to you. If the interface call is successful, the return parameters will be displayed; if the call fails, the corresponding error will be displayed. You can analyze and troubleshoot according to the Global Return Codes.

https://rtc-api.zego.im/?Action=StartMix
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false

https://rtc-api.zego.im/?Action=StartMix
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false

const crypto = require('crypto');
const request = require('request');

//Please modify AppId to your appId, appId is number
var appId = ;
//Please modify serverSecret to your serverSecret, serverSecret is string
var serverSecret = "";

//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateSignature(appId, signatureNonce, serverSecret, timeStamp) {
    const hash = crypto.createHash('md5'); //Specified to use the MD5 algorithm in the hash algorithm
    var str = appId + signatureNonce + serverSecret + timeStamp;
    hash.update(str);
    //hash.digest('hex') indicates that the output format is hexadecimal
    return hash.digest('hex');
}

var signatureNonce = crypto.randomBytes(8).toString('hex');
var timeStamp = Math.round(Date.now() / 1000);
var sig = GenerateSignature(appId, signatureNonce, serverSecret, timeStamp);

//The following example mixes the audio and video stream with streamId "stream1" and the audio and video stream with streamId "stream2" to mix out the audio and video stream with streamId "stream3"
var url = `https://rtc-api.zego.im/?Action=StartMix&AppId=${appId}&SignatureNonce=${signatureNonce}&Timestamp=${timeStamp}&Signature=${sig}&SignatureVersion=2.0&IsTest=false`;
var body = {
    'TaskId': '123',
    'Sequence': 123,
    'UserId': '123',
    'MixInput': [
    {
        'StreamId': 'stream1',
        'RectInfo': {
            "Top": 70,
            "Bottom": 160,
            "Left": 100,
            "Right": 260
        },
    },
    {
        'StreamId': 'stream2',
        'RectInfo': {
            "Top": 200,
            "Bottom": 290,
            "Left": 100,
            "Right": 260
        },
    }
    ],
    'MixOutput': [{
        'StreamId': 'stream3',
        'Width': 360,
        'Height': 360,
        'VideoBitrate': 12000,
        'Fps': 15
    }]
}

request({
    url: url,
    method: 'POST',
    json: true,
    headers: {
        'content-type': 'application/json'
    },
    body: body
}, function (error, response, body) {
    console.log(error)
    console.log(response.statusCode)
    if (!error && response.statusCode === 200) {
        console.log(body.Data)
    }
})

const crypto = require('crypto');
const request = require('request');

//Please modify AppId to your appId, appId is number
var appId = ;
//Please modify serverSecret to your serverSecret, serverSecret is string
var serverSecret = "";

//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateSignature(appId, signatureNonce, serverSecret, timeStamp) {
    const hash = crypto.createHash('md5'); //Specified to use the MD5 algorithm in the hash algorithm
    var str = appId + signatureNonce + serverSecret + timeStamp;
    hash.update(str);
    //hash.digest('hex') indicates that the output format is hexadecimal
    return hash.digest('hex');
}

var signatureNonce = crypto.randomBytes(8).toString('hex');
var timeStamp = Math.round(Date.now() / 1000);
var sig = GenerateSignature(appId, signatureNonce, serverSecret, timeStamp);

//The following example mixes the audio and video stream with streamId "stream1" and the audio and video stream with streamId "stream2" to mix out the audio and video stream with streamId "stream3"
var url = `https://rtc-api.zego.im/?Action=StartMix&AppId=${appId}&SignatureNonce=${signatureNonce}&Timestamp=${timeStamp}&Signature=${sig}&SignatureVersion=2.0&IsTest=false`;
var body = {
    'TaskId': '123',
    'Sequence': 123,
    'UserId': '123',
    'MixInput': [
    {
        'StreamId': 'stream1',
        'RectInfo': {
            "Top": 70,
            "Bottom": 160,
            "Left": 100,
            "Right": 260
        },
    },
    {
        'StreamId': 'stream2',
        'RectInfo': {
            "Top": 200,
            "Bottom": 290,
            "Left": 100,
            "Right": 260
        },
    }
    ],
    'MixOutput': [{
        'StreamId': 'stream3',
        'Width': 360,
        'Height': 360,
        'VideoBitrate': 12000,
        'Fps': 15
    }]
}

request({
    url: url,
    method: 'POST',
    json: true,
    headers: {
        'content-type': 'application/json'
    },
    body: body
}, function (error, response, body) {
    console.log(error)
    console.log(response.statusCode)
    if (!error && response.statusCode === 200) {
        console.log(body.Data)
    }
})

Request structure

Access address

Developers need to specify the corresponding access address according to the geographic region where their server is located, and send requests to the ZEGOCLOUD server.

ZEGO supports request access for the following geographic regions:

Where ${PRODUCT} is the different services of different products provided by ZEGO, corresponding as follows:

Communication protocol

All interfaces of the ZEGOCLOUD Server API communicate through HTTPS to provide secure communication services.

Request method

ZEGOCLOUD Server API supports the following HTTP request methods:

• GET
  • All request parameters (including common parameters and business parameters) are uniformly placed in Query.
• POST
  • For special complex APIs, business parameters are placed in Body, and common parameters are placed in Query.
  • The parameters in Body can be passed directly in JsonObject format without being serialized into String format.
  • In Headers, set "Content-type" to "application/json".

Common parameters

This section introduces the common parameters used by developers when calling ZEGOCLOUD Server API, including common request parameters and common return parameters.

Common request parameters

Common request parameters are request parameters that need to be used by every interface.

Request example:

https://${PRODUCT}-api.zego.im/?Action=xxx
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureVersion=2.0
&IsTest=false
&<Non-common request parameters>

https://${PRODUCT}-api.zego.im/?Action=xxx
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureVersion=2.0
&IsTest=false
&<Non-common request parameters>

Developers can enter the URL address on the Server API Verification page to verify whether the signature information, common parameters, and URL format are legal.

Common return parameters

The API return result adopts a unified format, and the returned data format is JSON.

Every time the interface is called, regardless of success or failure, common parameters will be returned.

Return example:

{
    "Code":0,
    "Data":{
        "MessageId":"1_1611647493487_29"
    },
    "Message":"success",
    "RequestId":"2237080460466033406"
}

{
    "Code":0,
    "Data":{
        "MessageId":"1_1611647493487_29"
    },
    "Message":"success",
    "RequestId":"2237080460466033406"
}

Signing the requests

To ensure secure API calls, the ZEGOCLOUD server authenticates every API request, which means a request signature must be included in every API request.

Get the AppId and Server Secret Key

To generate a request signature, you will need to use the AppId and ServerSecret assigned to your project by ZEGOCLOUD. The AppId is used as the identifier of the request sender, and ServerSecret is the secret key to generate the signature string on the request sender side and verify the signature on the ZEGOCLOUD server. To ensure system security, please keep this information strictly confidential.

You can find the AppId and ServerSecret of your project in the ZEGOCLOUD Admin Console.

Generate a signature

Parameters required to generate a signature

Signature algorithm

Signature = md5(AppId + SignatureNonce + ServerSecret + Timestamp)

Format of the Signature string

The Signature is a hex string of 32 characters in lower case.

Signature sample code

ZEGOCLOUD provides sample code in various programming languages for generating the signature.

import (
   "crypto/md5"
   "crypto/rand"
   "encoding/hex"
   "fmt"
   "log"
   "time"
)
// Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
func GenerateSignature(appId uint32, signatureNonce string, serverSecret string, timestamp int64) (Signature string){
   data := fmt.Sprintf("%d%s%s%d", appId, signatureNonce, serverSecret, timestamp)
   h := md5.New()
   h.Write([]byte(data))
   return hex.EncodeToString(h.Sum(nil))
}
func main() {
   /* Generate a 16-character random hexadecimal string (16 bits) */
   nonceByte := make([]byte, 8)
   rand.Read(nonceByte)
   signatureNonce := hex.EncodeToString(nonceByte)
   log.Printf(signatureNonce)
   appId := 12345       // Use your appId and serverSecret
   serverSecret := "9193cc662a4c0ec135ec71fb57194b38"
   timestamp := time.Now().Unix()
   /* appId:12345
      signatureNonce:4fd24687296dd9f3
      serverSecret:9193cc662a4c0ec135ec71fb57194b38
      timestamp:1615186943      2021/03/08 15:02:23
      signature:43e5cfcca828314675f91b001390566a
    */
   log.Printf("signature:%v", GenerateSignature(uint32(appId), signatureNonce, serverSecret, timestamp))
}

import (
   "crypto/md5"
   "crypto/rand"
   "encoding/hex"
   "fmt"
   "log"
   "time"
)
// Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
func GenerateSignature(appId uint32, signatureNonce string, serverSecret string, timestamp int64) (Signature string){
   data := fmt.Sprintf("%d%s%s%d", appId, signatureNonce, serverSecret, timestamp)
   h := md5.New()
   h.Write([]byte(data))
   return hex.EncodeToString(h.Sum(nil))
}
func main() {
   /* Generate a 16-character random hexadecimal string (16 bits) */
   nonceByte := make([]byte, 8)
   rand.Read(nonceByte)
   signatureNonce := hex.EncodeToString(nonceByte)
   log.Printf(signatureNonce)
   appId := 12345       // Use your appId and serverSecret
   serverSecret := "9193cc662a4c0ec135ec71fb57194b38"
   timestamp := time.Now().Unix()
   /* appId:12345
      signatureNonce:4fd24687296dd9f3
      serverSecret:9193cc662a4c0ec135ec71fb57194b38
      timestamp:1615186943      2021/03/08 15:02:23
      signature:43e5cfcca828314675f91b001390566a
    */
   log.Printf("signature:%v", GenerateSignature(uint32(appId), signatureNonce, serverSecret, timestamp))
}

Signing failures

When a signature verification fails, an error code will be returned.

Debug API online