调用方式

更新时间: 2025/09/17 09:14:53

音视频通话 2.0(NetEase Real-Time Communication,NERTC)是网易云信推出的实时音视频开发平台。网易云信基于网易多年的即时通讯和实时音视频通话能力的技术积累,为您提供稳定流畅、高品质、全平台的点对点和多人实时音视频通话服务。

使用限制

通过服务端或客户端 API 接口使用音视频通话 2.0 服务时,您需要注意房间人数、连麦人数等限制,详细说明请参考 使用限制

适用场景

音视频通话 2.0 提供客户端和服务端 RESTful API 供您调用:

  • 服务端 API:使用 HTTP/HTTPS 协议,支持 GET 和 POST 方法,适用于服务端管理和控制场景。
  • 客户端 SDK:提供完整的开发包,适用于快速二次开发,详情请参考 集成 SDK 指南。

部分功能支持客户端和服务端两种实现方式,请根据您的实际需求选择合适的调用方式。

请求概述

应用服务端调用 API 向网易云信 RTC 服务端发起的请求需遵循固定的请求结构和请求方式。

sequenceDiagram
    autonumber
    participant app as 应用服务器
    participant server as 网易云信 RTC 服务端

    app->>server: HTTPS 请求
    Note over app,server: 请求头:CheckSum 及公共参数<br>请求体:业务参数(JSON格式)
    server->>server: 验证 CheckSum
    server-->>app: 响应信息(JSON 数据,UTF-8 编码)

请求方式

  • 通信协议:网易云信 RTC 服务端 API 使用 HTTP/HTTPS 网络请求协议。

  • 请求方式:应用服务端向网易云信 RTC 服务端发起的请求支持 POST、DELETE、GET 三种方式,分别对应资源的增加、删除、修改和查询操作。

服务地址

  • 基础接入地址

    服务区域 接入地址 说明
    中国大陆 https://rtc.yunxinapi.com/v2/api 默认配置
    海外地区 https://rtc-ap.yunxinapi.com/v2/api 海外用户专用

    海外业务接入说明请参考 接入海外数据中心

  • 高可用域名配置推荐,为保障业务稳定性,建议配置主备域名)

    服务区域 主域名 备用域名 默认域名(兼容)
    中国大陆 rtc-pri.yunxinapi.com rtc-bak.yunxinapi.com rtc.yunxinapi.com
    海外地区 rtc-ap.yunxinapi.com rtc-ap-bak.yunxinapi.com rtc-ap.yunxinapi.com

    为确保服务的高可用性,网易云信建议:

    • 配置多域名访问:在业务系统中同时配置主备域名,当检测到主域名无法访问时,自动切换至备用域名。
    • 定期检查域名可用性:建议在应用中实现定期检查域名可用性的机制,以便及时发现并应对可能的域名访问问题。

请求结构

请求 URL

完整的 API 请求 URL 由以下部分组成:

组成部分 必选 描述 示例
- 基础 URL 服务接入地址 + 接口路径 https://rtc.yunxinapi.com/v2/api/room
路径参数 URL 中的动态参数,需 URL 编码 /rooms/{cid} 中的 {cid}
查询参数 URL 中的查询字符串,GET/DELETE 请求必需
  • GET、DELETE 操作必须使用查询参数,不能使用请求体参数
  • 查询参数为 key-value 形式,没有二级结构。所有参数和值需要经过 url 编码
  • 当查询参数出现 List 类型时,每个参数以逗号进行拼接
?page=1&size=10

请求头(Header)

Header 中包括用于鉴权的相关公共参数,用于标识用户和接口签名。如非必要,每个单独的接口文档中不再对这些参数进行说明,但每次请求均需要携带这些参数,才能正常发起请求。

参数名称 类型 必选 示例 说明
AppKey String b2e***fcc155e7d26c4 通过网易云信控制台获取,请参考 获取 App Key
Nonce String 8dfdb33d2840 随机数,最大长度 128 个字符。
CurTime String 1443592222 当前 UTC 时间戳,从 1970 年 1 月 1 日 0 时 0 分 0 秒开始到 现在 的秒数。该时间用于计算 CheckSum 的有效期,请确保与标准时间同步,例如 NTP 服务。
CheckSum String b404199cdb06d20xxxdc61016d SHA1(AppSecret + Nonce + CurTime),将该三个参数拼接的字符串进行 SHA1 哈希计算从而生成 16 进制字符(小写)。
  • 出于安全性考虑,每个 CheckSum有效期5 分钟,即服务端接收到请求的时间与请求中的 CurTime 相差不能超过 5 分钟,建议每次请求都生成新的 CheckSum
  • CheckSum 检验失败时会返回 401 错误码,更多错误码信息请参考 错误码

请妥善保管用于计算 CheckSumAppSecret,可在应用服务器存储和使用,但不应存储或传递到客户端,也不应在网页等前端代码中嵌入。

CheckSum 计算示例

您可以参考以下代码计算 CheckSum。

Java
Javapackage com.netease.im.rtctoken;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;

public class RestApiAuth {
    // 计算并获取 CheckSum
    public static String getChecksum(String appSecret, String nonce, long curTime) {
        return sha1(appSecret + nonce + curTime);
    }

    // 对输入字符串进行 SHA1 哈希计算
    private static String sha1(String input) {
        try {
            MessageDigest mDigest = MessageDigest.getInstance("SHA-1");
            byte[] result = mDigest.digest(input.getBytes(StandardCharsets.UTF_8));
            StringBuilder sb = new StringBuilder();
            for (byte b : result) {
                sb.append(String.format("%02x", b));
            }
            return sb.toString();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}
Node.js
JavaScriptconst crypto = require('crypto');

var GetChecksum = function (appSecret, nonce, curTime) {
    return sha1(`${appSecret}${nonce}${curTime}`);
}

const sha1 = function (input) {
    const sha1 = crypto.createHash('sha1');
    sha1.update(input, 'utf8');
    return sha1.digest('hex');
}
Go
Golangpackage token

import (
    "crypto/sha1"
    "fmt"
)

func GetChecksum(appSecret, nonce string, curtime int64) string {
    raw := fmt.Sprintf("%s%s%d", appSecret, nonce, curtime)
    return fmt.Sprintf("%x", sha1.Sum([]byte(raw)))
}

PHP
PHP<?php
function getChecksum(string $appSecret, string $nonce, int $curtime):string {
    return sha1($appSecret . $nonce . $curtime);
}
?>
Python
Pythonimport hashlib

def get_checksum(app_secret: str, nonce: str, timestamp: int):
    return hashlib.sha1(f'{app_secret}{nonce}{timestamp}'.encode()).hexdigest()
C#
C#using System.Security.Cryptography;
using System.Text;

namespace TokenBuilder
{
    public class RestApiAuth
    {
        public static string GetChecksum(string appSecret, string nonce, long curtime)
        {
            return ComputeSHA1($"{appSecret}{nonce}{curtime}");
        }
        private static string ComputeSHA1(string input)
        {
            using var sha1 = SHA1.Create();
            var hash = sha1.ComputeHash(Encoding.UTF8.GetBytes(input));
            var sb = new StringBuilder(hash.Length * 2);

            foreach (byte b in hash)
            {
                sb.Append(b.ToString("x2"));
            }

            return sb.ToString();
        }
    }
}
C++
C++#include <iostream>
#include <iomanip>
#include <string>
#include <sstream>
#include <openssl/sha.h>

std::string sha1(const std::string &input)
{
    unsigned char hash[SHA_DIGEST_LENGTH];
    SHA1(reinterpret_cast<const unsigned char *>(input.c_str()), input.length(), hash);
    std::ostringstream oss;
    oss << std::hex << std::setfill('0');
    for (auto c : hash)
    {
        oss << std::setw(2) << static_cast<int>(c);
    }
    return oss.str();
}

std::string getChecksum(const std::string appSecret, std::string nonce, long curtime)
{
    return sha1(appSecret + nonce + std::to_string(curtime));
}

请求体(Body)

  • Content-Typeapplication/json
  • 格式:JSON
  • 编码:UTF-8
  • 适用请求:POST、PUT 等需要传递业务参数的请求

响应结果

API 返回结果的格式统一。Header 中返回 2xx HTTP 状态码代表接口调用成功。Header 中返回 4xx 或 5xx HTTP 状态码代表接口调用失败。调用失败时,部分接口会同时在 Body 中返回该调用的相关错误信息供您排查问题。

正常返回示例

接口调用成功后会返回接口返回参数,这样的返回为正常返回。正常返回的 HTTP Header 中的状态码为 2xx。

正常返回示例如下:

JSON{
    "code": 200,
    "cid": 12345,
    ...
}

异常返回示例

接口调用出错后,会返回错误码、错误信息,这样的返回为异常返回。HTTP Header 中的状态码为 4xx 或者 5xx。部分接口会在 Body 中返回具体的业务错误码和错误信息供您排查问题。

您可以根据接口调用后返回的错误码,参考 Header 中的状态码Body 中的错误码排查问题。当您无法排查问题时,可以 提交工单 联系网易云信技术支持工程师。

异常返回示例如下:

此文档是否对你有帮助?
有帮助
去反馈
  • 使用限制
  • 适用场景
  • 请求概述
  • 请求方式
  • 服务地址
  • 请求结构
  • 请求 URL
  • 请求头(Header)
  • 请求体(Body)
  • 响应结果
  • 正常返回示例
  • 异常返回示例