服务端 API v2
  • API概览
  • 快速开始
  • 调用方式
  • 房间信令接口
  • 混流接口
  • 媒体服务接口
  • 媒体文件接口
  • 音视频流审核接口
  • 回调说明
  • 全局返回码
  • 使用 Postman 调试

调用方式

更新时间:2022-05-05 18:53

使用说明

ZEGO 服务端 API 支持 HTTPS 网络请求协议,允许 GET 或 POST 方法。您可以通过以下方式调用服务端 API:

  • 根据 API 文档编写代码,访问相应 API。
  • 参考 使用 Postman 调测指南,使用 ZEGO 提供的 Postman API 集合,使用 Postman 快速调试相应接口。

请求方式概述

服务端 API 请求由不同内容构成,有固定的请求结构:

  • 接入地址:ZEGO 服务端的接入地址,根据不同的产品和地域会有所不同。
  • 公共参数:每个请求都须有一系列公共参数。
  • 签名:签名也属于公共参数,需要根据相应的签名算法生成。
  • 请求参数:您需要通过 Action 参数指定目标操作,例如 Action = StartMix;还需要指定接口的其他参数。

我们根据您的签名验证了请求后,会返回结果给您。接口调用成功会显示返回参数,调用失败则显示相应报错,您可以根据 全局返回码 分析排查。

服务端 API 请求示例

以下为 StartMix(开始混流)接口的请求结构为例:

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:指定了 ZEGO 服务端的接入地址。
  • Action=StartMix:指定了要调用的 API。
  • 其它参数:即公共请求参数,是每个接口都需要使用到的请求参数,包含 AppId、SignatureNonce、Signature 等,具体请参考 公共请求参数

此外,ZEGO 提供多种编程语言的示例代码,开发者可根据实际情况进行参考。以下是 StartMix接口的 Node.js 代码:

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

//请将 AppId 修改为你的 appId,appId 为 number
var appId = ;
//请将 serverSecret 修改为你的 serverSecret,serverSecret 为 string
var serverSecret = "";

//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateSignature(appId, signatureNonce, serverSecret, timeStamp) {
    const hash = crypto.createHash('md5'); //规定使用哈希算法中的MD5算法
    var str = appId + signatureNonce + serverSecret + timeStamp;
    hash.update(str);
    //hash.digest('hex')表示输出的格式为16进制
    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)

//以下示例 将 streamId 为 "stream1" 的音视频流 与 streamId 为 "stream2" 的音视频流进行混流,混出 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)
    }
})

1 请求结构

1.1 接入地址

ZEGO 服务端 API 支持全球就近接入,统一接入地址为 ${SERVICE}-api.zego.im,其中 ${SERVICE} 代表不同的产品,比如实时视频产品(Express)的统一接入地址为 rtc-api.zego.im,同时也支持指定地域地址访问,例如上海地域的 Express 产品地址为 rtc-api-sha.zego.im

使用统一接入地址时, 我们会根据调用接口时客户端所在位置,自动解析到最近的某个具体地域的服务器。例如在上海发起请求,会自动解析到上海的服务器,效果和指定 api-sha.zego.im 是一致的。

地理区域 接⼊地址
中国⼤陆(上海)
${SERVICE}-api-sha.zego.im
港澳台(⾹港)
${SERVICE}-api-hkg.zego.im
欧洲(法兰克福)
${SERVICE}-api-fra.zego.im
美⻄(加州)
${SERVICE}-api-lax.zego.im
亚太(孟买)
${SERVICE}-api-bom.zego.im

地址中的 ${SERVICE} 为 ZEGO 提供的各个服务,对应地址如下:

产品 ${SERVICE} 值 接入地址

云通讯

  • 实时音视频
  • 实时语音
  • 低延迟直播
rtc rtc-api.zego.im
超级白板
  • whiteboard
  • docs
  • whiteboard-api.zego.im
  • docs-api.zego.im
  • 云端录制
  • 数据流录制
cloudrecord cloudrecord-api.zego.im

1.2 通信协议

ZEGO 服务端 API 的所有接口均通过 HTTPS 进行通信,提供安全的通信服务。

1.3 请求方法

ZEGO 服务端 API 支持以下 HTTP 请求方法:

  • GET
  • POST
  • 所有请求参数(包括公共参数和业务参数)统⼀放在 Query,使⽤ GET 请求方法。特殊复杂 API 的业务参数放在 Body,使用 POST 请求方法。
  • 使用 POST 请求方法传递参数时,Body 中的参数直接传 JsonObject 格式即可,无需序列化为 String 格式。

2 公共参数

本节介绍了开发者调用 ZEGO 服务端 API 时使用的公共参数,包含了公共请求参数和公共返回参数。

2.1 公共请求参数

公共请求参数是每个接口都需要使用到的请求参数。

参数 类型 是否必填 描述
AppId
Uint32
AppId,ZEGO 分配的用户唯一凭证。
Signature
String
签名,签名的生成请参考 3 签名机制
SignatureNonce
String
随机数。
SignatureVersion
String
签名版本号,必须填写为 2.0
Timestamp
Int64
Unix 时间戳,单位为秒。最多允许 10 分钟的误差。
IsTest String
是(2021-11-16 及之前创建的项目)
是否为测试环境。取值如下:
  • true(忽略大小写):测试环境
  • false(忽略大小写):正式环境(默认值)
针对 2021-11-16 及之前在 ZEGO 控制台 创建的项目:
  • 从控制台申请的 AppId 和 AppSign 等信息默认是测试环境。
  • 可根据 AppId 环境类型及业务需求设置本参数。
否(2021-11-16 之后创建的项目)
是否为测试环境。默认为正式环境,可忽略不填写。
针对 2021-11-16 之后在 ZEGO 控制台 创建的项目:从控制台申请的 AppId 和 AppSign 等信息都为正式环境。

请求示例:

  • 请勿直接拷贝下面的示例用于请求。
  • https://rtc-api.zego.im/?Action=ForbidLiveStream 需要替换为各接口文档“接口原型”章节中的请求地址。
  • 各公共参数的取值请根据实际情况修改。
https://rtc-api.zego.im/?Action=ForbidLiveStream
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureVersion=2.0
&IsTest=false

开发者可以在 服务端 API 校验 页面中,输入 URL 地址,验证签名信息、公共参数、以及 URL 格式是否合法。

2.2 公共返回参数

API 返回结果采用统一格式,返回的数据格式为 JSON。

每次调用接口,无论成功与否,都会返回公共参数。

参数 类型 描述
Code
Number
返回码。
Message
String
操作结果描述。
RequestId
String
请求 Id。
Data
-
响应数据。

返回示例:

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

3 签名机制

为保证 API 的安全调用,ZEGO 服务端会对每个 API 的访问请求进行身份验证。开发者在调用 API 时,都需要在请求中包含签名 Signature 信息。

每次调用接口都需要生成新的签名。

3.1 密钥获取

Signature 是通过对 AppId 和 ServerSecret 进行对称加密,来验证请求的发送者身份。AppId 用于标识访问者的身份,ServerSecret 用于加密签名字符串和服务器验证签名字符串的密钥,必须严格保密,防止泄漏。

开发者可到 ZEGO 控制台 在 “我的项目 > 项目配置 > 基本信息”中获取 AppId,在“我的项目 > 项目配置 > 配置信息”中获取 ServerSecret。

/Pics/console/11.png

3.2 签名生成

  1. 签名参数说明
参数 含义
AppId
应用 Id。公共参数里的 AppId,从 ZEGO 控制台 获取。
SignatureNonce
随机数。公共参数里的 SignatureNonce,生成算法可参考 3.3 签名示例
ServerSecret
应⽤秘钥,从 ZEGO 控制台 获取。
Timestamp
当前 Unix 时间戳,单位为秒。生成算法可参考下方签名示例,最多允许 10 分钟的误差。
  • 计算签名所使用的 SignatureNonce 和 Timestamp 参数取值,需要和公共参数中的 SignatureNonce 和 Timestamp 参数取值保持一致。
  • 生成的签名在 10 分钟内有效,超过时间请重新生成。
  1. 签名生成算法

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

  1. 签名字符串格式

签名采⽤ hex 编码(⼩写),⻓度为 32 个字符。

3.3 签名示例

ZEGO 提供多种编程语言的签名示例代码,开发者可根据实际情况进行参考。

Go 签名示例
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() {
   /*生成16进制随机字符串(16位)*/
   nonceByte := make([]byte, 8)
   rand.Read(nonceByte)
   signatureNonce := hex.EncodeToString(nonceByte)
   log.Printf(signatureNonce)
   appId := 12345       //使用你的appId和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))
}
Python 签名示例
# -*- coding: UTF-8 -*-
import secrets
import string
import hashlib
import time
#Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
def GenerateSignature(appId, signatureNonce, serverSecret, timestamp):
    str1 = str(appId) + signatureNonce + serverSecret + str(timestamp)
    hash = hashlib.md5()
    hash.update(str1.encode("utf8"))
    signature = hash.hexdigest()
    return signature

def main():
    #生成16进制随机字符串(16位)
    signatureNonce = secrets.token_hex(8)

    #使用你的appId和serverSecret
    appId = 12345
    serverSecret = "9193cc662a4c0ec135ec71fb57194b38"
    #获得10位unix时间戳
    timestamp = int(time.time())
    print(GenerateSignature(appId,signatureNonce,serverSecret,timestamp))

if __name__ == '__main__':
    main()
Java 签名示例
import java.security.MessageDigest;
import java.security.SecureRandom;
public class Md5{
    /**
     * 字节数组转16进制
     * @param bytes 需要转换的byte数组
     * @return  转换后的Hex字符串
     */
    public static String bytesToHex(byte[] bytes) {
        StringBuffer md5str = new StringBuffer();
        //把数组每一字节换成16进制连成md5字符串
        int digital;
        for (int i = 0; i < bytes.length; i++) {
            digital = bytes[i];
            if (digital < 0) {
                digital += 256;
            }
            if (digital < 16) {
                md5str.append("0");
            }
            md5str.append(Integer.toHexString(digital));
        }
        return md5str.toString();
    }
    // Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
    public static String GenerateSignature(long appId, String signatureNonce, String serverSecret, long timestamp){
        String str = String.valueOf(appId) + signatureNonce + serverSecret + String.valueOf(timestamp);
        String signature = "";
        try{
            //创建一个提供信息摘要算法的对象,初始化为md5算法对象
            MessageDigest md = MessageDigest.getInstance("MD5");
            //计算后获得字节数组
            byte[] bytes = md.digest(str.getBytes("utf-8"));
            //把数组每一字节换成16进制连成md5字符串
            signature = bytesToHex(bytes);
        }catch (Exception e) {
            e.printStackTrace();
        }
        return signature;
    }


    public static void main(String[] args){
        //生成16进制随机字符串(16位)
        byte[] bytes = new byte[8];

        //使用SecureRandom获取高强度安全随机数生成器
        SecureRandom sr = new SecureRandom();

        sr.nextBytes(bytes);
        String signatureNonce = bytesToHex(bytes);
        long appId = 12345L;       //使用你的appId和serverSecret,数字后要添加大写L或小写l表示long类型
        String serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
        long timestamp = System.currentTimeMillis() / 1000L;
        System.out.println(GenerateSignature(appId,signatureNonce,serverSecret,timestamp));
    }
}
PHP 签名示例
<?php
function GenerateSignature($appId, $signatureNonce, $serverSecret, $timestamp)
{
    $str = $appId.$signatureNonce.$serverSecret.$timestamp;
    $signature = md5($str);
    return $signature;
}

//生成16进制随机字符串(16位)
$signatureNonce = bin2hex(random_bytes(8));
//使用你的appId和serverSecret
$appId = 12345;
$serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
$timestamp = time();
$signature = GenerateSignature($appId, $signatureNonce, $serverSecret, $timestamp);
echo $signature;
?>
Node.js 签名示例
const crypto = require('crypto'); 
//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp){
    const hash = crypto.createHash('md5'); //规定使用哈希算法中的MD5算法
    var str = appId + signatureNonce + serverSecret + timeStamp;
    hash.update(str);
    //hash.digest('hex')表示输出的格式为16进制
    return hash.digest('hex');
}

var signatureNonce = crypto.randomBytes(8).toString('hex');
//使用你的appId和serverSecret
var appId = 12345;
var serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
var timeStamp = Math.round(Date.now()/1000);
console.log(GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp));

3.4 返回码

在使用服务端 API 接口发送请求时,存在以下与签名相关的返回码,请开发者根据实际情况处理。

返回码 说明 处理建议
0 请求成功。 -
100000004 签名过期。 请重新生成签名信息。
100000005 签名错误。 请检查生成签名信息时,参数输入是否正确。