Accessing Server APIs

Usage notes

ZEGOCLOUD server API supports the HTTPS protocol and allows you to call the GET or POST method.

Overview

A server API request consists of different parts and has a fixed request structure.

• Endpoint: The endpoint of the ZEGOCLOUD server. The endpoint differs based on different services and regions.
• Common parameters: Each request must contain a series of common parameters.
• Signature: The signature is a common parameter that must be generated by using a signature algorithm.
• Request parameters: You must specify an operation by setting the Action parameter. Example: Action = CreateMetaHumanVideo. In addition, you must set other parameters for the specified operation.

After the request is verified based on your signature, the verification result is returned. If a call is successful, response parameters are returned. If the call failed, an error is reported. You can troubleshoot the error based on Return Codes.

Request structure

Endpoint

Communication Protocol

For secure communications, all the Server APIs must be accessed via HTTPS requests.

Request methods

The server API supports the following HTTP Request methods:

• GET
• POST

Common parameters

This section introduces the common parameters used by developers when calling ZEGOCLOUD server APIs, including common request parameters and common response parameters.

Common Request Parameters

Common request parameters are the parameters that are required for every API request.

Request example:

https://aigc-digitalhuman-api.zegotech.cn/?Action=xxx
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=xxxx
&SignatureVersion=2.0

https://aigc-digitalhuman-api.zegotech.cn/?Action=xxx
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=xxxx
&SignatureVersion=2.0

公共返回参数

All responses to API requests are returned in a unified format, with the returned data in JSON format.

The following common response parameters will be included in the response to every request, regardless of whether the request is successful.

Sample Response:

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

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

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.