工作原理
走一遍完整的 Embedded 集成:从认证、绑定设备、同步音频,到上传与转写,理解 SDK 与各 API 如何拼在一起。
开发者平台处于内测阶段,以下端点路径与字段用于说明流程,正式契约以联调时提供的文档为准。端点 host 为 ikho.cn/developer/api。
能力边界:本页第 1、4、5 步(认证、文件上传、转写)现已可用;第 2、3 步依赖 Embedded SDK,该 SDK 规划中,尚未开放,相关代码是开放后的接口形态,现在无法编译运行。只走可用部分的完整实现见端到端教程·后端篇。
端到端集成 Embedded,一般走五步:认证 API 发令牌 → SDK 绑定设备 → 同步音频到 App →(可选)文件上传 API 传云 → 转写 API 出稿。其中第 2、3 步要等 SDK 开放;在此之前把你自己的音频交给第 4、5 步即可跑通出稿链路。下面逐步说明。
1 · 用认证 API 签发令牌(现已可用)
Embedded 有两类凭证要区分:
- 用户令牌:用户级令牌,携带你系统里的用户标识,由合作方令牌签发,用于绑定设备
- Client ID 与 API Key:用于调用转写 API
合作方令牌是应用级令牌,一个合作方令牌可以签发多个用户令牌。
POST https://ikho.cn/developer/api/oauth/partner/access-token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
// 返回
{
"access_token": "eyJhbGciOiJSUz...",
"refresh_token": "eyJhbGci...",
"token_type": "bearer",
"expires_in": 7200
}POST https://ikho.cn/developer/api/open/partner/users/access-token
Authorization: Bearer <partner_access_token>
Content-Type: application/json
{
"user_id": "<你系统里稳定的用户标识>",
"expires_in": 86400
}
// 返回
{
"access_token": "eyJhbGci...",
"token_type": "bearer",
"expires_in": 86400
}2 · 用 Embedded SDK 绑定设备(SDK 开放后)
Embedded SDK 规划中,尚未开放,本节与下一节描述的是开放后的接口形态,现在还拿不到可集成的包。
SDK 开放后,把用户令牌交给移动应用,用 SDK 初始化、扫描并连接用户的 iKho 设备。绑定过程用你的凭证完成加密与同步握手,数据只与你的应用同步。
// 初始化 SDK
private let customDomain = "ikho.cn"
// 用后端签发的用户令牌初始化 SDK
IKhoEmbedded.configure(userToken: userAccessToken)
// 扫描并绑定设备
final class DeviceCoordinator: IKhoDeviceDelegate {
func start() {
IKhoDeviceManager.shared.delegate = self
IKhoDeviceManager.shared.scanDevices()
}
func deviceScanResult(_ devices: [IKhoDevice]) {
guard let target = devices.first else { return }
IKhoDeviceManager.shared.stopScan()
IKhoDeviceManager.shared.bind(device: target)
}
func deviceBindChanged(_ result: IKhoBindResult) {
// 绑定成功后即可同步录音
}
}3 · 把音频同步到 App(SDK 开放后)
iKho 设备有自己的存储,录音先落在设备本地。SDK 开放后,可把音频文件从设备同步到用户的移动应用,同步走 BLE 或 Wi-Fi 快传(适合大文件)。在此之前,直接把你自己已有的音频文件交给下面第 4、5 步。
// BLE 同步(默认通道)
IKhoDeviceManager.shared.exportAudio(recordingId: recording.id, format: .m4a)
func exportProgress(recordingId: String, progress: Int) { /* 0-100 */ }
func exportCompleted(recordingId: String, outputPath: String) { /* 文件已就绪 */ }
// Wi-Fi 快传:开启后由 wifiTransferReady 回调触发导出
IKhoDeviceManager.shared.setWiFiTransfer(enabled: true)
func wifiTransferReady() {
IKhoDeviceManager.shared.exportAudio(recordingId: recording.id, format: .m4a)
}4 ·(可选)用文件上传 API 传云(现已可用)
转写 API 接受任意公网可访问的音频地址。你可以把文件放在自己的存储上,也可以用 iKho 的文件上传 API。用 iKho 托管存储时,上传分三步:生成预签名上传地址 → 分片上传音频 → 提交分片信息完成合并。完成后拿到可访问的下载地址,交给下一步。
5 · 用转写 API 出稿(现已可用)
把上传得到的音频地址交给转写 API,异步得到带说话人与时间戳的逐字稿。转写在后台完成降噪、说话人分离、语言识别等处理。发起任务后轮询状态,状态为 SUCCESS 时结果可取。
POST https://ikho.cn/developer/api/open/partner/ai/transcriptions/
Content-Type: application/json
X-Client-Api-Key: [API_KEY]
X-Client-Id: [CLIENT_ID]
{
"file_url": "<公网可访问的音频地址>",
"params": {
"transcribe": { "language": "auto", "model": "ikho-asr-pro" },
"diarization": { "enabled": true }
}
}
// 返回
{
"transcription_id": "task_exec_xxx",
"status": "PENDING",
"data": {}
}{
"transcription_id": "task_exec_xxx",
"status": "SUCCESS",
"data": {
"text": "会议 10 点开始。",
"language": "zh",
"duration": 1843,
"segments": [
{ "speaker": "发言人 1", "start_ms": 0, "end_ms": 4200, "text": "会议 10 点开始。" }
]
}
}绑定与加密
绑定,就是把用户的设备与你的应用关联起来。之所以叫「绑定」,是因为一台 S1 同一时间只能绑定到一个应用。绑定后,你的合作方与用户凭证用于对该用户数据的加密、解密与同步,数据只与你的应用同步,不会流向其他 Embedded 应用。这也是离线加密的基础:即使设备丢失或被盗,数据依旧无法被读取。
BLE 与 Wi-Fi 快传
设备默认通过 BLE(低功耗蓝牙)与应用配对并同步音频。对较大的录音文件,Wi-Fi 快传是更快的选择:它在设备与手机之间建立一条直连,同步速度比 BLE 快约一个数量级。Wi-Fi 快传需要在配置 iOS 应用时申请相应的热点权限。