API 参考--实时音视频-火山引擎

文档中心

导航

实时音视频

API 参考

最近更新时间：2025.11.19 11:51:38首次发布时间：2025.09.01 21:29:30

volc_get_version

获取当前 SDK 版本信息。

const char* volc_get_version(void);

传入参数

无

返回值

当前 SDK 版本信息。

volc_err_2_str

获取 SDK 内各种错误码、告警码的描述文字。

const char* volc_err_2_str(int err_code);

传入参数

参数名	类型	说明
err_code	int	需要获取描述的错误码

返回值

错误码的文本描述。

volc_create

创建 SDK 实例。

int volc_create(volc_engine_t* handle, const char* config_json, volc_event_handler_t event_handler, void* user_data);

传入参数

参数名	类型	说明
handle	volc_engine_t*	创建的引擎实例
config_json	const char*	一个 JSON 格式的字符串，包含所有初始化所需配置。具体配置项，请参看配置示例。
event_handler	volc_event_handler_t	SDK 回调给应用层的 Callback 对象，参看 volc_event_handler_t。
user_data	void*	用户设置的自定义数据

config_json 配置示例

低负载方案：

{
  "ver": 1,
  "iot": {
    "instance_id": "******", // 实例 ID，通过控制台获取
    "product_key": "******", // 产品 KEY，通过控制台获取
    "product_secret": "******", // 产品密钥，通过控制台获取
    "device_name": "device_name" // 设备名，可自行指定
  },
  "ws": {
      "audio" : {
          "codec": 4 // 音频数据类型，可通过“数据类型”了解枚举值
      }
  }
}

高质量方案：

{
  "ver": 1,
  "iot": {
    "instance_id": "******", // 实例ID，通过控制台获取
    "product_key": "******", // 产品KEY，通过控制台获取
    "product_secret": "******", // 产品密钥，通过控制台获取
    "device_name": "device_name" // 设备名，可自行指定
  },
  "rtc": { // rtc方案配置
      "log_level": 3, // rtc 日志等级，1：info，2：warn，3：error
      "audio" : {
        "publish": true,
        "subscribe": true,
        "codec": 3
      },
      "video" : {
        "publish": false,
        "subscribe": false,
        "codec": 1 // 音频数据类型，可通过“数据类型”了解枚举值
      },
      "params": [
        "{\"audio\":{\"codec\":{\"internal\":{\"enable\":1}}}}"
      ]
  }
}

返回值

0：创建成功。
<0：创建失败。

volc_destroy

销毁 volc_create 所创建的引擎实例，并释放所有相关资源。

void volc_destroy(volc_engine_t handle);

传入参数

参数名	类型	说明
handle	volc_engine_t	待销毁的引擎实例

返回值

无

volc_start

启动智能体。

int volc_start(volc_engine_t handle, volc_opt_t* opt);

传入参数

参数名	类型	说明
handle	volc_engine_t	引擎实例，参看 volc_engine_t 。
opt	volc_opt_t*	会话参数

返回值

0：成功。
<0：失败。参看 volc_error_code_e。

volc_stop

停止与智能体对话。

int volc_stop(volc_engine_t handle);

传入参数

参数名	类型	说明
handle	volc_engine_t	引擎实例，参看 volc_engine_t。

返回值

0：成功。
<0：失败。参看 volc_error_code_e。

volc_update

更新智能体。

int volc_update(volc_engine_t handle, const void* config_json, size_t config_len);

传入参数

参数名	类型	说明
handle	volc_engine_t	引擎实例
config_json	const void*	智能体配置
config_len	size_t	配置长度

返回值

0：成功。
<0：失败。参看 volc_error_code_e。

volc_send_audio_data

推送本地采集的音频数据。

int volc_send_audio_data(volc_engine_t handle, const void* data_ptr, size_t data_len, volc_audio_frame_info_t* info_ptr);

传入参数

参数名	类型	说明
handle	volc_engine_t	引擎实例，参看 volc_engine_t。
data_ptr	const void*	音频数据。
data_len	size_t	音频数据长度，单位：字节。
info_ptr	volc_audio_frame_info_t*	音频数据描述信息，参看 volc_audio_frame_info_t。

返回值

0：成功。
<0：失败。参看 volc_error_code_e。

volc_send_video_data

推送视频帧数据。

int volc_send_video_data(volc_engine_t handle, const void* data_ptr, size_t data_len, volc_video_frame_info_t* info_ptr);

传入参数

参数名	类型	说明
handle	volc_engine_t	引擎实例，参看 volc_engine_t。
data_ptr	const void*	视频数据。
data_len	size_t	视频数据长度，单位：字节。
info_ptr	volc_video_frame_info_t*	视频数据描述信息，参看 volc_video_frame_info_t。

返回值

0：成功。
<0：失败。参看 volc_error_code_e。

volc_send_message

推送自定义消息。

int volc_send_message(volc_engine_t handle, const void* data_ptr, size_t data_len, volc_message_info_t* info_ptr);

传入参数

参数名	类型	说明
handle	volc_engine_t	引擎实例，参看 volc_engine_t。
data_ptr	const void*	消息数据。
data_len	size_t	消息长度，单位：字节。
info_ptr	volc_message_info_t*	消息数据描述信息，参看 volc_message_info_t。

返回值

0：成功。
<0：失败。参看 volc_error_code_e。

volc_interrupt

打断智能体。

int volc_interrupt(volc_engine_t handle);

传入参数

参数名	类型	说明
handle	volc_engine_t	引擎实例，参看 volc_engine_t。

返回值

0：成功。
<0：失败。参看 volc_error_code_e。