结构体

BasicAuthCredential

Java

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 版本新增。

成员参数

参数	数据类型	描述
username	String	从声网控制台获取的客户 ID。
password	String	从声网控制台获取的客户密钥。

HttpProperty

Java

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

Java

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

Java

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

Java

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;
}

配置智能体加入 RTC 频道的属性。

信息

自 v0.3.0 版本新增。

成员参数

参数	数据类型	描述
token	String	用于加入 RTC 频道的动态密钥（），即用于身份验证的动态密钥（可选）。如果项目启用了 ，则必须在此字段中传递动态密钥。
channel	String	智能体加入的 RTC 频道名称（必需）。
agentRtcUId	String	智能体在 RTC 频道中的用户 ID（必需）。填入 "0" 表示随机分配，但需要相应修改动态密钥（）。
remoteRtcUIds	List<String>	智能体在 RTC 频道中订阅的用户 ID 列表，只有被订阅的用户才能与智能体互动（必需）。传递 "*" 表示订阅频道中的所有用户。
enableStringUId	Boolean	是否启用字符串 UID（可选）。 true：启用字符串 UID。 false：不启用字符串 UID（默认）。
idleTimeout	Integer	RTC 频道的最大空闲时间（秒）（可选）。在 remoteRtcUIds 指定的所有用户离开频道后的时间被视为空闲时间。如果超过设定的最大值，智能体将自动停止并退出频道。如果设置为 0，智能体仅在手动退出时停止。
agentRtmUId	String	RTM 频道中的智能体用户 ID。仅在 advancedFeatures.enable_rtm 为 true 时有效。
advancedFeatures	AdvancedFeatures	高级功能配置（可选），详见 AdvancedFeatures。
llmPayload	LLMPayload	自定义语言模型（LLM）配置（必需），详见 LLMPayload。
ttsPayload	TTSPayload	文本转语音（TTS）模块配置（可选），详见 TTSPayload。
vadPayload	VADPayload	语音活动检测（VAD）配置（可选），详见 VADPayload。
asrPayload	ASRPayload	自动语音识别（ASR）配置（可选），详见 ASRPayload。

AdvancedFeatures

Java

public static class AdvancedFeatures {
    @JsonProperty("enable_aivad")
    private Boolean enableAIVad;
    @JsonProperty("enable_rtm")
    private Boolean enableRtm;
}

定义智能体加入 RTC 频道的高级功能配置。

信息

自 v0.3.0 版本新增。

成员参数

参数	数据类型	描述
enableAIVad	Boolean	是否启用优雅中断功能 (AIVAD)（可选）。 true: 启用。 false: 不启用（默认）。 启用后，用户可以随时打断 AI 并快速响应，实现自然过渡和流畅对话。
enableRtm	Boolean	是否启用实时消息 (RTM) 模块（可选）。 true: 启用。 false: 不启用（默认）。 启用后，智能体可以使用 RTM 提供的功能来实现一些高级功能。

LLMPayload

Java

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 的输入模式（可选）。 ["text"]: 仅文本（默认）。 ["text", "image"]: 文本和图像，要求所选 LLM 支持视觉模式输入。
outputModalities	List<String>	LLM 的输出模式（可选）。 ["text"]: 仅文本（默认），输出文本将由 TTS 模块转换为语音，然后发布到 RTC 频道。 ["audio"]: 仅音频。音频将直接发布到 RTC 频道。 ["text", "audio"]: 文本和音频。你可以根据需要编写自己的逻辑来处理 LLM 输出。
failureMessage	String	智能体的失败消息（可选）。如果填写，当 LLM 调用失败时，将通过 TTS 模块返回。

TTSPayload

Java

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

Java

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

Java

public static class MinimaxTTSVendorAudioSettingParam {
    @JsonProperty("sample_rate")
    private Integer sampleRate;
}

定义 Minimax 供应商音频设置参数。

信息

自 v0.3.0 版本新增。

成员参数

参数	数据类型	描述
sampleRate	Integer	采样率。

MinimaxTTSVendorVoiceSettingParam

Java

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

Java

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

Java

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 Token。
appId	String	Bytedance TTS App ID。
cluster	String	Bytedance TTS 集群。
voiceType	String	语音类型。
speedRatio	Float	速度比率。
volumeRatio	Float	音量比率。
pitchRatio	Float	音高比率。
emotion	String	情感。

VADPayload

Java

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

Java

public static class ASRPayload {
    @JsonProperty("language")
    private String language;
}

定义智能体加入 RTC 频道的自动语音识别 (ASR) 配置。

信息

自 v0.3.0 版本新增。

成员参数

参数	数据类型	描述
language	String	用户与智能体交互使用的语言（可选）。 zh-CN: 中文（支持中英文混合）（默认） en-US: 英文。

ListConvoAIReq

Java

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	查询的智能体状态，支持以下状态： IDLE (0): 智能体空闲。 STARTING (1): 智能体正在启动。 RUNNING (2): 智能体正在运行。 STOPPING (3): 智能体正在停止。 STOPPED (4): 智能体已停止。 RECOVERING (5): 智能体正在恢复。 FAILED (6): 智能体已失败。

UpdateConvoAIReq

Java

public class UpdateConvoAIReq {
    @JsonProperty("token")
    private String token;
}

调用对话式 AI 引擎更新 API 的请求体。

信息

自 v0.3.0 版本新增。

成员参数

参数	数据类型	描述
token	String	用于身份验证的动态密钥（）。如果项目启用了 ，则必须在此字段中传递动态密钥。

JoinConvoAIRes

Java

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	状态。以下状态可用： IDLE (0): 智能体空闲。 STARTING (1): 智能体正在启动。 RUNNING (2): 智能体正在运行。 STOPPING (3): 智能体正在停止。 STOPPED (4): 智能体已停止。 RECOVERING (5): 智能体正在恢复。 FAILED (6): 智能体失败。

ListConvoAIRes

Java

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

Java

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	状态。可用的状态有： IDLE (0): 智能体空闲。 STARTING (1): 智能体正在启动。 RUNNING (2): 智能体正在运行。 STOPPING (3): 智能体正在停止。 STOPPED (4): 智能体已停止。 RECOVERING (5): 智能体正在恢复。 FAILED (6): 智能体失败。
agentId	String	智能体的唯一标识符。

UpdateConvoAIRes

Java

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	状态。可用的状态有： IDLE (0): 智能体空闲。 STARTING (1): 智能体正在启动。 RUNNING (2): 智能体正在运行。 STOPPING (3): 智能体正在停止。 STOPPED (4): 智能体已停止。 RECOVERING (5): 智能体正在恢复。 FAILED (6): 智能体失败。