AIGCService API 参考

  • Android

更新时间

AIGCService SDK 主要包含以下两大类:

  • AIGCService 类:提供 AIGC 服务的核心类,包含实现 AIGC 场景各功能的核心方法。
  • AIGCServiceCallback 类:AIGCService 异步方法的事件回调类。

本文提供 AIGCService SDK 的 API 参考。

AIGCService

create

Java
AIGCService create();

创建 AIGCService 实例。

返回值

成功创建后,该方法会返回一个 AIGCService 实例。

initialize

Java
void initialize(AIGCServiceConfig config);

初始化 AIGCService。

该方法为异步操作。调用结果会在 onEventResult 回调中返回。

参数

参数描述
configAIGCService 初始化参数。详见 AIGCServiceConfig。
表格内容超出当前宽度,可横向滚动查看更多列。

getRoles

Java
AIRole[] getRoles();

获取 SDK 支持的所有的 AIRole 数组。

注意

该方法需要在成功调用 initialize,且收到 onEventResult(INITIALIZE, SUCCESS) 后调用。

返回值

SDK 支持的 AIRole 数组。

setRole

Java
void setRole(String roleId);

设置 SDK 使用的 AIRole。该方法设置即时生效。

注意

该方法需要在成功调用 initialize,且收到 onEventResult(INITIALIZE, SUCCESS) 后调用。

参数

参数描述
roleId标明 AIRole 的 ID。
表格内容超出当前宽度,可横向滚动查看更多列。

getCurrentRole

Java
AIRole getCurrentRole()

获取当前使用的 AIRole。

注意

该方法需要在成功调用 initialize,且收到 onEventResult(INITIALIZE, SUCCESS) 后调用。

返回值

当前使用的 AIRole。

getServiceVendors

Java
ServiceVendorGroup getServiceVendors();

获取所有 AI 服务商的信息。

注意

该方法需要在成功调用 initialize,且收到 onEventResult(INITIALIZE, SUCCESS) 后调用。

返回值

包含了所有 AI 服务商信息的 ServiceVendorGroup 对象,由多个 STTVendor、LLMVendor 和 TTSVendor 组成。

setServiceVendor

Java
int setServiceVendor(ServiceVendor vendor);

设置所使用的 AI 服务商。

注意

该方法需要在成功调用 initialize,且收到 onEventResult(INITIALIZE, SUCCESS) 后调用。

参数

参数描述
vendor设置的服务商对象 ServiceVendor,包含 STTVendor、LLMVendor 和 TTSVendor。每种 Vendor 类型只支持设置一个服务商。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

  • 0:方法调用成功
  • 非 0:方法调用失败

start

Java
void start();

开启 AIGCService 服务。

该方法为异步操作。调用结果会在 onEventResult 回调中返回。

注意

该方法需要在成功调用 initialize,且收到 onEventResult(INITIALIZE, SUCCESS) 后调用。

stop

Java
void stop();

停止 AIGCService 服务。

该方法为异步操作。调用结果会在 onEventResult 回调中返回。

注意

该方法需要在成功调用 start,且收到 onEventResult(START, SUCCESS) 后调用。

pushSpeechDialogue

Java
int pushSpeechDialogue(byte[] data, Vad vad, boolean isLastFrame);

推送采集到的音频数据到 SDK。

注意

该方法需要在成功调用 start,且收到 onEventResult(START, SUCCESS) 后调用。

参数

参数描述
data待推送的音频数据。
vad本地是否有人声。详见 Vad。
isLastFrame

是否是最后一帧音频数据:

  • true:是
  • false:不是

该参数仅在 setSTTMode 设置为 CONTROLLED 时有效。

表格内容超出当前宽度,可横向滚动查看更多列。

返回值

  • 0:方法调用成功
  • 非 0:方法调用失败

pushTxtDialogue

Java
int pushTxtDialogue(String text, String roundId);

推送采集到的文本数据到 SDK 的 LLM 模块,用于 LLM 处理文本数据。

该方法和 pushMessagesToLLM 均可用于推送文本数据到 LLM 模块,区别为该方法仅支持推送单条消息,pushMessagesToLLM 支持推送多条消息(消息及其上下文语境)。

注意

  • 该方法需要在成功调用 start,且收到 onEventResult(START, SUCCESS) 后调用。
  • 建议文本数据的长度不超过 1 KB。对高于 1 KB 的数据我们不保证能正确处理。

参数

参数描述
text待推送的文本数据。
roundId

请求的 roundId,可为空。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。

  • 如果自行设置 roundId,为准确区分不同请求,请确保设置的 ID 全局唯一;
  • 如果 roundId 为空,SDK 内部会分配一个 roundId,并在每形成一个完整句子时更新为新的 roundId。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

  • 0:方法调用成功
  • 非 0:方法调用失败

pushMessagesToLLM

Java
int pushMessagesToLLM(String messagesJsonArray, String extraInfoJson, String roundId);

推送请求数据的 JSON 数组和其他字段信息到 LLM 模块,用于 LLM 处理相应请求数据。

该方法和 pushTxtDialogue 均可用于推送文本数据到 LLM 模块,区别为 pushTxtDialogue 仅支持推送单条消息,该方法支持推送多条消息(消息及其上下文语境)。

注意

  • 该方法需要在成功调用 start,且收到 onEventResult(START, SUCCESS) 后调用。
  • 建议 JSON 数据的长度不超过 1 KB。对高于 1 KB 的数据我们不保证能正确处理。

参数

参数描述
messagesJsonArray请求数据的 JSON 数组。
extraInfoJson其他特定字段信息的 JSON。
roundId

请求的 roundId,可为空。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。

  • 如果自行设置 roundId,为准确区分不同请求,请确保设置的 ID 全局唯一;
  • 如果 roundId 为空,SDK 内部会分配一个 roundId,并在每形成一个完整句子时更新为新的 roundId。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

  • 0:方法调用成功
  • 非 0:方法调用失败

pushTxttoTTS

Java
int pushTxttoTTS(String text, String roundId);

推送采集到的文本数据到 SDK 的 TTS 模块,用于 TTS 播报文本。

注意

  • 该方法需要在成功调用 start,且收到 onEventResult(START, SUCCESS) 后调用。
  • 建议文本数据的长度不超过 1 KB。对高于 1 KB 的数据我们不保证能正确处理。

参数

参数描述
text待推送的文本数据。
roundId

请求的 roundId,可为空。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。

  • 如果自行设置 roundId,为准确区分不同请求,请确保设置的 ID 全局唯一;
  • 如果 roundId 为空,SDK 内部会分配一个 roundId,并在每形成一个完整句子时更新为新的 roundId。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

  • 0:方法调用成功
  • 非 0:方法调用失败

interrupt

Java
int interrupt(int mask);

中断指定服务。

注意

该方法需要在成功调用 start,且收到 onEventResult(START, SUCCESS) 后调用。

参数

参数描述
mask服务类型的掩码值。详见 Constants。服务类型支持使用按位或运算符(|)进行组合,例:mask = Contstants.SERVICE_STT | Constants.SERVICE_LLM 代表同时中断 STT 和 LLM 服务。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

  • 0:方法调用成功
  • 非 0:方法调用失败

setSTTMode

Java
int setSTTMode(STTMode mode);

设置 STT 服务的模式。

注意

该方法需要在成功调用 start,且收到 onEventResult(START, SUCCESS) 后调用。

参数

参数描述
modeSTT 服务模式。详见 STTMode。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

  • 0:方法调用成功
  • 非 0:方法调用失败

setPrompt

Java
int setPrompt(String prompt);

设置大语言模型的 Prompt 信息。

注意

该方法需要在成功 init,且收到 onEventResult(INIT, SUCCESS) 后,且 start 前调用。

参数

参数描述
promptPrompt 信息。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

  • 0:方法调用成功
  • 非 0:方法调用失败

getVersion

Java
String getVersion();

获取 AIGCService SDK 的版本号。

返回值

当前 SDK 的版本号。

destroy

Java
void destroy();

销毁 AIGCService 实例。

该方法为异步操作。调用结果会在 onEventResult 回调中返回。

AIGCServiceCallback

onEventResult

Java
void onEventResult(@NonNull ServiceEvent event, @NonNull ServiceCode code, @Nullable String msg);

AIGCService 实例事件回调。

该回调在 SDK 调用 initialize、start、stop、destroy 后触发,报告对应方法的调用结果。

参数

参数描述
event该服务事件的类型,详见 ServiceEvent。
code该服务事件的结果,详见 ServiceCode。
msg事件信息。该字串可能为空。
表格内容超出当前宽度,可横向滚动查看更多列。

onSpeech2TextResult

Java
HandleResult onSpeech2TextResult(String roundId, Data<String> result, boolean isRecognizedSpeech, ServiceCode code)

回调语音转文字 (STT) 处理后的结果。

参数

参数描述
roundId

请求的 roundId。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。

  • 如果你在推送时设置了 roundId,回调中沿用你设置的 roundId;
  • 如果推送时 roundId 为空,SDK 内部会分配一个 roundId,并在每形成一个完整句子时更新为新的 roundId。
result语音识别出来的文字(UTF-8 字符集)。 该参数为读写模式。在 isRecognizedSpeech 为 true 时,如果 result 参数被修改,后续流程会用更新后的 result 当作后续流程的输入。
isRecognizedSpeech

该回调返回的 result 是否是一个完整的句子:

  • true:是
  • false:不是
codeSTT 语音识别结果。详见 ServiceCode。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

HandleResult,该回调的处理结果类型。你需要设置该返回值:

  • CONTINUE(0):SDK 会继续处理后续流程
  • DISCARD(1):SDK 会中断处理后续流程

注意

该规则仅在 isRecognizedSpeech 返回 true 下有效。

onLLMResult

Java
HandleResult onLLMResult(String roundId, Data<String> answer, boolean isRoundEnd, int estimatedResponseTokens, ServiceCode code)

回调大语言模型 (LLM) 处理后的结果。

参数

参数描述
roundId

请求的 roundId。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。

  • 如果你在推送时设置了 roundId,回调中沿用你设置的 roundId;
  • 如果推送时 roundId 为空,SDK 内部会分配一个 roundId,并在每形成一个完整句子时更新为新的 roundId。
answer大语言模型处理后的结果(UTF-8 字符集)。该参数为读写模式。如果 answer 参数被修改,后续流程会用更新后的 answer 当作后续流程的输入。
isRoundEnd

本轮大语言模型返回结果是否结束:

  • true:是。
  • false:否。
estimatedResponseTokens本轮 LLM 大模型处理返回内容大约消耗的 Token 数。该数值只是估算值,不作为计费标准,你可以用该值监测并限制 Token 的消耗。如果返回的 token 为 0,可忽略该值。
codeLLM 大模型处理结果。详见 ServiceCode。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

HandleResult,该回调的处理结果类型。你需要设置该返回值:

  • CONTINUE(0):SDK 会继续处理后续流程
  • DISCARD(1):SDK 会中断处理后续流程

onText2SpeechResult

Java
HandleResult onText2SpeechResult(String roundId, Data<byte[]> voice, int sampleRates, int channels, int bits, ServiceCode code)

回调文字转语音 (TTS) 处理后的结果。

参数

参数描述
roundId

请求的 roundId。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。

  • 如果你在推送时设置了 roundId,回调中沿用你设置的 roundId;
  • 如果推送时 roundId 为空,SDK 内部会分配一个 roundId,并在每形成一个完整句子时更新为新的 roundId。
voice文字转语音处理后的语音数据。该参数为读写模式。如果 voice 参数被修改,后续流程会用更新后的 voice 参数值作为输入。
sampleRates语音数据 (PCM) 的采样率,单位为 Hz。
channels语音数据 (PCM) 的通道数。
bits语音数据 (PCM) 的位数。
codeTTS 文本转语音处理结果。详见 ServiceCode。
表格内容超出当前宽度,可横向滚动查看更多列。

返回值

HandleResult,该回调的处理结果类型。你需要设置该返回值:

  • CONTINUE(0):SDK 会继续处理后续流程
  • DISCARD(1):SDK 会中断处理后续流程

信息

该回调是目前最后一个业务流程,返回值 CONTINUE 和 DISCARD 效果一样,均不会影响后续业务。后续版本中我们可能会在该回调后添加其他业务。

onSpeechStateChange

Java
void onSpeechStateChange(SpeechState state);

识别语音开始和结束的状态。

参数

参数描述
state语音的状态,详见 SpeechState。
表格内容超出当前宽度,可横向滚动查看更多列。

类型定义

AIGCServiceConfig

Java
pubic class AIGCServiceConfig {
    public Context context;
    public String appId;
    public String rtmToken;
    public int userId;
    public AIGCServiceCallback callback;
    public String userName;
    public boolean enableMultiTurnShortTermMemory;
    public int speechRecognitionFiltersLength;
    public boolean enableLog;
    public boolean enableSaveLogToFile;
    public SceneMode input;
    public SceneMode output;
    public boolean enableChatIdleTip;
    public String logFilePath;
    public NoiseEnvironment noiseEnvironment;
    public SpeechRecognitionCompletenessLevel speechRecognitionCompletenessLevel;
}

AIGCService 的初始化配置。

参数描述
contextAndroid 平台的 Context。
appId声网项目的 App ID。
rtmToken声网项目的 RTM Token。
userId用户 ID。
callback服务回调。详见 AIGCServiceCallback。
userName用户名。
enableMultiTurnShortTermMemory

是否开启多轮短时记忆:

  • true:是。开启后,后续流程的处理会结合上下文语境。
  • false:否。

注意

该参数配置在调用 pushMessagesToLLM 时无效。

speechRecognitionFiltersLength过滤语音识别结果的字数长度。
enableLog

是否开启日志输出到 IDE 的控制台:

  • true:是。
  • false:否。
enableSaveLogToFile

是否保存日志到文件系统:

  • true:是。
  • false:否。

注意

该参数的设置只有在 enableLog 为 true 时才生效。

input输入参数,详见 SceneMode。
output输出参数,详见 SceneMode。
enableChatIdleTip

是否开启闲时聊天提示信息:

  • true:是。
  • false:(默认)否。
logFilePath设置日志的存储路径。如果不设或设为空字串,SDK 会使用默认的存储路径。
noiseEnvironment设置噪音环境级别,详见 NoiseEnvironment。SDK 会根据你的设置等级,相应地处理环境噪音对语音数据的影响。
speechRecognitionCompletenessLevel设置语音识别句子完整度级别,详见 SpeechRecognitionCompletenessLevel。
表格内容超出当前宽度,可横向滚动查看更多列。

AIRole

Java
public class AIRole implements Serializable {
    protected String roleId;
    protected String roleName;
    protected String gender;
    protected String profession;
    protected String description;
}

AI 服务的属性。

参数描述
roleIdAI 服务的 ID,是 AI 服务的唯一标识。
roleNameAI 服务的名称。
genderAI 服务的性别:"male" 表示男性,"female" 表示女性。
professionAI 服务的职业。
descriptionAI 服务的简单介绍。
表格内容超出当前宽度,可横向滚动查看更多列。

Constants

常量值。

参数名参数值描述
SERVICE_STT0b0001STT 服务类型值。
SERVICE_LLM0b0010LLM 服务类型值。
SERVICE_TTS0b0100TTS 服务类型值。
表格内容超出当前宽度,可横向滚动查看更多列。

SceneMode

Java
public class SceneMode {
    public Language language;
    public int speechFrameBits;
    public int speechFrameSampleRates;
    public int speechFrameChannels;
}

AIGCServiceConfig 中 input 和 output 参数的详细配置项。

参数描述
language语言类型。详见 Language。
speechFrameSampleRates语音数据 (PCM) 的采样率。SDK 仅支持 16000。
speechFrameChannels语音数据 (PCM) 的通道数。SDK 仅支持 1。
speechFrameBits语音数据 (PCM) 的位数。SDK 仅支持 16。
表格内容超出当前宽度,可横向滚动查看更多列。

STTVendor

Java
public class STTVendor extends BaseVendor {
    private String id;
    private String vendorName;
}

public class BaseVendor {
    protected String accountInJson;
}

语音转文字的供应商信息。

参数描述
id语音转文字供应商的 ID。
vendorName供应商名称。
accountInJson供应商自有的账号信息。若使用该字段,联系 sales@shengwang.cn 了解字段的 JSON 格式。
表格内容超出当前宽度,可横向滚动查看更多列。

LLMVendor

Java
public class LLMVendor extends BaseVendor {
    private String id;
    private String vendorName;
    private String model;
}

public class BaseVendor {
    protected String accountInJson;
}

大语言模型的供应商信息。

参数描述
id大语言模型供应商的 ID。
vendorName供应商名称。
model模型参数。
accountInJson供应商自有的账号信息。若使用该字段,联系 sales@shengwang.cn 了解字段的 JSON 格式。
表格内容超出当前宽度,可横向滚动查看更多列。

TTSVendor

Java
public class TTSVendor extends BaseVendor {
    private String id;

    private String vendorName;

    private String language;
    private String voiceName;
    private String voiceNameValue;
    private String voiceNameStyle;
}

public class BaseVendor {
    protected String accountInJson;
}

文字转语音的供应商信息。

参数描述
id文字转语音供应商的 ID。
vendorName供应商名称。
language所支持的语言。如果为空,则表示支持所有语言。
voiceName发言人名称,仅用于标签上展示的名称。
voiceNameValue发言人名称参数值。
voiceNameStyle(可选)发言人风格参数值。
accountInJson供应商自有的账号信息。若使用该字段,联系 sales@shengwang.cn 了解字段的 JSON 格式。
表格内容超出当前宽度,可横向滚动查看更多列。

ServiceEvent

服务事件类型。

枚举名枚举值描述
IDLE0初始状态。
INITIALIZE1初始化状态,对应调用 initialize 方法。
START2启动状态,对应调用 start 方法。
STOP3停止服务状态,对应调用 stop 方法。
DESTROY4销毁服务状态,对应调用 destroy 方法。
表格内容超出当前宽度,可横向滚动查看更多列。

ServiceCode

服务事件结果。

枚举名枚举值描述
ERROR_GENERAL-1通用错误。
SUCCESS0成功。
INITALIZE_FAIL1初始化失败。
START_FAIL2启动失败。
ERROR_LLM_LENGTH_LIMIT3大模型返回长度超出限制。
ERROR_LLM_EXCEEDS_MAX_CAPACITY4输入或输出内容超出模型最大容量限制。
ERROR_LICENSE_EXPIRE5License 过期。
ERROR_INVALID_API_KEY6无效的 API Key。
ERROR_INVALID_PARAMETER7无效参数。
ERROR_INVALID_STATE8无效状态。
ERROR_TIMEOUT9服务超时。
ERROR_CONTENT_MANAGEMENT_POLICY10LLM 判定请求内容不合规,触发内容审核。
表格内容超出当前宽度,可横向滚动查看更多列。

Vad

本地是否有人声。

枚举名枚举值描述
UNKNOWN-1不确定。
MUTE0本地无人声。
NON_MUTE1本地有人声。
表格内容超出当前宽度,可横向滚动查看更多列。

Language

语言类型。

枚举名枚举值描述
ZH_CNzh-CN中文。
EN_USen-US英文。
JA_JPja-JP日文。
FR_FRfr-FR法语。
DE_DEde-DE德语。
ES_ESes-ES西班牙语。
PT_BRpt-BR葡萄牙语(巴西)。
PT_PTpt-PT葡萄牙语(葡萄牙)。
TR_TRtr-TR土耳其语。
AR_EGar-EG阿拉伯语(埃及)。
AR_SAar-SA阿拉伯语(沙特阿拉伯)。
表格内容超出当前宽度,可横向滚动查看更多列。

NoiseEnvironment

噪音环境级别。

枚举名枚举值描述
QUIET0周围环境噪音很少,比较安静。
NORMAL1周围环境噪音正常。
NOISE2周围环境噪音很强。
表格内容超出当前宽度,可横向滚动查看更多列。

SpeechRecognitionCompletenessLevel

语音识别句子的完整性级别。级别越高,则识别句子的完整性越好;相应地,语音识别的整体时间也会越长。

枚举名枚举值描述
LOW0低级别。
NORMAL1正常级别。
HIGH2高级别。
表格内容超出当前宽度,可横向滚动查看更多列。

STTMode

STT 服务模式类型。

枚举名枚举值描述
FREESTYLE0(默认)自由模式,适用于实时对话、实时语音识别。
CONTROLLED1受控模式,适用于单段语音输入。
表格内容超出当前宽度,可横向滚动查看更多列。

SpeechState

语音的状态。

枚举名枚举值描述
START0语音开始。
END1语音结束。
表格内容超出当前宽度,可横向滚动查看更多列。

这个页面有帮助吗?