Quick Start

2026-07-13

Prerequisites

You have created a project in the ZEGOCLOUD Console and obtained a valid AppID and AppSign. For details, refer to Console - Project Information.
You have contacted ZEGOCLOUD Technical Support to enable the cloud real-time speech recognition service.

Usage Steps

Sequence Diagram

The core steps for using the real-time speech recognition service are shown in the blue blocks in the diagram. After your business server calls the Start Cloud Real-Time ASR interface, the cloud real-time ASR server will recognize all or specified audio streams in the room and callback the recognition results to your business server through the pre-configured callback address.

If you need to implement scenarios such as real-time subtitles that require displaying recognition content on the client side, please refer to the Display Subtitles document to use the subtitle component or implement custom subtitle display for recognition results.

Note

Please contact ZEGOCLOUD Technical Support to configure the callback address for receiving recognition results.

Note

If no real user exists in the RTC room after 120 seconds (default value, configurable), the cloud real-time speech recognition service will automatically stop and trigger a callback with Event as Exception and Data.Code as 1202. For details, refer to Return Codes.

Integrate ZEGO Express SDK

Please refer to the client SDK integration and quick start documentation for implementing video or voice calls to complete client SDK integration and stream publishing.

Integrate ZEGO Express SDK

Implement Video or Voice Call

Client Best Configuration Practices

For optimal recognition results, we recommend the following configurations when using the ZEGO Express SDK on the client side:

Note

For configuration on other platforms, please contact ZEGOCLOUD Technical Support for details.

Business Server Starts Cloud Speech Recognition

The following is sample code for the business server to start cloud speech recognition and receive recognition and translation results (using Node.js as an example):

Start Cloud Real-Time ASR

const https = require('https');
const querystring = require('querystring');

// !mark(1:10)
const data = JSON.stringify({
  "RoomId": "room_1",
  "ASR": {
    "Params": {
      "engine_model_type": "16k_zh"
    },
    "VADSilenceSegmentation": 500
  },
  "SubtitleType": 1 // Subtitle delivery type, default is 0. 0: No delivery; 1: Recognition results only (e.g., when a user says "你好" in Chinese, delivers "你好"); 2: Translation results only (e.g., when a user says "你好" in Chinese, delivers the translated "Hello"); 3: Both recognition and translation results (e.g., when a user says "你好" in Chinese, delivers both "你好" and "Hello"). If you need to display subtitles on the client, it is recommended to set this to 1, 2, or 3. For details, see [Display Subtitles](./guides/display-subtitles.mdx)
});

const params = {
  Action: 'StartRealtimeASRTask',
  AppId: '1234567890',
  SignatureNonce: 'vecj0mc2jcl',
  Timestamp: '1753691152',
  Signature: 'e8032aabe7702091b0bb2ca83cc2f98a',
  SignatureVersion: '2.0'
};

const options = {
  hostname: 'cloud-realtime-asr-api.zegotech.cn',
  path: '/?' + querystring.stringify(params),
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request(options, (res) => {
  let responseData = '';

  res.on('data', (chunk) => {
    responseData += chunk;
  });

  res.on('end', () => {
    console.log('Response:', JSON.parse(responseData));
  });
});

req.on('error', (error) => {
  console.error('Error:', error);
});

req.write(data);
req.end();

const https = require('https');
const querystring = require('querystring');

// !mark(1:10)
const data = JSON.stringify({
  "RoomId": "room_1",
  "ASR": {
    "Params": {
      "engine_model_type": "16k_zh"
    },
    "VADSilenceSegmentation": 500
  },
  "SubtitleType": 1 // Subtitle delivery type, default is 0. 0: No delivery; 1: Recognition results only (e.g., when a user says "你好" in Chinese, delivers "你好"); 2: Translation results only (e.g., when a user says "你好" in Chinese, delivers the translated "Hello"); 3: Both recognition and translation results (e.g., when a user says "你好" in Chinese, delivers both "你好" and "Hello"). If you need to display subtitles on the client, it is recommended to set this to 1, 2, or 3. For details, see [Display Subtitles](./guides/display-subtitles.mdx)
});

const params = {
  Action: 'StartRealtimeASRTask',
  AppId: '1234567890',
  SignatureNonce: 'vecj0mc2jcl',
  Timestamp: '1753691152',
  Signature: 'e8032aabe7702091b0bb2ca83cc2f98a',
  SignatureVersion: '2.0'
};

const options = {
  hostname: 'cloud-realtime-asr-api.zegotech.cn',
  path: '/?' + querystring.stringify(params),
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request(options, (res) => {
  let responseData = '';

  res.on('data', (chunk) => {
    responseData += chunk;
  });

  res.on('end', () => {
    console.log('Response:', JSON.parse(responseData));
  });
});

req.on('error', (error) => {
  console.error('Error:', error);
});

req.write(data);
req.end();

Get Recognition or Translation Results

Get Recognition or Translation Results via Server Callback (Non-streaming)

Callback Interface Usage Example

// Business server ASR callback
function asrCallBack(req, res) {
    const { AppId, RoomId, Event, Data } = req.body;
  // Verify signature parameter callbacksecret obtained from console
  // Signature verification documentation: https://www.zegocloud.com/docs/cloud-realtime-asr/callbacks/receiving-callback#verify-signature
  const calcSign = genCallbackSignature(Nonce, callbacksecret, Timestamp);
  // Signature error
  if (calcSign !== Signature) {
    res.json({
      Code: -1,
      Message: "Signature error",
    });
    return;
  }
    // Return response
  res.json({
    Code: 0,
    Message: "ok",
  });
   switch (Event) {
    // Exception event
    case "ASRResult":
      // Process recognition results according to actual business needs
      handleData(Data);
      break;
    case "TranslationResult":
      // Process translation results according to actual business needs
      handleData(Data);
      break;
    default:
      break;
  }
}

// Business server ASR callback
function asrCallBack(req, res) {
    const { AppId, RoomId, Event, Data } = req.body;
  // Verify signature parameter callbacksecret obtained from console
  // Signature verification documentation: https://www.zegocloud.com/docs/cloud-realtime-asr/callbacks/receiving-callback#verify-signature
  const calcSign = genCallbackSignature(Nonce, callbacksecret, Timestamp);
  // Signature error
  if (calcSign !== Signature) {
    res.json({
      Code: -1,
      Message: "Signature error",
    });
    return;
  }
    // Return response
  res.json({
    Code: 0,
    Message: "ok",
  });
   switch (Event) {
    // Exception event
    case "ASRResult":
      // Process recognition results according to actual business needs
      handleData(Data);
      break;
    case "TranslationResult":
      // Process translation results according to actual business needs
      handleData(Data);
      break;
    default:
      break;
  }
}

Get and Display Recognition or Translation Results via RTC Room Signaling (Streaming)

If you need to display recognition or translation results on the client side, please refer to the Display Subtitles document to use the subtitle component or implement custom subtitle display for recognition results.

Stop Cloud Speech Recognition

Stop Cloud Real-Time ASR

const https = require('https');
const querystring = require('querystring');

const data = JSON.stringify({
  "TaskId": "1920370518175780864"
});

const params = {
  Action: 'StopRealtimeASRTask',
  AppId: '1234567890',
  SignatureNonce: 'vecj0mc2jcl',
  Timestamp: '1753691152',
  Signature: 'e8032aabe7702091b0bb2ca83cc2f98a',
  SignatureVersion: '2.0'
};

const options = {
  hostname: 'cloud-realtime-asr-api.zegotech.cn',
  path: '/?' + querystring.stringify(params),
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request(options, (res) => {
  let responseData = '';

  res.on('data', (chunk) => {
    responseData += chunk;
  });

  res.on('end', () => {
    console.log('Response:', JSON.parse(responseData));
  });
});

req.on('error', (error) => {
  console.error('Error:', error);
});

req.write(data);
req.end();

const https = require('https');
const querystring = require('querystring');

const data = JSON.stringify({
  "TaskId": "1920370518175780864"
});

const params = {
  Action: 'StopRealtimeASRTask',
  AppId: '1234567890',
  SignatureNonce: 'vecj0mc2jcl',
  Timestamp: '1753691152',
  Signature: 'e8032aabe7702091b0bb2ca83cc2f98a',
  SignatureVersion: '2.0'
};

const options = {
  hostname: 'cloud-realtime-asr-api.zegotech.cn',
  path: '/?' + querystring.stringify(params),
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request(options, (res) => {
  let responseData = '';

  res.on('data', (chunk) => {
    responseData += chunk;
  });

  res.on('end', () => {
    console.log('Response:', JSON.parse(responseData));
  });
});

req.on('error', (error) => {
  console.error('Error:', error);
});

req.write(data);
req.end();