# AIGCService API 参考 (/zh-CN/api-reference/conversational-ai/aigc/aigcservice) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" /> AIGCService SDK 主要包含以下两大类: - [`AIGCService`](#aigcservice) 类:提供 AIGC 服务的核心类,包含实现 AIGC 场景各功能的核心方法。 - [`AIGCServiceCallback`](#aigcservicecallback) 类:`AIGCService` 异步方法的事件回调类。 本文提供 AIGCService SDK 的 API 参考。 ## AIGCService [#aigcservice] ### create [#create] ```java AIGCService create(); ``` 创建 `AIGCService` 实例。 #### 返回值 [#返回值] 成功创建后,该方法会返回一个 `AIGCService` 实例。 ### initialize [#initialize] ```java void initialize(AIGCServiceConfig config); ``` 初始化 `AIGCService`。 该方法为异步操作。调用结果会在 [`onEventResult`](#oneventresult) 回调中返回。 #### 参数 [#参数] | 参数 | 描述 | | --- | --- | | config | `AIGCService` 初始化参数。详见 [`AIGCServiceConfig`](#aigcserviceconfig)。| ### getRoles [#getroles] ```java AIRole[] getRoles(); ``` 获取 SDK 支持的所有的 `AIRole` 数组。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResult(INITIALIZE, SUCCESS)` 后调用。 ::: #### 返回值 [#返回值-1] SDK 支持的 [`AIRole`](#airole) 数组。 ### setRole [#setrole] ```java void setRole(String roleId); ``` 设置 SDK 使用的 `AIRole`。该方法设置即时生效。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResult(INITIALIZE, SUCCESS)` 后调用。 ::: #### 参数 [#参数-1] | 参数 | 描述 | | --- | --- | | `roleId` | 标明 `AIRole` 的 ID。 | ### getCurrentRole [#getcurrentrole] ```java AIRole getCurrentRole() ``` 获取当前使用的 `AIRole`。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResult(INITIALIZE, SUCCESS)` 后调用。 ::: #### 返回值 [#返回值-2] 当前使用的 `AIRole`。 ### getServiceVendors [#getservicevendors] ```java ServiceVendorGroup getServiceVendors(); ``` 获取所有 AI 服务商的信息。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResult(INITIALIZE, SUCCESS)` 后调用。 ::: #### 返回值 [#返回值-3] 包含了所有 AI 服务商信息的 `ServiceVendorGroup` 对象,由多个 [`STTVendor`](#sttvendor)、[`LLMVendor`](#llmvendor) 和 [`TTSVendor`](#ttsvendor) 组成。 ### setServiceVendor [#setservicevendor] ```java int setServiceVendor(ServiceVendor vendor); ``` 设置所使用的 AI 服务商。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResult(INITIALIZE, SUCCESS)` 后调用。 ::: #### 参数 [#参数-2] | 参数 | 描述 | | --- | --- | | `vendor` | 设置的服务商对象 `ServiceVendor`,包含 [`STTVendor`](#sttvendor)、[`LLMVendor`](#llmvendor) 和 [`TTSVendor`](#ttsvendor)。每种 Vendor 类型只支持设置一个服务商。| #### 返回值 [#返回值-4] - 0:方法调用成功 - 非 0:方法调用失败 ### start [#start] ```java void start(); ``` 开启 AIGCService 服务。 该方法为异步操作。调用结果会在 [`onEventResult`](#oneventresult) 回调中返回。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResult(INITIALIZE, SUCCESS)` 后调用。 ::: ### stop [#stop] ```java void stop(); ``` 停止 AIGCService 服务。 该方法为异步操作。调用结果会在 [`onEventResult`](#oneventresult) 回调中返回。 :::warning[注意] 该方法需要在成功调用 `start`,且收到 `onEventResult(START, SUCCESS)` 后调用。 ::: ### pushSpeechDialogue [#pushspeechdialogue] ```java int pushSpeechDialogue(byte[] data, Vad vad, boolean isLastFrame); ``` 推送采集到的音频数据到 SDK。 :::warning[注意] 该方法需要在成功调用 `start`,且收到 `onEventResult(START, SUCCESS)` 后调用。 ::: #### 参数 [#参数-3] | 参数 | 描述 | | --- | --- | | `data` | 待推送的音频数据。 | | `vad` | 本地是否有人声。详见 [`Vad`](#vad)。 | | `isLastFrame` | [aigcservice-android-html-0-3-1 details](#table-slot-aigcservice-android-html-0-3-1) | **aigcservice-android-html-0-3-1 details** 是否是最后一帧音频数据: - `true`:是 - `false`:不是 该参数仅在 [`setSTTMode`](#setsttmode) 设置为 `CONTROLLED` 时有效。 #### 返回值 [#返回值-5] - 0:方法调用成功 - 非 0:方法调用失败 ### pushTxtDialogue [#pushtxtdialogue] ```java int pushTxtDialogue(String text, String roundId); ``` 推送采集到的文本数据到 SDK 的 LLM 模块,用于 LLM 处理文本数据。 该方法和 `pushMessagesToLLM` 均可用于推送文本数据到 LLM 模块,区别为该方法仅支持推送单条消息,`pushMessagesToLLM` 支持推送多条消息(消息及其上下文语境)。 :::warning[注意] - 该方法需要在成功调用 `start`,且收到 `onEventResult(START, SUCCESS)` 后调用。 - 建议文本数据的长度不超过 1 KB。对高于 1 KB 的数据我们不保证能正确处理。 ::: #### 参数 [#参数-4] | 参数 | 描述 | | --- | --- | | `text` | 待推送的文本数据。 | | `roundId` | [aigcservice-android-html-1-2-1 details](#table-slot-aigcservice-android-html-1-2-1) | **aigcservice-android-html-1-2-1 details** 请求的 `roundId`,可为空。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果自行设置 `roundId`,为准确区分不同请求,请确保设置的 ID 全局唯一; - 如果 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 #### 返回值 [#返回值-6] - 0:方法调用成功 - 非 0:方法调用失败 ### pushMessagesToLLM [#pushmessagestollm] ```java int pushMessagesToLLM(String messagesJsonArray, String extraInfoJson, String roundId); ``` 推送请求数据的 JSON 数组和其他字段信息到 LLM 模块,用于 LLM 处理相应请求数据。 该方法和 `pushTxtDialogue` 均可用于推送文本数据到 LLM 模块,区别为 `pushTxtDialogue` 仅支持推送单条消息,该方法支持推送多条消息(消息及其上下文语境)。 :::warning[注意] - 该方法需要在成功调用 `start`,且收到 `onEventResult(START, SUCCESS)` 后调用。 - 建议 JSON 数据的长度不超过 1 KB。对高于 1 KB 的数据我们不保证能正确处理。 ::: #### 参数 [#参数-5] | 参数 | 描述 | | --- | --- | | `messagesJsonArray` | 请求数据的 JSON 数组。 | | `extraInfoJson` | 其他特定字段信息的 JSON。 | | `roundId` | [aigcservice-android-html-2-3-1 details](#table-slot-aigcservice-android-html-2-3-1) | **aigcservice-android-html-2-3-1 details** 请求的 `roundId`,可为空。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果自行设置 `roundId`,为准确区分不同请求,请确保设置的 ID 全局唯一; - 如果 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 #### 返回值 [#返回值-7] - 0:方法调用成功 - 非 0:方法调用失败 ### pushTxttoTTS [#pushtxttotts] ```java int pushTxttoTTS(String text, String roundId); ``` 推送采集到的文本数据到 SDK 的 TTS 模块,用于 TTS 播报文本。 :::warning[注意] - 该方法需要在成功调用 `start`,且收到 `onEventResult(START, SUCCESS)` 后调用。 - 建议文本数据的长度不超过 1 KB。对高于 1 KB 的数据我们不保证能正确处理。 ::: #### 参数 [#参数-6] | 参数 | 描述 | | --- | --- | | `text` | 待推送的文本数据。 | | `roundId` | [aigcservice-android-html-3-2-1 details](#table-slot-aigcservice-android-html-3-2-1) | **aigcservice-android-html-3-2-1 details** 请求的 `roundId`,可为空。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果自行设置 `roundId`,为准确区分不同请求,请确保设置的 ID 全局唯一; - 如果 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 #### 返回值 [#返回值-8] - 0:方法调用成功 - 非 0:方法调用失败 ### interrupt [#interrupt] ```java int interrupt(int mask); ``` 中断指定服务。 :::warning[注意] 该方法需要在成功调用 `start`,且收到 `onEventResult(START, SUCCESS)` 后调用。 ::: #### 参数 [#参数-7] | 参数 | 描述 | | --- | --- | | `mask` | 服务类型的掩码值。详见 [`Constants`](#constants)。服务类型支持使用按位或运算符(\|)进行组合,例:`mask = Contstants.SERVICE_STT \| Constants.SERVICE_LLM` 代表同时中断 STT 和 LLM 服务。 | #### 返回值 [#返回值-9] - 0:方法调用成功 - 非 0:方法调用失败 ### setSTTMode [#setsttmode] ```java int setSTTMode(STTMode mode); ``` 设置 STT 服务的模式。 :::warning[注意] 该方法需要在成功调用 `start`,且收到 `onEventResult(START, SUCCESS)` 后调用。 ::: #### 参数 [#参数-8] | 参数 | 描述 | | --- | --- | | `mode` | STT 服务模式。详见 [`STTMode`](#sttmode)。 | #### 返回值 [#返回值-10] - 0:方法调用成功 - 非 0:方法调用失败 ### setPrompt [#setprompt] ```java int setPrompt(String prompt); ``` 设置大语言模型的 Prompt 信息。 :::warning[注意] 该方法需要在成功 `init`,且收到 `onEventResult(INIT, SUCCESS)` 后,且 `start` 前调用。 ::: #### 参数 [#参数-9] | 参数 | 描述 | | --- | --- | | `prompt` | Prompt 信息。| #### 返回值 [#返回值-11] - 0:方法调用成功 - 非 0:方法调用失败 ### getVersion [#getversion] ```java String getVersion(); ``` 获取 AIGCService SDK 的版本号。 #### 返回值 [#返回值-12] 当前 SDK 的版本号。 ### destroy [#destroy] ```java void destroy(); ``` 销毁 `AIGCService` 实例。 该方法为异步操作。调用结果会在 [`onEventResult`](#oneventresult) 回调中返回。 ## AIGCServiceCallback [#aigcservicecallback] ### onEventResult [#oneventresult] ```java void onEventResult(@NonNull ServiceEvent event, @NonNull ServiceCode code, @Nullable String msg); ``` AIGCService 实例事件回调。 该回调在 SDK 调用 `initialize`、`start`、`stop`、`destroy` 后触发,报告对应方法的调用结果。 #### 参数 [#参数-10] | 参数 | 描述 | | --- | --- | | `event` | 该服务事件的类型,详见 [`ServiceEvent`](#serviceevent)。| | `code` | 该服务事件的结果,详见 [`ServiceCode`](#servicecode)。| | `msg` | 事件信息。该字串可能为空。| ### onSpeech2TextResult [#onspeech2textresult] ```java HandleResult onSpeech2TextResult(String roundId, Data result, boolean isRecognizedSpeech, ServiceCode code) ``` 回调语音转文字 (STT) 处理后的结果。 #### 参数 [#参数-11] | 参数 | 描述 | | --- | --- | | `roundId` | [aigcservice-android-html-6-1-1 details](#table-slot-aigcservice-android-html-6-1-1) | | `result` | 语音识别出来的文字(UTF-8 字符集)。 该参数为读写模式。在 `isRecognizedSpeech` 为 `true` 时,如果 `result` 参数被修改,后续流程会用更新后的 `result` 当作后续流程的输入。 | | `isRecognizedSpeech` | [aigcservice-android-html-6-3-1 details](#table-slot-aigcservice-android-html-6-3-1) | | `code` | STT 语音识别结果。详见 [`ServiceCode`](#servicecode)。 | **aigcservice-android-html-6-1-1 details** 请求的 `roundId`。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果你在推送时设置了 `roundId`,回调中沿用你设置的 `roundId`; - 如果推送时 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 **aigcservice-android-html-6-3-1 details** 该回调返回的 `result` 是否是一个完整的句子: - `true`:是 - `false`:不是 #### 返回值 [#返回值-13] `HandleResult`,该回调的处理结果类型。你需要设置该返回值: - `CONTINUE(0)`:SDK 会继续处理后续流程 - `DISCARD(1)`:SDK 会中断处理后续流程 :::warning[注意] 该规则仅在 `isRecognizedSpeech` 返回 `true` 下有效。 ::: ### onLLMResult [#onllmresult] ```java HandleResult onLLMResult(String roundId, Data answer, boolean isRoundEnd, int estimatedResponseTokens, ServiceCode code) ``` 回调大语言模型 (LLM) 处理后的结果。 #### 参数 [#参数-12] | 参数 | 描述 | | --- | --- | | `roundId` | [aigcservice-android-html-7-1-1 details](#table-slot-aigcservice-android-html-7-1-1) | | `answer` | 大语言模型处理后的结果(UTF-8 字符集)。该参数为读写模式。如果 `answer` 参数被修改,后续流程会用更新后的 `answer` 当作后续流程的输入。 | | `isRoundEnd` | [aigcservice-android-html-7-3-1 details](#table-slot-aigcservice-android-html-7-3-1) | | `estimatedResponseTokens` | 本轮 LLM 大模型处理返回内容大约消耗的 Token 数。该数值只是估算值,不作为计费标准,你可以用该值监测并限制 Token 的消耗。如果返回的 `token` 为 `0`,可忽略该值。 | | `code` | LLM 大模型处理结果。详见 [`ServiceCode`](#servicecode)。 | **aigcservice-android-html-7-1-1 details** 请求的 `roundId`。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果你在推送时设置了 `roundId`,回调中沿用你设置的 `roundId`; - 如果推送时 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 **aigcservice-android-html-7-3-1 details** 本轮大语言模型返回结果是否结束: - `true`:是。 - `false`:否。 #### 返回值 [#返回值-14] `HandleResult`,该回调的处理结果类型。你需要设置该返回值: - `CONTINUE(0)`:SDK 会继续处理后续流程 - `DISCARD(1)`:SDK 会中断处理后续流程 ### onText2SpeechResult [#ontext2speechresult] ```java HandleResult onText2SpeechResult(String roundId, Data voice, int sampleRates, int channels, int bits, ServiceCode code) ``` 回调文字转语音 (TTS) 处理后的结果。 #### 参数 [#参数-13] | 参数 | 描述 | | --- | --- | | `roundId` | [aigcservice-android-html-8-1-1 details](#table-slot-aigcservice-android-html-8-1-1) | | `voice` | 文字转语音处理后的语音数据。该参数为读写模式。如果 `voice` 参数被修改,后续流程会用更新后的 `voice` 参数值作为输入。 | | `sampleRates` | 语音数据 (PCM) 的采样率,单位为 Hz。 | | `channels` | 语音数据 (PCM) 的通道数。 | | `bits` | 语音数据 (PCM) 的位数。 | | `code` | TTS 文本转语音处理结果。详见 [`ServiceCode`](#servicecode)。 | **aigcservice-android-html-8-1-1 details** 请求的 `roundId`。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果你在推送时设置了 `roundId`,回调中沿用你设置的 `roundId`; - 如果推送时 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 #### 返回值 [#返回值-15] `HandleResult`,该回调的处理结果类型。你需要设置该返回值: - `CONTINUE(0)`:SDK 会继续处理后续流程 - `DISCARD(1)`:SDK 会中断处理后续流程 :::info[信息] 该回调是目前最后一个业务流程,返回值 `CONTINUE` 和 `DISCARD` 效果一样,均不会影响后续业务。后续版本中我们可能会在该回调后添加其他业务。 ::: ### onSpeechStateChange [#onspeechstatechange] ```java void onSpeechStateChange(SpeechState state); ``` 识别语音开始和结束的状态。 #### 参数 [#参数-14] | 参数 | 描述 | | --- | --- | | `state` | 语音的状态,详见 [`SpeechState`](#speechstate)。 | ## 类型定义 [#类型定义] ### AIGCServiceConfig [#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` 的初始化配置。 | 参数 | 描述 | | --- | --- | | `context` | Android 平台的 Context。 | | `appId` | 声网项目的 App ID。 | | `rtmToken` | 声网项目的 [RTM Token](/zh-CN/realtime-media/rtm/build/authentication-and-connection/user-authentication)。 | | `userId` | 用户 ID。 | | `callback` | 服务回调。详见 [`AIGCServiceCallback`](#aigcservicecallback)。 | | `userName` | 用户名。 | | `enableMultiTurnShortTermMemory` | [aigcservice-android-html-10-7-1 details](#table-slot-aigcservice-android-html-10-7-1) | | `speechRecognitionFiltersLength` | 过滤语音识别结果的字数长度。 | | `enableLog` | [aigcservice-android-html-10-9-1 details](#table-slot-aigcservice-android-html-10-9-1) | | `enableSaveLogToFile` | [aigcservice-android-html-10-10-1 details](#table-slot-aigcservice-android-html-10-10-1) | | `input` | 输入参数,详见 [`SceneMode`](#scenemode)。 | | `output` | 输出参数,详见 [`SceneMode`](#scenemode)。 | | `enableChatIdleTip` | [aigcservice-android-html-10-13-1 details](#table-slot-aigcservice-android-html-10-13-1) | | `logFilePath` | 设置日志的存储路径。如果不设或设为空字串,SDK 会使用默认的存储路径。 | | `noiseEnvironment` | 设置噪音环境级别,详见 [`NoiseEnvironment`](#noiseenvironment)。SDK 会根据你的设置等级,相应地处理环境噪音对语音数据的影响。 | | `speechRecognitionCompletenessLevel` | 设置语音识别句子完整度级别,详见 [`SpeechRecognitionCompletenessLevel`](#speechrecognitioncompletenesslevel)。 | **aigcservice-android-html-10-7-1 details** 是否开启多轮短时记忆: - `true`:是。开启后,后续流程的处理会结合上下文语境。 - `false`:否。 :::warning[注意] 该参数配置在调用 `pushMessagesToLLM` 时无效。 ::: **aigcservice-android-html-10-9-1 details** 是否开启日志输出到 IDE 的控制台: - `true`:是。 - `false`:否。 **aigcservice-android-html-10-10-1 details** 是否保存日志到文件系统: - `true`:是。 - `false`:否。 :::warning[注意] 该参数的设置只有在 `enableLog` 为 `true` 时才生效。 ::: **aigcservice-android-html-10-13-1 details** 是否开启闲时聊天提示信息: - `true`:是。 - `false`:(默认)否。 ### AIRole [#airole] ```java public class AIRole implements Serializable { protected String roleId; protected String roleName; protected String gender; protected String profession; protected String description; } ``` AI 服务的属性。 | 参数 | 描述 | | --- | --- | | `roleId` | AI 服务的 ID,是 AI 服务的唯一标识。| | `roleName` | AI 服务的名称。| | `gender` | AI 服务的性别:`"male"` 表示男性,`"female"` 表示女性。| | `profession` | AI 服务的职业。 | | `description` | AI 服务的简单介绍。| ### Constants [#constants] 常量值。 | 参数名 | 参数值 | 描述 | | --- | --- | --- | | `SERVICE_STT` | `0b0001` | STT 服务类型值。| | `SERVICE_LLM` | `0b0010` | LLM 服务类型值。| | `SERVICE_TTS` | `0b0100` | TTS 服务类型值。| ### SceneMode [#scenemode] ```java public class SceneMode { public Language language; public int speechFrameBits; public int speechFrameSampleRates; public int speechFrameChannels; } ``` `AIGCServiceConfig` 中 `input` 和 `output` 参数的详细配置项。 | 参数 | 描述 | | --- | --- | | `language` | 语言类型。详见 [`Language`](#language)。 | | `speechFrameSampleRates` | 语音数据 (PCM) 的采样率。SDK 仅支持 16000。 | | `speechFrameChannels` | 语音数据 (PCM) 的通道数。SDK 仅支持 1。 | | `speechFrameBits` | 语音数据 (PCM) 的位数。SDK 仅支持 16。 | ### STTVendor [#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 [#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 [#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 [#serviceevent] 服务事件类型。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `IDLE` | `0` | 初始状态。 | | `INITIALIZE` | `1` | 初始化状态,对应调用 `initialize` 方法。 | | `START` | `2` | 启动状态,对应调用 `start` 方法。| | `STOP` | `3` | 停止服务状态,对应调用 `stop` 方法。 | | `DESTROY` | `4` | 销毁服务状态,对应调用 `destroy` 方法。| ### ServiceCode [#servicecode] 服务事件结果。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `ERROR_GENERAL` | `-1` | 通用错误。| | `SUCCESS` | `0` | 成功。| | `INITALIZE_FAIL` | `1` | 初始化失败。| | `START_FAIL` | `2` | 启动失败。| | `ERROR_LLM_LENGTH_LIMIT` | `3` | 大模型返回长度超出限制。| | `ERROR_LLM_EXCEEDS_MAX_CAPACITY` | `4` | 输入或输出内容超出模型最大容量限制。| | `ERROR_LICENSE_EXPIRE` | `5` | License 过期。 | | `ERROR_INVALID_API_KEY` | `6` | 无效的 API Key。 | | `ERROR_INVALID_PARAMETER` | `7` | 无效参数。| | `ERROR_INVALID_STATE` | `8` | 无效状态。| | `ERROR_TIMEOUT` | `9` | 服务超时。| | `ERROR_CONTENT_MANAGEMENT_POLICY` | `10` | LLM 判定请求内容不合规,触发内容审核。 | ### Vad [#vad] 本地是否有人声。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `UNKNOWN` | `-1` | 不确定。| | `MUTE` | `0`| 本地无人声。| | `NON_MUTE` | `1` | 本地有人声。 | ### Language [#language] 语言类型。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `ZH_CN` | `zh-CN` | 中文。 | | `EN_US` | `en-US` | 英文。 | | `JA_JP` | `ja-JP` | 日文。 | | `FR_FR` | `fr-FR` | 法语。| | `DE_DE` | `de-DE` | 德语。 | | `ES_ES` | `es-ES` | 西班牙语。 | | `PT_BR` | `pt-BR` | 葡萄牙语(巴西)。 | | `PT_PT` | `pt-PT` | 葡萄牙语(葡萄牙)。 | | `TR_TR` | `tr-TR` | 土耳其语。 | | `AR_EG` | `ar-EG` | 阿拉伯语(埃及)。 | | `AR_SA` | `ar-SA` | 阿拉伯语(沙特阿拉伯)。 | ### NoiseEnvironment [#noiseenvironment] 噪音环境级别。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `QUIET` | `0` | 周围环境噪音很少,比较安静。| | `NORMAL` | `1` | 周围环境噪音正常。| | `NOISE` | `2` | 周围环境噪音很强。| ### SpeechRecognitionCompletenessLevel [#speechrecognitioncompletenesslevel] 语音识别句子的完整性级别。级别越高,则识别句子的完整性越好;相应地,语音识别的整体时间也会越长。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `LOW` | `0` | 低级别。| | `NORMAL` | `1` | 正常级别。| | `HIGH` | `2` | 高级别。| ### STTMode [#sttmode] STT 服务模式类型。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `FREESTYLE` | `0` | (默认)自由模式,适用于实时对话、实时语音识别。| | `CONTROLLED` | `1` | 受控模式,适用于单段语音输入。| ### SpeechState [#speechstate] 语音的状态。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `START` | `0` | 语音开始。| | `END` | `1` | 语音结束。| <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" /> AgoraAIGCService SDK 主要包含以下两大类: - [`AgoraAIGCService`](#aigcservice) 类:提供 AIGC 服务的核心类,包含实现 AIGC 场景各功能的核心方法。 - [`AgoraAIGCServiceDelegate`](#aigcservicecallback) 类:`AgoraAIGCService` 异步方法的事件回调类。 本文提供 AgoraAIGCService SDK 的 API 参考。 ## AgoraAIGCService [#agoraaigcservice] ### create [#create-1] ```objc + (instancetype)create; ``` 创建 `AgoraAIGCService` 实例。 #### 返回值 [#返回值-16] 成功创建后,该方法会返回一个 `AgoraAIGCService` 实例。 ### initialize [#initialize-1] ```objc - (void)initialize:(AgoraAIGCConfigure *)config; ``` 初始化 `AgoraAIGCService`。 该方法为异步操作。调用结果会在 [`onEventResultWithEvent`](#oneventresult) 回调中返回。 #### 参数 [#参数-15] | 参数 | 描述 | | --- | --- | | config | `AgoraAIGC` 初始化参数。详见 [`AgoraAIGCConfigure`](#aigcserviceconfig)。| ### getRoles [#getroles-1] ```objc - (NSArray * _Nullable)getRoles; ``` 获取 SDK 支持的所有的 `AgoraAIGCAIRole` 数组。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResultWithEvent(Initialize, Success)` 后调用。 ::: #### 返回值 [#返回值-17] SDK 支持的 [`AgoraAIGCAIRole`](#airole) 数组。 ### setRoleWithId [#setrolewithid] ```objc - (void)setRoleWithId:(NSString *)roleId; ``` 设置 SDK 使用的 `AgoraAIGCAIRole`。该方法设置即时生效。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResultWithEvent(Initialize, Success)` 后调用。 ::: #### 参数 [#参数-16] | 参数 | 描述 | | --- | --- | | `roleId` | 标明 `AgoraAIGCAIRole` 的 ID。 | ### getCurrentRole [#getcurrentrole-1] ```objc (AgoraAIGCAIRole * _Nullable)getCurrentRole; ``` 获取当前使用的 `AgoraAIGCAIRole`。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResultWithEvent(Initialize, Success)` 后调用。 ::: #### 返回值 [#返回值-18] 当前使用的 `AgoraAIGCAIRole`。 ### getServiceVendors [#getservicevendors-1] ```objc - (AgoraAIGCServiceVendorGroup * _Nullable)getServiceVendors; ``` 获取所有 AI 服务商的信息。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResultWithEvent(Initialize, Success)` 后调用。 ::: #### 返回值 [#返回值-19] 包含了所有 AI 服务商信息的 `AgoraAIGCServiceVendorGroup` 对象,由多个 [`AgoraAIGCSTTVendor`](#sttvendor)、[`AgoraAIGCLLMVendor`](#llmvendor) 和 [`AgoraAIGCTTSVendor`](#ttsvendor) 组成。 ### setServiceVendor [#setservicevendor-1] ```objc - (AgoraAIGCServiceCode)setServiceVendor:(AgoraAIGCServiceVendor *)vendor; ``` 设置所使用的 AI 服务商。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResultWithEvent(Initialize, Success)` 后调用。 ::: #### 参数 [#参数-17] | 参数 | 描述 | | --- | --- | | `vendor` | 设置的服务商对象 `AgoraAIGCServiceVendor`,包含 [`AgoraAIGCSTTVendor`](#sttvendor)、[`AgoraAIGCLLMVendor`](#llmvendor) 和 [`AgoraTTSVendor`](#ttsvendor)。每种类型只支持设置一个服务商。| #### 返回值 [#返回值-20] 该方法调用的结果,详见 [`AgoraAIGCServiceCode`](#servicecode)。 ### start [#start-1] ```objc - (void)start; ``` 开启 AgoraAIGCService 服务。 该方法为异步操作。调用结果会在 [`onEventResultWithEvent`](#oneventresult) 回调中返回。 :::warning[注意] 该方法需要在成功调用 `initialize`,且收到 `onEventResultWithEvent(Initialize, Success)` 后调用。 ::: ### stop [#stop-1] ```objc - (void)stop; ``` 停止 AgoraAIGCService 服务。 该方法为异步操作。调用结果会在 [`onEventResultWithEvent`](#oneventresult) 回调中返回。 :::warning[注意] 该方法需要在成功调用 `start`,且收到 `onEventResultWithEvent(Start, Success)` 后调用。 ::: ### pushSpeechDialogueWithData [#pushspeechdialoguewithdata] ```objc - (AgoraAIGCServiceCode)pushSpeechDialogueWithData:(NSData *)data vad:(AgoraAIGCVad)vad isLastFrame:(BOOL)isLastFrame; ``` 推送采集到的音频数据到 SDK。 :::warning[注意] 该方法需要在成功调用 `start`,且收到 `onEventResultWithEvent(Start, Success)` 后调用。 ::: #### 参数 [#参数-18] | 参数 | 描述 | | --- | --- | | `data` | 待推送的音频数据。 | | `vad` | 本地是否有人声。详见 [`AgoraAIGCVad`](#vad)。 | | `isLastFrame` | [aigcservice-ios-html-0-3-1 details](#table-slot-aigcservice-ios-html-0-3-1) | **aigcservice-ios-html-0-3-1 details** 是否是最后一帧音频数据: - `true`:是 - `false`:不是 该参数仅在 [`setSTTMode`](#setsttmode) 设置为 `AgoraAIGCServiceSTTModeControlled` 时有效。 #### 返回值 [#返回值-21] 该方法调用的结果,详见 [`AgoraAIGCServiceCode`](#servicecode)。 ### pushTxtDialogue [#pushtxtdialogue-1] ```objc - (AgoraAIGCServiceCode)pushTxtDialogue:(NSString *)text roundId:(NSString * _Nullable)roundId; ``` 推送采集到的文本数据到 SDK 的 LLM 模块,用于 LLM 处理文本数据。 该方法和 `pushMessagesToLlm` 均可用于推送文本数据到 LLM 模块,区别为该方法仅支持推送单条消息,`pushMessagesToLlm` 支持推送多条消息(消息及其上下文语境)。 :::warning[注意] - 该方法需要在成功调用 `start`,且收到 `onEventResultWithEvent(Start, Success)` 后调用。 - 建议文本数据的长度不超过 1 KB。对高于 1 KB 的数据我们不保证能正确处理。 ::: #### 参数 [#参数-19] | 参数 | 描述 | | --- | --- | | `text` | 待推送的文本数据。 | | `roundId` | [aigcservice-ios-html-1-2-1 details](#table-slot-aigcservice-ios-html-1-2-1) | **aigcservice-ios-html-1-2-1 details** 请求的 `roundId`,可为空。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果自行设置 `roundId`,为准确区分不同请求,请确保设置的 ID 全局唯一; - 如果 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 #### 返回值 [#返回值-22] 该方法调用的结果,详见 [`AgoraAIGCServiceCode`](#servicecode)。 ### pushMessagesToLlm [#pushmessagestollm-1] ```objc - (AgoraAIGCServiceCode)pushMessagesToLlm:(NSString *)messagesJsonArray extraInfoJson:(NSString * _Nullable)extraInfoJson roundId:(NSString * _Nullable)roundId; ``` 推送请求数据的 JSON 数组和其他字段信息到 LLM 模块,用于 LLM 处理相应请求数据。 该方法和 `pushTxtDialogue` 均可用于推送文本数据到 LLM 模块,区别为 `pushTxtDialogue` 仅支持推送单条消息,该方法支持推送多条消息(消息及其上下文语境)。 :::warning[注意] - 该方法需要在成功调用 `start`,且收到 `onEventResultWithEvent(Start, Success)` 后调用。 - 建议 JSON 数据的长度不超过 1 KB。对高于 1 KB 的数据我们不保证能正确处理。 ::: #### 参数 [#参数-20] | 参数 | 描述 | | --- | --- | | `messagesJsonArray` | 请求数据的 JSON 数组。 | | `extraInfoJson` | 其他特定字段信息的 JSON。 | | `roundId` | [aigcservice-ios-html-2-3-1 details](#table-slot-aigcservice-ios-html-2-3-1) | **aigcservice-ios-html-2-3-1 details** 请求的 `roundId`,可为空。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果自行设置 `roundId`,为准确区分不同请求,请确保设置的 ID 全局唯一; - 如果 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 #### 返回值 [#返回值-23] 该方法调用的结果,详见 [`AgoraAIGCServiceCode`](#servicecode)。 ### pushTxtToTTS [#pushtxttotts-1] ```objc - (AgoraAIGCServiceCode)pushTxtToTTS:(NSString *)text roundId:(NSString * _Nullable)roundId; ``` 推送采集到的文本数据到 SDK 的 TTS 模块,用于 TTS 播报文本。 :::warning[注意] - 该方法需要在成功调用 `start`,且收到 `onEventResultWithEvent(Start, Success)` 后调用。 - 建议文本数据的长度不超过 1 KB。对高于 1 KBB 的数据我们不保证能正确处理。 ::: #### 参数 [#参数-21] | 参数 | 描述 | | --- | --- | | `text` | 待推送的文本数据。 | | `roundId` | [aigcservice-ios-html-3-2-1 details](#table-slot-aigcservice-ios-html-3-2-1) | **aigcservice-ios-html-3-2-1 details** 请求的 `roundId`,可为空。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果自行设置 `roundId`,为准确区分不同请求,请确保设置的 ID 全局唯一; - 如果 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 #### 返回值 [#返回值-24] 该方法调用的结果,详见 [`AgoraAIGCServiceCode`](#servicecode)。 ### interrupt [#interrupt-1] ```objc - (void)interrupt:(AgoraAIGCServiceInterruptMask)mask; ``` 中断指定服务。 :::warning[注意] 该方法需要在成功调用 `start`,且收到 `onEventResultWithEvent(Start, Success)` 后调用。 ::: #### 参数 [#参数-22] | 参数 | 描述 | | ------ | ------------------------------------------------------------ | | `mask` | 服务类型的掩码值。详见 [`AgoraAIGCServiceInterruptMask`](#agoraaigcserviceinterruptmask)。服务类型支持使用按位或运算符(\|)进行组合,例:`mask = AgoraAIGCServiceInterruptMaskSTT \| AgoraAIGCServiceInterruptMaskLLM` 代表同时中断 STT 和 LLM 服务。 | ### setSTTMode [#setsttmode-1] ```objc - (AgoraAIGCServiceCode)setSTTMode:(AgoraAIGCServiceSTTMode)mode; ``` 设置 STT 服务的模式。 :::warning[注意] 该方法需要在成功调用 `start`,且收到 `onEventResultWithEvent(Start, Success)` 后调用。 ::: #### 参数 [#参数-23] | 参数 | 描述 | | ------ | ------------------------------------------------------------ | | `mode` | STT 服务模式。详见 [`AgoraAIGCServiceSTTMode`](#agoraaigcservicesttmode)。 | #### 返回值 [#返回值-25] 该方法调用的结果,详见 [`AgoraAIGCServiceCode`](#servicecode)。 ### setPrompt [#setprompt-1] ```objc - (AgoraAIGCServiceCode)setPrompt:(NSString *)prompt; ``` 设置大语言模型的 Prompt 信息。 :::warning[注意] 该方法需要在成功 `init`,且收到 `onEventResultWithEvent(Initialize, Success)` 后,且 `start` 前调用。 ::: #### 参数 [#参数-24] | 参数 | 描述 | | --- | --- | | `prompt` | Prompt 信息。| #### 返回值 [#返回值-26] 该方法调用的结果,详见 [`AgoraAIGCServiceCode`](#servicecode)。 ### getSdkVersion [#getsdkversion] ```objc + (NSString *)getSdkVersion; ``` 获取 AIGCService SDK 的版本号。 #### 返回值 [#返回值-27] 当前 SDK 的版本号。 ### destroy [#destroy-1] ```objc + (void)destory; ``` 销毁 `AgoraAIGCService` 实例。 该方法为异步操作。调用结果会在 [`onEventResultWithEvent`](#oneventresult) 回调中返回。 ## AgoraAIGCServiceDelegate [#agoraaigcservicedelegate] ### onEventResultWithEvent [#oneventresultwithevent] ```objc - (void)onEventResultWithEvent:(AgoraAIGCServiceEvent)event code:(AgoraAIGCServiceCode)code message:(NSString * _Nullable)message; ``` AIGCService 实例事件回调。 该回调在 SDK 调用 `initialize`、`start`、`stop`、`destroy` 后触发,报告对应方法的调用结果。 #### 参数 [#参数-25] | 参数 | 描述 | | --- | --- | | `event` | 该服务事件的类型,详见 [`AgoraAIGCServiceEvent`](#serviceevent)。| | `code` | 该服务事件的结果,详见 [`AgoraAIGCServiceCode`](#servicecode)。| | `message` | 事件信息。该字串可能为空。| ### onSpeech2TextWithRoundId [#onspeech2textwithroundid] ```objc - (AgoraAIGCHandleResult)onSpeech2TextWithRoundId:(NSString *)roundId result:(NSString *)result recognizedSpeech:(BOOL)recognizedSpeech code:(AgoraAIGCServiceCode)code; ``` 报告语音转文字 (STT) 处理后的结果。 #### 参数 [#参数-26] | 参数 | 描述 | | --- | --- | | `roundId` | [aigcservice-ios-html-4-1-1 details](#table-slot-aigcservice-ios-html-4-1-1) | | `result` | 语音识别出来的文字(UTF-8 字符集)。该参数为只读模式。 | | `recognizedSpeech` | [aigcservice-ios-html-4-3-1 details](#table-slot-aigcservice-ios-html-4-3-1) | | `code` | STT 语音识别结果。详见 [`AgoraAIGCServiceCode`](#servicecode)。 | **aigcservice-ios-html-4-1-1 details** 请求的 `roundId`。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果你在推送时设置了 `roundId`,回调中沿用你设置的 `roundId`; - 如果推送时 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 **aigcservice-ios-html-4-3-1 details** 该回调返回的 `result` 是否是一个完整的句子: - `YES`:是 - `NO`:不是 #### 返回值 [#返回值-28] `AgoraAIGCHandleResult`,该回调的处理结果类型。你需要设置该返回值: - `AgoraAIGCHandleResultContinue`:SDK 会继续处理后续流程 - `AgoraAIGCHandleResultDiscard`:SDK 会中断处理后续流程 :::warning[注意] 该规则仅在 `recognizedSpeech` 返回 `YES` 下有效。 ::: ### onLLMResultWithRoundId [#onllmresultwithroundid] ```objc - (AgoraAIGCHandleResult)onLLMResultWithRoundId:(NSString *)roundId answer:(NSString *)answer isRoundEnd:(BOOL)isRoundEnd estimatedResponseTokens:(NSUInteger)tokens code:(AgoraAIGCServiceCode)code; ``` 回调大语言模型 (LLM) 处理后的结果。 #### 参数 [#参数-27] | 参数 | 描述 | | --- | --- | | `roundId` | [aigcservice-ios-html-5-1-1 details](#table-slot-aigcservice-ios-html-5-1-1) | | `answer` | 大语言模型处理后的结果(UTF-8 字符集)。该参数为只读模式。 | | `isRoundEnd` | [aigcservice-ios-html-5-3-1 details](#table-slot-aigcservice-ios-html-5-3-1) | | `tokens` | 本轮 LLM 大模型处理返回内容大约消耗的 Token 数。该数值只是估算值,不作为计费标准,你可以利用该值监测并限制 Token 的消耗。如果返回的 `token` 为 `0`,可忽略该值。 | | `code` | LLM 大模型处理结果。详见 [`AgoraAIGCServiceCode`](#servicecode)。 | **aigcservice-ios-html-5-1-1 details** 请求的 `roundId`。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果你在推送时设置了 `roundId`,回调中沿用你设置的 `roundId`; - 如果推送时 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 **aigcservice-ios-html-5-3-1 details** 本轮大语言模型返回结果是否结束: - `YES`:是。 - `NO`:否。 #### 返回值 [#返回值-29] `AgoraAIGCHandleResult`,该回调的处理结果类型。你需要设置该返回值: - `AgoraAIGCHandleResultContinue`:SDK 会继续处理后续流程 - `AgoraAIGCHandleResultDiscard`:SDK 会中断处理后续流程 ### onText2SpeechResultWithRoundId [#ontext2speechresultwithroundid] ```objc - (AgoraAIGCHandleResult)onText2SpeechResultWithRoundId:(NSString *)roundId voice:(NSData *)voice sampleRates:(NSInteger)sampleRates channels:(NSInteger)channels bits:(NSInteger)bits code:(AgoraAIGCServiceCode)code; ``` 回调文字转语音 (TTS) 处理后的结果。 #### 参数 [#参数-28] | 参数 | 描述 | | --- | --- | | `roundId` | [aigcservice-ios-html-6-1-1 details](#table-slot-aigcservice-ios-html-6-1-1) | | `voice` | 文字转语音处理后的语音数据。该参数为读写模式。如果 `voice` 参数被修改,后续流程会用更新后的 `voice` 参数值作为输入。 | | `sampleRates` | 语音数据 (PCM) 的采样率,单位为 Hz。 | | `channels` | 语音数据 (PCM) 的通道数。 | | `bits` | 语音数据 (PCM) 的位数。 | | `code` | TTS 文本转语音处理结果。详见 [`AgoraAIGCServiceCode`](#servicecode)。 | **aigcservice-ios-html-6-1-1 details** 请求的 `roundId`。用于跟踪后续 LLM/TTS 对应关系的 ID,你可以利用该参数在 UI 层实现相关的业务逻辑。 - 如果你在推送时设置了 `roundId`,回调中沿用你设置的 `roundId`; - 如果推送时 `roundId` 为空,SDK 内部会分配一个 `roundId`,并在每形成一个完整句子时更新为新的 `roundId`。 #### 返回值 [#返回值-30] `AgoraAIGCHandleResult`,该回调的处理结果类型。你需要设置该返回值: - `AgoraAIGCHandleResultContinue`:SDK 会继续处理后续流程 - `AgoraAIGCHandleResultDiscard`:SDK 会中断处理后续流程 :::info[信息] 该回调是目前最后一个业务流程,返回值 `Continue` 和 `Discard` 效果一样,均不会影响后续业务。后续版本中我们可能会在该回调后添加其他业务。 ::: ### onSpeechStateChange [#onspeechstatechange-1] ```objc - (void)onSpeechStateChange:(AgoraAIGCServiceSpeechState)state; ``` 识别语音开始和结束的状态。 #### 参数 [#参数-29] | 参数 | 描述 | | --- | --- | | `state` | 语音的状态。详见 [`AgoraAIGCServiceSpeechState`](#agoraaigcservicespeechstate)。 | ## 类型定义 [#类型定义-1] ### AgoraAIGCConfigure [#agoraaigcconfigure] ```objc @interface AgoraAIGCConfigure : NSObject @property (nonatomic, copy, readonly)NSString *appId; @property (nonatomic, copy, readonly)NSString *rtmToken; @property (nonatomic, copy, readonly)NSString *userId; @property (nonatomic, assign, readonly)BOOL enableMultiTurnShortTermMemory; @property (nonatomic, assign, readonly)NSUInteger speechRecognitionFiltersLength; @property (nonatomic, strong, readonly)AgoraAIGCSceneMode *input; @property (nonatomic, strong, readonly)AgoraAIGCSceneMode *output; @property (nonatomic, assign, readonly)BOOL enableLog; @property (nonatomic, assign, readonly)BOOL enableSaveLogToFile; @property (nonatomic, copy, readonly, nullable)NSString *logFilePath; @property (nonatomic, copy, readonly)NSString *userName; @property (nonatomic, assign, readonly)BOOL enableChatIdleTip; @property (nonatomic, assign, readonly) AgoraNoiseEnvironment noiseEnvironment; @property (nonatomic, assign, readonly) AgoraSpeechRecognitionCompletenessLevel speechRecognitionCompletenessLevel; - (instancetype)initWithAppId:(NSString *)appId rtmToken:(NSString *)rtmToken userId:(NSString *)userId enableMultiTurnShortTermMemory:(BOOL)enableMultiTurnShortTermMemory speechRecognitionFiltersLength:(NSUInteger)speechRecognitionFiltersLength input:(AgoraAIGCSceneMode *)input output:(AgoraAIGCSceneMode *)output enableLog:(BOOL)enableLog enableSaveLogToFile:(BOOL)enableSaveLogToFile logFilePath:(NSString *)logFilePath userName:(NSString *)userName; enableChatIdleTip:(BOOL)enableChatIdleTip; noiseEnvironment:(AgoraNoiseEnvironment)noiseEnvironment speechRecognitionCompletenessLevel:(AgoraSpeechRecognitionCompletenessLevel)speechRecognitionCompletenessLevel; - (instancetype)init __attribute__((unavailable("Use initWithAppId instead"))); - (NSString *)description; @end ``` `AgoraAIGCConfigure` 的初始化配置。 | 参数 | 描述 | | --- | --- | | `appId` | 声网项目的 App ID。 | | `rtmToken` | 声网项目的 [RTM Token](/zh-CN/realtime-media/rtm/build/authentication-and-connection/user-authentication)。 | | `userId` | 用户 ID。 | | `enableMultiTurnShortTermMemory` | [aigcservice-ios-html-8-4-1 details](#table-slot-aigcservice-ios-html-8-4-1) | | `speechRecognitionFiltersLength` | 过滤语音识别结果的字数长度。 | | `input` | 输入参数,详见 [`AgoraAIGCSceneMode`](#scenemode)。 | | `output` | 输出参数,详见 [`AgoraAIGCSceneMode`](#scenemode)。 | | `enableLog` | [aigcservice-ios-html-8-8-1 details](#table-slot-aigcservice-ios-html-8-8-1) | | `enableSaveLogToFile` | [aigcservice-ios-html-8-9-1 details](#table-slot-aigcservice-ios-html-8-9-1) | | `logFilePath` | 设置 Log 的存储路径。如果不设或设为空字串,SDK 会使用默认的存储路径。 | | `userName` | 用户名。 | | `enableChatIdleTip` | [aigcservice-ios-html-8-12-1 details](#table-slot-aigcservice-ios-html-8-12-1) | | `noiseEnvironment` | 设置噪音环境级别,详见 [`AgoraNoiseEnvironment`](#noiseenvironment)。SDK会根据你的设置等级,相应地处理环境噪音对语音数据的影响。 | | `speechRecognitionCompletenessLevel` | 设置语音识别句子完整度级别,详见 [`AgoraSpeechRecognitionCompletenessLevel`](#speechrecognitioncompletenesslevel)。 | **aigcservice-ios-html-8-4-1 details** 是否开启多轮短时记忆: - `YES`:是。开启后,后续流程的处理会结合上下文语境。 - `NO`:否。 :::warning[注意] 该参数配置在调用 `pushMessagesToLlm` 时无效。 ::: **aigcservice-ios-html-8-8-1 details** 是否开启日志输出到 IDE 的控制台: - `YES`:是。 - `NO`:否。 **aigcservice-ios-html-8-9-1 details** 是否保存日志到文件系统: - `YES`:是。 - `NO`:否。 :::warning[注意] 该参数的设置只有在 `enableLog` 为 `YES` 时才生效。 ::: **aigcservice-ios-html-8-12-1 details** 是否开启闲时聊天提示信息: - `YES`:是。 - `NO`:(默认)否。 ### AgoraAIGCAIRole [#agoraaigcairole] ```objc @interface AgoraAIGCAIRole : NSObject @property (nonatomic, copy, readonly)NSString *roleId; @property (nonatomic, copy, readonly)NSString *roleName; /// means description @property (nonatomic, copy, readonly)NSString *desc; @property (nonatomic, copy, readonly)NSString *profession; /// ["male","female"] @property (nonatomic, copy, readonly)NSString *gender; - (instancetype)initWithRoleId:(NSString *)roleId roleName:(NSString *)roleName desc:(NSString *)desc profession:(NSString *)profession gender:(NSString *)gender; @end ``` AI 服务的属性。 | 参数 | 描述 | | --- | --- | | `roleId` | AI 服务的 ID,是 AI 服务的唯一标识。| | `roleName` | AI 服务的名称。| | `desc` | AI 服务的简单介绍。| | `profession` | AI 服务的职业。 | | `gender` | AI 服务的性别:`"male"` 表示男性,`"female"` 表示女性。| ### AgoraAIGCSceneMode [#agoraaigcscenemode] ```objc @interface AgoraAIGCSceneMode : NSObject @property (nonatomic, assign, readonly)AgoraAIGCLanguage language; @property (nonatomic, assign, readonly)NSUInteger speechFrameBits; @property (nonatomic, assign, readonly)NSUInteger speechFrameSampleRates; @property (nonatomic, assign, readonly)NSUInteger speechFrameChannels; - (instancetype)initWithLanguage:(AgoraAIGCLanguage)language speechFrameBits:(NSUInteger)speechFrameBits speechFrameSampleRates:(NSUInteger)speechFrameSampleRates speechFrameChannels:(NSUInteger)speechFrameChannels; - (instancetype)init __attribute__((unavailable("Use initWithLanguage instead"))); @end ``` `AgoraAIGCConfigure` 中 `input` 和 `output` 参数的详细配置项。 | 参数 | 描述 | | --- | --- | | `language` | 语言类型,详见 [`AgoraAIGCLanguage`](#language)。 | | `speechFrameBits` | 语音数据 (PCM) 的位数。SDK 仅支持 16。 | | `speechFrameSampleRates` | 语音数据 (PCM) 的采样率。SDK 仅支持 16000。 | | `speechFrameChannels` | 语音数据 (PCM) 的通道数。SDK 仅支持 1。 | ### AgoraAIGCSTTVendor [#agoraaigcsttvendor] ```objc @interface AgoraAIGCSTTVendor : AgoraAIGCBaseVendor @property (nonatomic, copy, readonly)NSString *Id; @property (nonatomic, copy, readonly)NSString *vendorName; - (instancetype)initWithAccountInJson:(NSString * _Nullable)accountInJson Id:(NSString *)Id vendorName:(NSString *)vendorName; - (instancetype)init __attribute__((unavailable("Use initWithAccountInJson:Id:vendorName instead"))); - (instancetype)initWithAccountInJson:(NSString * _Nullable)accountInJson __attribute__((unavailable("Use initWithAccountInJson:Id:vendorName instead"))); @end @interface AgoraAIGCBaseVendor : NSObject @property (nonatomic, copy, nullable, readonly)NSString *accountInJson; - (instancetype)initWithAccountInJson:(NSString * _Nullable)accountInJson; @end ``` 语音转文字的供应商信息。 | 参数 | 描述 | | --- | --- | | `Id` | 语音转文字供应商的 ID。| | `vendorName` | 供应商名称。| | `accountInJson` | 供应商自有的账号信息。若使用该字段,联系 sales@shengwang.cn 了解字段的 JSON 格式。| ### AgoraAIGCLLMVendor [#agoraaigcllmvendor] ```objc @interface AgoraAIGCLLMVendor : AgoraAIGCBaseVendor @property (nonatomic, copy, readonly)NSString *Id; @property (nonatomic, copy, readonly)NSString *vendorName; @property (nonatomic, copy, readonly)NSString *model; - (instancetype)initWithAccountInJson:(NSString * _Nullable)accountInJson Id:(NSString *)Id vendorName:(NSString *)vendorName model:(NSString *)model; - (instancetype)init __attribute__((unavailable("Use initWithAccountInJson:Id:vendorName:model instead"))); - (instancetype)initWithAccountInJson:(NSString * _Nullable)accountInJson __attribute__((unavailable("Use initWithAccountInJson:Id:vendorName:model instead"))); @end @interface AgoraAIGCBaseVendor : NSObject @property (nonatomic, copy, nullable, readonly)NSString *accountInJson; - (instancetype)initWithAccountInJson:(NSString * _Nullable)accountInJson; @end ``` 大语言模型的供应商信息。 | 参数 | 描述 | | --- | --- | | `Id` | 大语言模型供应商的 ID。| | `vendorName` | 供应商名称。| | `model` | 模型参数。| | `accountInJson` | 供应商自有的账号信息。若使用该字段,联系 sales@shengwang.cn 了解字段的 JSON 格式。| ### AgoraAIGCTTSVendor [#agoraaigcttsvendor] ```objc @interface AgoraAIGCTTSVendor : AgoraAIGCBaseVendor @property (nonatomic, copy, readonly)NSString *Id; @property (nonatomic, copy, readonly)NSString *language; @property (nonatomic, copy, readonly)NSString *voiceName; @property (nonatomic, copy, readonly)NSString *voiceNameValue; @property (nonatomic, copy, readonly)NSString *vendorName; @property (nonatomic, copy, readonly)NSString *voiceStyle; - (instancetype)initWithAccountInJson:(NSString * _Nullable)accountInJson Id:(NSString *)Id language:(NSString *)language voiceName:(NSString *)voiceName voiceNameValue:(NSString *)voiceNameValue vendorName:(NSString *)vendorName voiceStyle:(NSString *)voiceStyle; - (instancetype)init __attribute__((unavailable("Use initWithAccountInJson instead"))); - (instancetype)initWithAccountInJson:(NSString * _Nullable)accountInJson __attribute__((unavailable("Use initWithAccountInJson:Id:language:voiceName:voiceNameValue:vendorName:voiceStyle instead"))); @end @interface AgoraAIGCBaseVendor : NSObject @property (nonatomic, copy, nullable, readonly)NSString *accountInJson; - (instancetype)initWithAccountInJson:(NSString * _Nullable)accountInJson; @end ``` 文字转语音的供应商信息。 | 参数 | 描述 | | --- | --- | | `Id` | 文字转语音供应商的 ID。| | `language` | 所支持的语言。如果为空,则表示支持所有语言。| | `voiceName` | 发言人名称,仅用于标签上展示的名称。 | | `voiceNameValue` | 发言人名称参数值。| | `vendorName` | 供应商名称。| | `voiceStyle` | (选填)发言人风格参数值。| | `accountInJson` | 供应商自有的账号信息。若使用该字段,联系 sales@shengwang.cn 了解字段的 JSON 格式。| ### AgoraAIGCServiceEvent [#agoraaigcserviceevent] 服务事件类型。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `AgoraAIGCServiceEventIdle` | `0` | 初始状态。 | | `AgoraAIGCServiceEventInitialize` | `1` | 初始化状态,对应调用 `initialize` 方法。 | | `AgoraAIGCServiceEventStart` | `2` | 启动状态,对应调用 `start` 方法。| | `AgoraAIGCServiceEventStop` | `3` | 停止服务状态,对应调用 `stop` 方法。 | | `AgoraAIGCServiceEventDestory` | `4` | 销毁服务状态,对应调用 `destroy` 方法。| ### AgoraAIGCServiceCode [#agoraaigcservicecode] 服务事件结果。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `AgoraAIGCServiceCodeErrorGeneral` | `-1` | 通用错误。| | `AgoraAIGCServiceCodeSuccess` | `0` | 成功。| | `AgoraAIGCServiceCodeInitializeFail` | `1` | 初始化失败。| | `AgoraAIGCServiceCodeStartFail` | `2` | 启动失败。| | `AgoraAIGCServiceCodeLicenseExpire` | `5` | License 过期。 | | `AgoraAIGCServiceCodeTimeout` | `9` | 服务超时。 | | `AgoraAIGCServiceCodeContentManagementPolicy` | `10` | LLM 判定请求内容不合规,触发内容审核。 | ### AgoraAIGCVad [#agoraaigcvad] 本地是否有人声。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `AgoraAIGCVadUnknow` | `-1` | 不确定。| | `AgoraAIGCVadMute` | `0`| 本地无人声。| | `AgoraAIGCVadNonMute` | `1` | 本地有人声。 | ### AgoraAIGCLanguage [#agoraaigclanguage] 语言类型。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `AgoraAIGCLanguageZH_CN` | `0` | 中文。 | | `AgoraAIGCLanguageEN_US` | `1` | 英文。 | ### AgoraNoiseEnvironment [#agoranoiseenvironment] 噪音环境级别。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `AgoraNoiseEnvironmentQuiet` | `0` | 周围环境噪音很少,比较安静。| | `AgoraNoiseEnvironmentNormal` | `1` | 周围环境噪音正常。| | `AgoraNoiseEnvironmentNoise` | `2` | 周围环境噪音很强。| ### AgoraSpeechRecognitionCompletenessLevel [#agoraspeechrecognitioncompletenesslevel] 语音识别句子的完整性级别。级别越高,则识别句子的完整性越好;相应地,语音识别的整体时间也会越长。 | 枚举名 | 枚举值 | 描述 | | --- | --- | --- | | `AgoraSpeechRecognitionCompletenessLevelLow` | `0` | 低级别。| | `AgoraSpeechRecognitionCompletenessLevelNormal` | `1` | 正常级别。| | `AgoraSpeechRecognitionCompletenessLevelHigh` | `2` | 高级别。| ### AgoraAIGCServiceInterruptMask [#agoraaigcserviceinterruptmask] 服务类型的掩码值。 | 枚举名 | 枚举值 | 描述 | | ------------------------------------- | -------- | ------------- | | `AgoraAIGCServiceInterruptMaskSTT` | `0b0001` | STT 服务类型值。 | | `AgoraAIGCServiceInterruptMaskLLM` | `0b0010` | LLM 服务类型值。 | | `AgoraAIGCServiceInterruptMaskTTS` | `0b0100` | TTS 服务类型值。 | ### AgoraAIGCServiceSTTMode [#agoraaigcservicesttmode] STT 服务模式类型。 | 枚举名 | 枚举值 | 描述 | | ----------------------------------- | ------ | -------------------------------------- | | `AgoraAIGCServiceSTTModeFreeStyle` | `0` | (默认)自由模式,适用于实时对话、实时语音识别。 | | `AgoraAIGCServiceSTTModeControlled` | `1` | 受控模式,适用于单段语音输入。 | ### AgoraAIGCServiceSpeechState [#agoraaigcservicespeechstate] 语音的状态 | 枚举名 | 枚举值 | 描述 | | --------------------------------------- | ------ | ---------------------- | | `AgoraAIGCServiceSpeechStateStateStart` | `0` | 语音开始。 | | `AgoraAIGCServiceSpeechStateStateEnd` | `1` | 语音结束。 | <_PlatformProcessedMarker close="true" />