Accessing Methods
Request Structure
Service Address
Developers need to send requests to the ZEGO server through the access address https://cloud-realtime-asr-api.zegotech.cn.
Communication Protocol
All ZEGO server API interfaces communicate via HTTPS, providing secure communication services.
Request Method
ZEGO server API supports the following HTTP request methods:
- GET
- POST
All request parameters (including common parameters and business parameters) are uniformly placed in the Query using the GET request method. For special complex API parameters, place them in the Body using the POST request method.
Common Parameters
Common Request Parameters
Common request parameters are request parameters required by every interface:
| Parameter | Type | Required | Description |
|---|---|---|---|
| AppId | Uint32 | Yes | AppId, the unique credential assigned by ZEGO to the user. |
| Signature | String | Yes | Signature, for signature generation please refer to Signature Mechanism. |
| SignatureNonce | String | Yes | Random string. |
| SignatureVersion | String | Yes | Signature version number, default value is 2.0. |
| Timestamp | Number | Yes | Unix timestamp, in seconds. Maximum allowed deviation of 10 minutes. |
Request Example:
https://cloud-realtime-asr-api.zegotech.cn/?Action=StartRealtimeASRTask
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0For ID-type parameters among non-common request parameters, including UserId, RoomId, etc., the following rules should be followed:
- Character restrictions: numbers, English characters, '-', '_'.
- Maximum length:
- RoomId: 128 bytes.
- UserId: 32 bytes.
Common Response Parameters
API response results use a unified format, and the returned data format is JSON. Every time an interface is called, whether successful or not, common parameters will be returned.
| Parameter | Type | Description |
|---|---|---|
| Code | Number | Error code. |
| Message | String | Description information of the request result. |
| RequestId | String | Request ID. |
| Data | Object | Response object. See each interface response parameter for details. |
Response Example:
{
"Code": 0,
"Message": "success",
"RequestId": "1920370518150615040",
"Data": {
"TaskId": "1920370518175780864"
}
}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.
A new signature needs to be generated for 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
| Parameter | Description |
|---|---|
| AppId | Application ID. |
| SignatureNonce | A random string. |
| ServerSecret | Server secret key. |
| Timestamp | Unix timestamp of the current time, in seconds. A maximum error of 10 minutes is allowed. |
| Parameter | Description |
|---|---|
| AppId | Application ID. The AppId in the public parameters. Get it from the ZEGOCLOUD Admin Console. |
| SignatureNonce | A 16-character hexadecimal random string (hex encoding of 8-byte random number). The SignatureNonce in the public parameters. Refer to Signature sample code for how to generate. |
| ServerSecret | Server secret key. Get it from the ZEGOCLOUD Admin Console. |
| Timestamp | Unix timestamp of the current time, in seconds. Refer to Signature sample code for how to generate, with a maximum error of 10 minutes. |
The values of the SignatureNonce and Timestamp parameters used to generate the signature must be consistent with those of the common parameters.
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))
}Signing failures
When a signature verification fails, an error code will be returned.
| return code | description |
|---|---|
| 100000004 | Signature expired. |
| 100000005 | Invalid signature. |
Debug API Online
You can debug server API online on the ZEGO server API documentation page, making it convenient for developers to quickly test and verify API functionality.