公共类型与错误处理

TopStepAIKit 的语音、翻译、同传、录音和图片生成模块共享语言、音频格式、任务标识、回调和错误模型。

TSAIAudioFormat

枚举值	数值	说明
`TSAIAudioFormatUnknown`	-1	未知格式
`TSAIAudioFormatNone`	0	结果中表示无音频；配置中表示自动嗅探文件格式
`TSAIAudioFormatPcm`	1	PCM
`TSAIAudioFormatOpus`	2	Opus
`TSAIAudioFormatMp3`	3	MP3
`TSAIAudioFormatWav`	4	WAV

裸 PCM 无文件头，必须明确指定格式、采样率、声道和位深等参数。

TSAILanguage

TSAILanguage 是 ASR、翻译、同传、录音和图片生成共用的 AI 服务语言枚举，与设备 UI 使用的 TSLanguageType 不同。

枚举值	值	枚举值	值
`Unknown`	-1	`Auto`	0
`ChineseSimplified`	1	`ChineseTraditional`	2
`EnglishUS`	3	`EnglishUK`	4
`Japanese`	5	`Korean`	6
`French`	7	`German`	8
`Spanish`	9	`Russian`	10
`Portuguese`	11	`Indonesian`	12
`Malay`	13	`Filipino`	14
`Thai`	15	`Arabic`	16
`Vietnamese`	17	`Danish`	18
`Greek`	19	`Finnish`	20
`Hindi`	21	`Italian`	22
`Dutch`	23	`Norwegian`	24
`Polish`	25	`Swedish`	26
`Swahili`	27	`Turkish`	28
`Bengali`	29	`Romanian`	30
`Nepali`	31	`Ukrainian`	32
`Czech`	33	`Welsh`	34
`Hungarian`	35	`Icelandic`	36
`Georgian`	37	`Kazakh`	38
`Luxembourgish`	39	`Latvian`	40
`Malayalam`	41	`Slovak`	42
`Slovenian`	43	`Serbian`	44
`Telugu`	45	`Catalan`	46
`Tamil`	47	`Urdu`	48
`Croatian`	49	`Bulgarian`	50
`Lithuanian`	51	`Latin`	52
`Maori`	53	`Persian`	54
`Azerbaijani`	55	`Kannada`	56
`Estonian`	57	`Macedonian`	58
`Breton`	59	`Basque`	60
`Armenian`	61	`Mongolian`	62
`Bosnian`	63	`Albanian`	64
`Galician`	65	`Marathi`	66
`Punjabi`	67	`Sinhala`	68
`Khmer`	69	`Shona`	70
`Yoruba`	71	`Somali`	72
`Afrikaans`	73	`Occitan`	74
`Belarusian`	75	`Tajik`	76
`Sindhi`	77	`Gujarati`	78
`Amharic`	79	`Yiddish`	80
`Lao`	81	`Uzbek`	82
`Faroese`	83	`HaitianCreole`	84
`Pashto`	85	`Turkmen`	86
`NorwegianNynorsk`	87	`Maltese`	88
`Sanskrit`	89	`Burmese`	90
`Tibetan`	91	`Malagasy`	92
`Assamese`	93	`Tatar`	94
`Hawaiian`	95	`Lingala`	96
`Hausa`	97	`Bashkir`	98
`Javanese`	99	`Sundanese`	100

表中名称应加上 TSAILanguage 前缀，例如 ChineseSimplified 的完整枚举值是 TSAILanguageChineseSimplified。

Auto 与 Unknown

Auto 仅用于翻译或同传的源语言自动检测。
ASR、录音和图片生成不接受 Auto。
翻译和同传的目标语言必须是具体语言。
Unknown 通常表示未设置或使用 App 当前本地化，具体语义以模型属性说明为准。

BCP-47 转换

+ (nullable NSString *)bcp47CodeForLanguage:(TSAILanguage)language;
+ (nullable NSString *)targetBcp47CodeForLanguage:(TSAILanguage)language;
+ (TSAILanguage)languageForBcp47Code:(nullable NSString *)code;

TSAIASRScene

枚举值	数值	说明
`TSAIASRSceneUnknown`	-1	未指定场景
`TSAIASRSceneOnSite`	1	会议、采访、面对面等现场录音
`TSAIASRSceneCall`	2	电话或 VoIP 通话录音

TSAIChatIntentType

枚举值	数值	说明
`Unknown`	-1	未知协议意图；原始值见 `intentId`
`None`	0	纯对话，无可执行意图
`PhotoCapture` / `PhotoUnderstand`	1 / 2	拍照 / 理解照片
`VideoStart` / `VideoStop`	3 / 4	开始 / 停止录像
`AudioRecord`	5	开始录音
`VolumeUp` / `VolumeDown` / `VolumeSet`	10 / 11 / 12	音量控制
`MusicPlay` / `MusicStop`	20 / 21	播放 / 停止音乐
`MusicNext` / `MusicPrev`	22 / 23	下一首 / 上一首
`CallAnswer` / `CallDecline` / `CallRecord`	30 / 31 / 32	通话控制
`DeviceBatteryQuery` / `DevicePowerOff`	40 / 41	查询电量 / 设备关机
`DialogExit` / `AgentSwitch` / `VoiceClone`	50 / 51 / 52	退出对话 / 切换角色 / 声音克隆

表格中的短名称应加上 TSAIChatIntentType 前缀，例如 TSAIChatIntentTypePhotoCapture。

任务与回调约定

单次任务通常同步返回客户端生成的 taskId，与 Provider 或服务端任务 ID 无关。
流式 partial 回调可能调用零次或多次；completion 在成功、失败或取消时调用一次。
completion 是任务终态的权威信号。
调用取消接口后，Provider 可能无法物理停止服务端任务，但 SDK 会屏蔽迟到结果。
回调线程以具体接口说明为准；问答、生图和部分 Context 回调明确位于主线程。

TSAIErrorDomain

错误码	数值	说明
`TSAIErrorCodeInvalidParameter`	1001	参数无效
`TSAIErrorCodeNotSupported`	1002	当前能力不支持
`TSAIErrorCodeContextInactive`	1003	Context 未激活或已失效
`TSAIErrorCodeProviderUnavailable`	1004	Provider 不可用
`TSAIErrorCodeBridgeUnavailable`	1005	平台 DeviceBridge 不可用
`TSAIErrorCodeActivationSuperseded`	1006	激活请求已被后续请求取代
`TSAIErrorCodeBusy`	1007	存在互斥任务
`TSAIErrorCodeCancelled`	1008	任务已取消
`TSAIErrorCodeAuthorizationRequired`	1009	Provider 需要鉴权
`TSAIErrorCodeTaskFailed`	1010	AI 任务执行失败
`TSAIErrorCodeContentRejected`	1011	内容被服务拒绝
`TSAIErrorCodeTimeout`	1012	请求超时
`TSAIErrorCodeNetworkUnavailable`	1013	网络不可用
`TSAIErrorCodeInvalidResponse`	1014	Provider 响应无效
`TSAIErrorCodeAudioRouteUnavailable`	1015	没有满足请求或回退策略的完整音频路由
`TSAIErrorCodeAudioRouteMismatch`	1016	业务用例、设备场景或已占用路由与请求不匹配

错误处理示例

if ([error.domain isEqualToString:TSAIErrorDomain]) {
    switch (error.code) {
        case TSAIErrorCodeAuthorizationRequired:
            TSLog(@"AI 服务需要重新鉴权");
            break;
        case TSAIErrorCodeNetworkUnavailable:
            TSLog(@"当前网络不可用");
            break;
        case TSAIErrorCodeContextInactive:
            TSLog(@"请重新获取 activeContext");
            break;
        default:
            TSLog(@"AI 操作失败: %@", error.localizedDescription);
            break;
    }
}

TSAIAudioFormat​

TSAILanguage​

Auto 与 Unknown​

BCP-47 转换​

TSAIASRScene​

TSAIChatIntentType​

任务与回调约定​

TSAIErrorDomain​

错误处理示例​