接口概述
TmkTranslationSDK 对外接口概览。iOS 与 Android 提供对齐的能力，本页按能力域分组列出各接口的用途、参数、返回值与成功判定方式。完整的接入示例与字段细节见 iOS SDK API 与 Android SDK API。
如何判断调用成功
同步接口看返回值（Bool / 对象 / 句柄，无异常即成功）；异步接口以回调进入成功分支为准（iOS Result.success / Android onSuccess），不能以方法立即返回值判断成败（尤其建房接口）。
iOS
生命周期与鉴权
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
sdkVersion | 获取 SDK 版本号 | 无 | String（如 1.2.0） | 返回非空版本字符串 |
sdkInit(_ config:) | 初始化全局配置 | config: TmkTranslationGlobalConfig（appId/secret、在线鉴权上下文、日志、诊断、网络环境、自定义地址、networkTimeout） | 无 | 无异常返回（仅保存配置，不触发鉴权） |
verifyAuth(_ callback:) | 在线/离线鉴权 | callback: AuthCallback | 无 | 回调进入 .success(())（仅由在线鉴权结果决定） |
releaseChannel() | 会话级释放 | 无 | 无 | 同步返回（停通道、取消建房、异步关在线房间；不清空全局配置与鉴权） |
destroy() | 全局释放 | 无 | 无 | 同步返回（清空鉴权与配置；后续须重新 sdkInit） |
语言列表
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
isOfflineTranslationSupported() | 查询是否支持离线 | 无 | Bool | 返回 true（建议鉴权成功后调用） |
getOnlineSupportedLanguages(version:_:) / getOfflineSupportedLanguages(version:_:) | 获取在线/离线支持语言列表 | version: String?、callback | TmkSDKCancellable? | 回调进入 .success(TmkLocaleListResponse) |
在线房间
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
createTmkTranslationRoom(config:_:) | 创建在线房间 | config: TmkTranslationRoomConfig（源/目标语言、scenario、roomId?、channelScenario、messageTunnel、speakers?、translateEngine、dialogConversationAudioMode）、callback | 无（勿用立即返回值） | 回调进入 .success(TmkTranslationRoom) |
room.closeRoom(completion:) | 关闭在线房间 | completion | TmkSDKCancellable? | 回调进入 .success(()) |
room.updateRoomLocale(sourceLocales:targetLocales:completion:) | 运行中切换房间语言 | sourceLocales:[String]、targetLocales:[String]、completion | TmkSDKCancellable? | 回调进入 .success(()) |
room.updateTranslateEngine(_:completion:) | 运行中切换在线翻译引擎 | engine: .automatic/.fast/.accurate、completion | TmkSDKCancellable? | 回调进入 .success(()) |
room.updateScenario(_:completion:) | 运行中切换房间能力 | scenario: .recognize/.toText/.toSpeech、completion | TmkSDKCancellable? | 回调进入 .success(()) |
通道
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
createTranslationChannel(_:callback:) / (_:listener:callback:) | 创建并自动启动通道（在线/离线统一入口） | config: TmkTranslationChannelConfig（room、mode、scenario、源/目标语言、采样率、声道数、播放模式、音色、模型目录、translateMode、capabilityTier 等）、可选 listener、callback | 无 | 回调进入 .success(TmkTranslationChannel) |
channel.pushStreamAudioData(_:channelCount:extraChunk:) | 推送 PCM 音频 | data(16bit LE PCM)、channelCount(1 单/2 双)、extraChunk(一般 nil)；另有按 speakerChannel 推流重载 | 无 | 无异常返回（未 start/状态不允许时被忽略） |
channel.release() / channel.createTranslationChannel() | 通道资源释放 / 重建 | 无 | 无 | 无异常返回 |
channel.currentRuntimeState() / getTranslationMode() / getScenario() / getChannelEngineType() | 通道状态/能力查询 | 无 | 状态快照 / 枚举 | 同步返回 |
channel.setTranslationListener(_:) | 设置/替换结果监听器 | listener: TmkTranslationListener | 无 | 同步返回 |
channel.updateLanguages(sourceLang:targetLang:) | 运行中更新通道语言（同步，仅更新内部字段，无网络/模型切换） | sourceLang、targetLang | 无 | 同步返回 |
channel.updateLanguages(sourceLang:targetLang:completion:) | 运行中异步切换通道语言（在线/离线统一入口）。在线：发网络指令，有超时可取消；离线：流式切换，不打断流，不可取消 | sourceLang、targetLang、completion: (Result<Void, TmkTranslationError>) -> Void | TmkSDKCancellable?（在线为真句柄，离线为 no-op，通道已释放时 nil） | 回调进入 .success(()) |
channel.updateTranslateMode(_:completion:) | 运行时切换翻译下发模式（partial/stable）。仅离线支持；在线返回 .engineNotSupported | mode: TmkTranslateDeliveryMode、completion | 无 | 回调进入 .success(()) |
channel.updateScenario(_:completion:) | 运行时切换能力档位（recognize/toText/toSpeech），在线/离线统一。在线：服务端热切；离线：升档前校验模型就绪，按需加载/卸载 MT/TTS | scenario: TmkRoomScenario、completion | TmkSDKCancellable?（在线为真句柄，离线为 no-op） | 回调进入 .success(()) |
channel.updateSpeaker(speakers:callback:) | 运行中更新 TTS 音色 | speakers:[TmkSpeaker]、callback | TmkSDKCancellable? | 回调进入 .success(()) |
离线模型管理
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
downloadOfflineModels(srcLang:dstLang:modelRootDirectory:scenario:needMt:needTts:listener:) | 下载离线模型 | 源/目标语言、模型目录?、scenario、needMt、needTts、listener | 无 | 通过 listener 回调进度/就绪/错误 |
cancelOfflineModelDownload() | 取消下载 | 无 | 无 | 同步返回（listener 回 cancelled 状态） |
getOfflineModelPackageInfos(...) | 查询模型包状态 | 源/目标语言、scenario、needMt、needTts | [TmkOfflineModelPackageInfo] | 同步返回列表 |
isOfflineModelReady(...) | 同步检查模型整体就绪 | 源/目标语言、scenario、needMt、needTts | Bool | 返回 true |
isAsrModelReady / isMtModelReady / isTtsModelReady / isTtsDataReady | 单项模型就绪检查 | 语言码 / 源目标语言 / 模型目录? | Bool | 返回 true（语言码按主标签归一 zh-CN→zh） |
checkOfflineModelReadyAsync(…, completion:) | 异步整体就绪检查 | 源/目标语言、scenario、needMt、needTts、callbackQueue、completion | 无 | completion(Bool) 回 true（主线程） |
defaultOfflineModelRootDirectory() / …URL() | 默认模型目录 | 无 | String / URL | 同步返回（Documents/tmkOfflineModel） |
诊断、工具与回调数据
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
getDiagnosisDirectoryURL() | 获取诊断目录 | 无 | URL? | 返回非 nil（需先 setDiagnosisEnabled(true)） |
onRecognized extraData 新增字段 | ASR 回调 result.extraData 中新增 "offset"（纳秒, Int64）和 "duration"（纳秒, Int64），表示本段语音在音频流中的偏移与时长；MT 翻译回调不包含此字段 | — | — | extraData["offset"]/extraData["duration"] 有值（可能为 nil 表示服务端未下发） |
TmkTranslationPCMTools.* | PCM 工具（混音/拆分/格式转换） | PCM/数组数据 | Data / [Float] / 元组 | 同步返回（拆分失败可能 nil） |
Android
生命周期与鉴权
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
sdkVersion | 获取 SDK 版本号 | 无 | String（如 1.2.0） | 返回非空版本字符串 |
sdkInit(context, config) | 初始化全局配置 | context: Context（建议 ApplicationContext）、config: TmkTransGlobalConfig（appId/secret、在线鉴权上下文、诊断、网络环境、自定义地址、networkTimeoutSeconds） | 无 | 无异常返回（仅保存配置，不触发鉴权） |
verifyAuth(callback) | 在线/离线鉴权 | callback: AuthCallback | 无 | 回调进入 onSuccess()（仅由在线鉴权结果决定） |
releaseChannel() | 会话级释放 | 无 | 无 | 同步返回（停通道、异步关在线房间；不清空全局配置与鉴权） |
destroy() | 全局释放 | 无 | 无 | 同步返回（清空鉴权与配置；后续须重新 sdkInit） |
语言列表
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
isOfflineTranslationSupported() | 查询是否支持离线 | 无 | Boolean | 返回 true（建议鉴权成功后调用） |
getOnlineSupportedLanguages(version, callback) / getOfflineSupportedLanguages(version, callback) | 获取在线/离线支持语言列表 | version: String?、callback: TmkLocaleListCallback | Cancelable | 回调进入 onSuccess(TmkLocaleListResponse) |
在线房间
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
createTmkTranslationRoom(config, callback) | 创建在线房间 | config: TmkTranslationRoomConfig（scenario 必填、源/目标语言、speakers、onlineTranslateEngine、roomScenario、translateMode、dialogConversationAudioMode）、callback | Cancelable（回调前可取消） | 回调进入 onSuccess(TmkTranslationRoom) |
room.updateRoomLocale(sourceLocales, targetLocales, callback) | 运行中切换房间语言 | sourceLocales、targetLocales、callback | — | 回调成功（Result<Unit>）；无活动通道返回 INVALID_STATE |
room.updateTranslateEngine(engine, callback) | 运行中切换在线翻译引擎 | engine: AUTOMATIC/FAST/ACCURATE、callback | — | 回调成功（Result<Unit>） |
room.updateScenario(scenario, callback) | 运行中切换房间能力 | scenario: RECOGNIZE/TRANSLATE_SPEECH_TO_TEXT/TRANSLATE_SPEECH_TO_SPEECH、callback | — | 回调成功（Result<Unit>） |
通道
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
createTranslationChannel(context, config, callback) / (…, listener, callback) | 创建通道（在线/离线统一入口） | context、config: TmkTransChannelConfig（translateMode 等）、可选 listener、callback | 无 | 回调进入 onSuccess(TmkTranslationChannel)（三参重载需自行 setTranslationListener+start()；四参重载自动启动） |
channel.pushStreamAudioData(data, channelCount, extraChunk) | 推送 PCM 音频 | data: ByteArray(16bit LE PCM)、channelCount(1 单/2 双)、extraChunk(一般 null) | 无 | 无异常返回（未 start/状态不允许时被忽略） |
channel.start() / destroy() | 启动通道和销毁通道 | 无 | 无 | 无异常返回（状态以 onStateChanged 为准） |
channel.currentRuntimeState() / getTranslationMode() / getScenario() / getChanelEngineType() / getTranslationListener() | 通道状态/能力查询 | 无 | 状态快照 / 枚举 / listener | 同步返回 |
channel.setTranslationListener(listener) | 设置/替换结果监听器 | listener: TmkTranslationListener | 无 | 同步返回 |
channel.updateLanguages(sourceLang, targetLang, callback) | 运行中异步切换通道语言（在线/离线统一入口）。在线：发网络指令，有超时可取消；离线：流式切换，不打断流，不可取消 | sourceLang: String、targetLang: String、callback: ActionCallback | Cancelable（在线为真句柄，离线为 no-op） | 回调进入 onSuccess(Result<Unit>) |
channel.updateTranslateMode(mode) | 运行时切换翻译下发模式（partial/stable）。仅离线支持，在线静默忽略 | mode: TmkTranslateDeliveryMode | 无 | 同步返回（离线引擎内部异步切换） |
channel.updateScenario(scenario, callback) | 运行时切换能力档位（RECOGNIZE/TRANSLATE_SPEECH_TO_TEXT/TRANSLATE_SPEECH_TO_SPEECH），在线/离线统一。在线：服务端热切；离线：升档前校验模型就绪，按需加载/卸载 MT/TTS | scenario: TmkRoomScenario、callback: ActionCallback | Cancelable（在线为真句柄，离线为 no-op） | 回调进入 onSuccess(Result<Unit>) |
channel.updateSpeaker(speakers, callback) | 运行中更新 TTS 音色 | speakers: List<TmkSpeaker>、callback: ActionCallback | Cancelable | 回调进入 onSuccess(Result<Unit>) |
离线模型管理
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
downloadOfflineModels(context, srcLang, dstLang, scenario, needMt, needTts, listener) / downloadChineseEnglishOfflineModels(...) | 下载离线模型 / 中英双向 | 源/目标语言、scenario、needMt、needTts、listener（多重载，可省 context 或传 modelRootDirectory） | 无 | 通过 listener 回调进度/就绪/错误 |
cancelOfflineModelDownload() | 取消下载 | 无 | 无 | 同步返回（listener 回 cancelled 状态） |
getOfflineModelPackageInfos(context, ...) | 查询模型包状态 | context、源/目标语言、scenario、needMt、needTts | List<TmkOfflineModelPackageInfo> | 同步返回列表 |
isOfflineModelReady(context, ...) | 同步检查模型整体就绪 | context、源/目标语言、scenario、needMt、needTts | Boolean | 返回 true |
isAsrModelReady / isMtModelReady / isTtsModelReady / isTtsDataReady | 单项模型就绪检查 | 语言码 / 源目标语言 / 模型目录?（均有带 context 重载） | Boolean | 返回 true（语言码按主标签归一 zh-CN→zh） |
checkOfflineModelReadyAsync(context, …, completion) | 异步整体就绪检查 | context、源/目标语言、scenario、needMt、needTts、completion | 无 | completion(Boolean) 回 true（主线程） |
defaultOfflineModelRootDirectory() / (context) | 默认模型目录 | 可选 context（可在 init 前查询） | String | 同步返回 |
回调数据
| 接口 | 说明 | 传入参数 | 返回值 | 如何判断调用成功 |
|---|---|---|---|---|
onRecognized extraData 新增字段 | ASR 回调 r.extraData 中新增 "offset"（纳秒, Long）和 "duration"（纳秒, Long），表示本段语音偏移与时长；MT 翻译回调不含此字段 | — | — | r.extraData["offset"]/r.extraData["duration"] 有值（可能缺失，表示服务端未下发） |