结构体
BasicAuthCredential
public class BasicAuthCredential implements Credential {
private final String username;
private final String password;
private final static String name = "BasicAuth";
public BasicAuthCredential(String username, String password) {
this.username = username;
this.password = password;
}
}
BasicAuthCredential
提供对声网 REST Client 的基本身份验证。
自 v0.3.0 版本新增。
成员参数
HttpProperty
public class HttpProperty {
private final int httpConnectionPoolSize;
private final int httpConnectionMaxIdleTime;
private final int httpConnectionMaxLifeTime;
private final int httpConnectionEvictInBackground;
private final int httpConnectionPendingAcquireTimout;
private final int httpConnectionPendingAcquireMaxCount;
}
HttpProperty
表示 HTTP 客户端的属性。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
httpConnectionPoolSize | int | 连接池中的最大连接数。 |
httpConnectionMaxIdleTime | int | 连接池中连接的最大空闲时间,单位:毫秒。 |
httpConnectionMaxLifeTime | int | 连接池中连接的最大生命周期,单位:毫秒。 |
httpConnectionEvictInBackground | int | 在后台驱逐连接的时间,单位:毫秒。 |
httpConnectionPendingAcquireTimout | int | 从连接池获取连接的超时时间,单位:毫秒。 |
httpConnectionPendingAcquireMaxCount | int | 保持在挂起队列中的最大注册请求数。 |
ConvoAIConfig
public class ConvoAIConfig {
private final String appId;
private final Credential credential;
private final DomainArea domainArea;
private final HttpProperty httpProperty;
private final ConvoAIServiceRegionEnum serviceRegion;
}
定义对话式 AI 引擎 REST Client 的配置。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
appId | String | 声网 。 |
credential | Credential | 用于访问声网服务的凭证。可用的凭证类型:BasicAuthCredential 。 |
domainArea | DomainArea | REST Client 的域区域。详见 DomainArea 。 |
httpProperty | HttpProperty | REST Client 的 HTTP 属性。详见 HttpProperty 。 |
serviceRegion | ConvoAIServiceRegionEnum | 对话式 AI 引擎的服务区域。详见 ConvoAIServiceRegionEnum 。 |
JoinConvoAIReq
public class JoinConvoAIReq {
@JsonProperty("name")
private String name;
@JsonProperty("properties")
private Properties properties;
}
调用对话式 AI 引擎 join
API 的请求体参数。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
name | String | 智能体的唯一标识符,不能重复。 |
properties | Properties | 智能体的配置属性,详见 Properties 。 |
Properties
public static class Properties {
@JsonProperty("token")
private String token;
@JsonProperty("channel")
private String channel;
@JsonProperty("agent_rtc_uid")
private String agentRtcUId;
@JsonProperty("remote_rtc_uids")
private List<String> remoteRtcUIds;
@JsonProperty("enable_string_uid")
private Boolean enableStringUId;
@JsonProperty("idle_timeout")
private Integer idleTimeout;
@JsonProperty("agent_rtm_uid")
private String agentRtmUId;
@JsonProperty("advanced_features")
private AdvancedFeatures advancedFeatures;
@JsonProperty("llm")
private LLMPayload llmPayload;
@JsonProperty("tts")
private TTSPayload ttsPayload;
@JsonProperty("vad")
private VADPayload vadPayload;
@JsonProperty("asr")
private ASRPayload asrPayload;
@JsonProperty("parameters")
private Map<String, Object> parameters;
}
配置智能体加入 RTC 频道的属性。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
token | String | (可选)用于加入 RTC 频道的 ,即用于鉴权的动态密钥。如果项目启用了 ,则必须在该字段中传入动态密钥。 |
channel | String | (必需)智能体加入的 RTC 频道名称。 |
agentRtcUId | String | (必填)智能体在 RTC 频道中的用户 ID。填入 "0" 表示随机分配,但需要相应地修改 token 。 |
remoteRtcUIds | List<String> | (必填)智能体在 RTC 频道中订阅的用户 ID 列表,仅订阅的用户可以与智能体交互。传入 "*" 表示订阅频道内所有用户。 |
enableStringUId | Boolean | (可选)是否启用字符串 UID。
|
idleTimeout | Integer | (可选)RTC 频道的最大空闲时间(单位:秒)。当 remoteRtcUIds 中指定的所有用户离开频道后,开始计算空闲时间。若超过设定的最大值,智能体将自动停止并退出频道。若设置为 0,则只能通过手动退出来停止智能体。 |
agentRtmUId | String | (可选)RTM 频道中的智能体用户 ID。仅在 advancedFeatures.enableRtm 为 true 时有效。 |
advancedFeatures | AdvancedFeatures | (可选)高级功能配置,详见 AdvancedFeatures 。 |
llmPayload | LLMPayload | (必填)自定义语言模型(LLM)配置,详见 LLMPayload 。 |
ttsPayload | TTSPayload | (可选)文本转语音模块配置,详见 TTSPayload 。 |
vadPayload | VADPayload | (可选)语音活动检测配置,详见 VADPayload 。 |
asrPayload | ASRPayload | (可选)自动语音识别配置,详见 ASRPayload 。 |
parameters | Map<String, Object> | (可选)用于传递任意扩展参数的字段。 |
AdvancedFeatures
public static class AdvancedFeatures {
@JsonProperty("enable_aivad")
private Boolean enableAIVad;
@JsonProperty("enable_rtm")
private Boolean enableRtm;
}
定义智能体加入 RTC 频道的高级功能配置。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
enableAIVad | Boolean | 是否启用优雅中断功能 (AIVAD)(可选)。
|
enableRtm | Boolean | 是否启用实时消息 (RTM) 模块(可选)。
|
LLMPayload
public static class LLMPayload {
@JsonProperty("url")
private String url;
@JsonProperty("api_key")
private String apiKey;
@JsonProperty("system_messages")
private List<Map<String, Object>> systemMessages;
@JsonProperty("params")
private HashMap<String, Object> params;
@JsonProperty("max_history")
private Integer maxHistory;
@JsonProperty("greeting_message")
private String greetingMessage;
@JsonProperty("input_modalities")
private List<String> inputModalities;
@JsonProperty("output_modalities")
private List<String> outputModalities;
@JsonProperty("failure_message")
private String failureMessage;
}
定义智能体加入 RTC 频道的自定义语言模型 (LLM) 配置。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
url | String | LLM 回调 URL(必需)。必须与 OpenAI 协议兼容。 |
apiKey | String | LLM 验证 API 密钥(必需)。默认值为空,API 密钥必须在生产环境中启用。 |
systemMessages | List<Map<String, Object>> | 在每次 LLM 调用开始时附加的一组预定义信息,用于控制 LLM 输出(可选)。可以是角色设置、提示和答案示例,必须与 OpenAI 协议兼容。 |
params | HashMap<String, Object> | 在 LLM 消息体中传输的附加信息,例如使用的模型、最大令牌限制等(可选)。不同的 LLM 提供商支持不同的配置,详见各自的 LLM 文档。 |
maxHistory | Integer | LLM 中缓存的短期记忆条目数(可选)。默认值为 10。传递 0 表示不缓存短期记忆。智能体和订阅用户将分别记录条目。 |
greetingMessage | String | 智能体问候消息(可选)。如果填写,当 remote_rtc_uids 列表中没有用户时,智能体将自动向第一个加入频道的订阅用户发送问候消息。 |
inputModalities | List<String> | LLM 的输入模式(可选)。
|
outputModalities | List<String> | LLM 的输出模式(可选)。
|
failureMessage | String | 智能体的失败消息(可选)。如果填写,当 LLM 调用失败时,将通过 TTS 模块返回。 |
TTSPayload
public static class TTSPayload {
@JsonProperty("vendor")
private TTSVendorEnum vendor;
@JsonProperty("params")
private TTSVendorParams params;
}
定义智能体加入 RTC 频道的文本转语音 (TTS) 模块配置。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
vendor | TTSVendorEnum | TTS 供应商,详见 TTSVendorEnum 。 |
params | TTSVendorParams | TTS 供应商参数描述,详见 MinimaxTTSVendorParams 、TencentTTSVendorParams 、BytedanceTTSVendorParams 。 |
MinimaxTTSVendorParams
public static class MinimaxTTSVendorParams implements TTSVendorParams {
@JsonProperty("group_id")
private String groupId;
@JsonProperty("key")
private String key;
@JsonProperty("model")
private String model;
@JsonProperty("audio_setting")
private MinimaxTTSVendorAudioSettingParam audioSetting;
@JsonProperty("voice_setting")
private MinimaxTTSVendorVoiceSettingParam voiceSetting;
}
定义 MinimaxTTSVendorParams
模块参数。
自 v0.3.0 版本新增。
更多信息详见Minimax。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
groupId | String | 组 ID。 |
key | String | API 密钥。 |
model | String | 模型。 |
audioSetting | MinimaxTTSVendorAudioSettingParam | 音频设置,详见 MinimaxTTSVendorAudioSettingParam 。 |
voiceSetting | MinimaxTTSVendorVoiceSettingParam | 语音设置,详见 MinimaxTTSVendorVoiceSettingParam 。 |
MinimaxTTSVendorAudioSettingParam
public static class MinimaxTTSVendorAudioSettingParam {
@JsonProperty("sample_rate")
private Integer sampleRate;
}
定义 Minimax 供应商音频设置参数。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
sampleRate | Integer | 采样率。 |
MinimaxTTSVendorVoiceSettingParam
public static class MinimaxTTSVendorVoiceSettingParam {
@JsonProperty("voice_id")
private String voiceId;
@JsonProperty("speed")
private Float speed;
@JsonProperty("vol")
private Float vol;
@JsonProperty("pitch")
private Integer pitch;
@JsonProperty("emotion")
private String emotion;
}
定义 MinimaxTTSVendorVoiceSettingParam
,用于设置 Minimax 供应商的语音参数。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
voiceId | String | 语音 ID。 |
speed | Float | 语速。 |
vol | Float | 音量。 |
pitch | Integer | 音调。 |
emotion | String | 情感。 |
TencentTTSVendorParams
public static class TencentTTSVendorParams implements TTSVendorParams {
@JsonProperty("app_id")
private String appId;
@JsonProperty("secret_id")
private String secretId;
@JsonProperty("secret_key")
private String secretKey;
@JsonProperty("voice_type")
private Integer voiceType;
@JsonProperty("volume")
private Integer volume;
@JsonProperty("speed")
private Integer speed;
@JsonProperty("emotion_category")
private String emotionCategory;
@JsonProperty("emotion_intensity")
private Integer emotionIntensity;
}
定义腾讯 TTS 模块参数。
自 v0.3.0 版本新增。
更多信息详见Tencent。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
appId | String | 腾讯云 TTS App ID。 |
secretId | String | 腾讯云 TTS Secret ID。 |
secretKey | String | 腾讯云 TTS Secret Key。 |
voiceType | Integer | 语音类型。 |
volume | Integer | 音量。 |
speed | Integer | 语速。 |
emotionCategory | String | 情感类别。 |
emotionIntensity | Integer | 情感强度。 |
BytedanceTTSVendorParams
public static class BytedanceTTSVendorParams implements TTSVendorParams {
@JsonProperty("token")
private String token;
@JsonProperty("app_id")
private String appId;
@JsonProperty("cluster")
private String cluster;
@JsonProperty("voice_type")
private String voiceType;
@JsonProperty("speed_ratio")
private Float speedRatio;
@JsonProperty("volume_ratio")
private Float volumeRatio;
@JsonProperty("pitch_ratio")
private Float pitchRatio;
@JsonProperty("emotion")
private String emotion;
}
定义 Bytedance TTS 模块参数。
自 v0.3.0 版本新增。
详见 Bytedance。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
token | String | Bytedance TTS 。 |
appId | String | Bytedance TTS App ID。 |
cluster | String | Bytedance TTS 集群。 |
voiceType | String | 语音类型。 |
speedRatio | Float | 速度比率。 |
volumeRatio | Float | 音量比率。 |
pitchRatio | Float | 音高比率。 |
emotion | String | 情感。 |
VADPayload
public static class VADPayload {
@JsonProperty("interrupt_duration_ms")
private Integer interruptDurationMs;
@JsonProperty("prefix_padding_ms")
private Integer prefixPaddingMs;
@JsonProperty("silence_duration_ms")
private Integer silenceDurationMs;
@JsonProperty("threshold")
private Float threshold;
}
定义智能体加入 RTC 频道的语音活动检测 (VAD) 配置。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
interruptDurationMs | Integer | 人声时长阈值(毫秒),范围 [120, 1200](可选)。连续人声信号的最短持续时间,以避免误中断。 |
prefixPaddingMs | Integer | 前缀填充阈值(毫秒),范围 [0, 5000](可选)。开始新的语音片段所需的最短语音持续时间,以避免因非常短的声音触发语音活动检测。 |
silenceDurationMs | Integer | 静音时长阈值(毫秒),范围 [0, 2000](可选)。语音结束时的最短静音持续时间,以确保短暂停顿不会过早结束语音片段。 |
threshold | Float | 语音识别灵敏度,范围 (0.0,1.0)(可选)。确定音频信号中被视为“语音活动”的声音级别。较低的值使智能体更容易检测到语音,而较高的值可能会忽略微弱的声音。 |
ASRPayload
public static class ASRPayload {
@JsonProperty("language")
private String language;
}
定义智能体加入 RTC 频道的自动语音识别 (ASR) 配置。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
language | String | 用户与智能体交互使用的语言(可选)。
|
ListConvoAIReq
public class ListConvoAIReq {
private final String channel;
private final Integer limit;
private final String cursor;
private final Long fromTime;
private final Long toTime;
private final Integer state;
}
定义用于查询对话式智能体列表的过滤条件类型。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
channel | String | 设置频道名称。 |
limit | Integer | 设置项目数量。限制每页返回的项目数量,默认值为 20。 |
cursor | String | 设置分页游标。分页游标,即分页起始位置的智能体 ID。 |
fromTime | Long | 设置结束时间戳。结束时间戳(秒),默认值为当前时间。 |
toTime | Long | 设置开始时间戳。开始时间戳(秒),默认值为 1 天前。 |
state | Integer | 查询的智能体状态,支持以下状态:
|
UpdateConvoAIReq
public class UpdateConvoAIReq {
@JsonProperty("token")
private String token;
}
调用对话式 AI 引擎更新 API 的请求体。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
token | String | 用于身份验证的动态密钥()。如果项目启用了 ,则必须在此字段中传递动态密钥。 |
JoinConvoAIRes
public class JoinConvoAIRes {
@JsonProperty("agent_id")
private String agentId;
@JsonProperty("create_ts")
private Integer createTs;
@JsonProperty("status")
private String status;
}
对话式 AI 引擎 join
API 返回的响应。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
agentId | String | 智能体的唯一标识符。 |
createTs | Integer | 智能体创建时的时间戳。 |
status | String | 状态。以下状态可用:
|
ListConvoAIRes
public class ListConvoAIRes {
@JsonProperty("data")
private Data data;
@JsonProperty("meta")
private Meta meta;
@JsonProperty("status")
private String status;
@Override
public String toString() {
return "ListConvoAIRes{" +
"data=" + data +
", meta=" + meta +
", status='" + status + '\'' +
'}';
}
public static class Data {
@JsonProperty("count")
private Integer count;
@JsonProperty("list")
private List<Agent> list;
@Override
public String toString() {
return "Data{" +
"count=" + count +
", list=" + list +
'}';
}
}
public static class Agent {
@JsonProperty("agent_id")
private String agentId;
@JsonProperty("start_ts")
private Integer startTs;
@JsonProperty("status")
private String status;
@Override
public String toString() {
return "Agent{" +
"agentId='" + agentId + '\'' +
", startTs=" + startTs +
", status='" + status + '\'' +
'}';
}
}
public static class Meta {
@JsonProperty("total")
private Integer total;
@JsonProperty("cursor")
private String cursor;
@Override
public String toString() {
return "Meta{" +
"total=" + total +
", cursor='" + cursor + '\'' +
'}';
}
}
}
对话式 AI 引擎 List
API 返回的响应。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
data | Data | 智能体数据信息。 |
meta | Meta | 返回列表的元数据。 |
status | String | 请求状态。 |
QueryConvoAIRes
public class QueryConvoAIRes {
@JsonProperty("message")
private String message;
@JsonProperty("start_ts")
private Integer startTs;
@JsonProperty("stop_ts")
private Integer stopTs;
@JsonProperty("status")
private String status;
@JsonProperty("agent_id")
private String agentId;
}
对话式 AI 引擎查询 API 返回的响应。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
message | String | 请求消息。 |
startTs | Integer | 智能体创建的时间戳。 |
stopTs | Integer | 智能体停止的时间戳。 |
status | String | 状态。可用的状态有:
|
agentId | String | 智能体的唯一标识符。 |
UpdateConvoAIRes
public class UpdateConvoAIRes {
@JsonProperty("agent_id")
private String agentId;
@JsonProperty("create_ts")
private Integer createTs;
@JsonProperty("state")
private String state;
}
对话式 AI 引擎更新 API 返回的响应。
自 v0.3.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
agentId | String | 智能体的唯一标识符。 |
createTs | Integer | 智能体创建的时间戳。 |
state | String | 状态。可用的状态有:
|
SpeakConvoAIReq
public class SpeakConvoAIReq {
private String text;
private String priority;
private Boolean interrupt;
public static Builder builder() {
return new Builder();
}
public static class Builder {
private String text;
private String priority;
private Boolean interrupt;
public Builder text(String text) {
this.text = text;
return this;
}
public Builder priority(String priority) {
this.priority = priority;
return this;
}
public Builder interrupt(Boolean interrupt) {
this.interrupt = interrupt;
return this;
}
public SpeakConvoAIReq build() {
return new SpeakConvoAIReq(this);
}
}
private SpeakConvoAIReq(Builder builder) {
setText(builder.text);
setPriority(builder.priority);
setInterrupt(builder.interrupt);
}
public void setText(String text) {
this.text = text;
}
public void setPriority(String priority) {
this.priority = priority;
}
public void setInterrupt(Boolean interrupt) {
this.interrupt = interrupt;
}
public String getText() {
return text;
}
public String getPriority() {
return priority;
}
public Boolean getInterrupt() {
return interrupt;
}
}
调用对话式智能体语音 API 时使用的请求参数。
自 v0.4.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
text | String | (必填)需语音播报的文本内容,最大长度为 512 字节。 |
priority | String | (可选)语音行为的优先级,可选值如下:
|
interrupt | Boolean | (可选)是否允许用户说话打断智能体的语音播报:
|
HistoryConvoAIRes
public class HistoryConvoAIRes {
@JsonProperty("start_ts")
private Long startTs;
@JsonProperty("agent_id")
private String agentId;
@JsonProperty("status")
private String status;
@JsonProperty("contents")
private List<HistoryContent> contents;
}
表示 getHistory
API 返回的响应内容。
自 v0.4.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
startTs | Long | 智能体的创建时间戳。 |
agentId | String | 智能体的唯一标识符。 |
status | String | 智能体的运行状态。 |
contents | List<HistoryContent> | 智能体的短期记忆内容。详见 HistoryContent 。 |
HistoryContent
public static class HistoryContent {
@JsonProperty("content")
private String content;
@JsonProperty("role")
private String role;
public String getContent() {
return content;
}
public void setContent(String content) {
this.content = content;
}
public String getRole() {
return role;
}
public void setRole(String role) {
this.role = role;
}
@Override
public String toString() {
return "HistoryContent{" +
"content='" + content + '\'' +
", role='" + role + '\'' +
'}';
}
}
表示智能体短期记忆内容。
自 v0.4.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
content | String | 消息的内容。 |
role | String | 发送消息的角色:
|
InterruptConvoAIRes
public class InterruptConvoAIRes {
@JsonProperty("agent_id")
private String agentId;
@JsonProperty("start_ts")
private Integer startTs;
@JsonProperty("channel")
private String channel;
}
封装会话式 AI 引擎中断 API 的响应信息。
自 v0.4.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
agentId | String | 智能体的唯一标识符。 |
startTs | Integer | 智能体的启动时间戳。 |
channel | String | 频道名。 |
SpeakConvoAIRes
public class SpeakConvoAIRes {
@JsonProperty("agent_id")
private String agentId;
@JsonProperty("start_ts")
private Integer startTs;
@JsonProperty("channel")
private String channel;
@Override
public String toString() {
return "SpeakConvoAIRes{" +
"agentId='" + agentId + '\'' +
", startTs=" + startTs +
", channel='" + channel + '\'' +
'}';
}
public String getAgentId() {
return agentId;
}
public void setAgentId(String agentId) {
this.agentId = agentId;
}
public Integer getStartTs() {
return startTs;
}
public void setStartTs(Integer startTs) {
this.startTs = startTs;
}
public String getChannel() {
return channel;
}
public void setChannel(String channel) {
this.channel = channel;
}
}
表示会话式 AI 引擎 speak
API 返回的响应结果。
自 v0.4.0 版本新增。
成员参数
参数 | 数据类型 | 描述 |
---|---|---|
agentId | String | 智能体的唯一标识符。 |
startTs | Integer | 智能体的启动时间戳。 |
channel | String | 频道名。 |