总览

工作原理

走一遍完整的 Embedded 集成:从认证、绑定设备、同步音频,到上传与转写,理解 SDK 与各 API 如何拼在一起。

开发者平台处于内测阶段,以下端点路径与字段用于说明流程,正式契约以联调时提供的文档为准。端点 host 为 platform.ikho.cn/developer/api。

端到端集成 Embedded,一般走五步:认证 API 发令牌 → SDK 绑定设备 → 同步音频到 App →(可选)文件上传 API 传云 → 转写 API 出稿。下面逐步说明。

1 · 用认证 API 签发令牌

Embedded 有两类凭据要区分:

用户令牌:用户级令牌,携带你系统里的用户标识,由合作方令牌签发,用于绑定设备
Client ID 与 API Key:用于调用转写 API

合作方令牌是应用级令牌,一个合作方令牌可以签发多个用户令牌。

用凭据换取合作方令牌

POST https://platform.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": 3600
}

签发用户令牌

POST https://platform.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 初始化、扫描并连接用户的 iKho 设备。绑定过程用你的凭据完成加密与同步握手,数据只与你的应用同步。

用 Embedded SDK 绑定设备

class="tk-cmt">// 初始化 SDK
private let customDomain = class="tk-str">"platform.ikho.cn"

func configure(userId: String) {
    RecordingStore.shared.userId = userId
    IkhoDeviceAgent.shared.initSDK(
        userAccessToken: userAccessToken,
        customDomain: customDomain
    )
}

class="tk-cmt">// 扫描设备
func startScan() {
    IkhoDeviceAgent.shared.startScan()
}

class="tk-cmt">// 通过蓝牙连接并绑定设备
func connect(_ device: ScannedDevice, userId: String) {
    IkhoDeviceAgent.shared.connectBleDevice(bleDevice: device.ble, deviceToken: userId)
}

3 · 把音频同步到 App

iKho 设备有自己的存储,录音先落在设备本地。录制结束后,把音频文件从设备同步到用户的移动应用。同步可走 BLE,也可走 Wi-Fi 快传(适合大文件)。

BLE 与 Wi-Fi 快传同步

class="tk-cmt">// BLE 同步
IkhoDeviceAgent.shared.exportAudio(
    sessionId: file.sessionId,
    outputDir: outputDir,
    format: .wav,
    channels: 1,
    callback: callback
)

class="tk-cmt">// Wi-Fi 快传:设备开热点后再拉流
IkhoDeviceAgent.shared.setDeviceWiFi(open: true)
class="tk-cmt">// 握手成功后
IkhoWiFiAgent.shared.exportAudioViaWiFi(sessionId: file.sessionId, outputDir: outputDir)

4 ·(可选)用文件上传 API 传云

转写 API 接受任意公网可访问的音频地址。你可以把文件放在自己的存储上,也可以用 iKho 的文件上传 API。用 iKho 托管存储时,上传分三步:生成预签名上传地址 → 分片上传音频 → 提交分片信息完成合并。完成后拿到可访问的下载地址,交给下一步。

5 · 用转写 API 出稿

把上传得到的音频地址交给转写 API,异步得到带说话人与时间戳的逐字稿。转写在后台完成降噪、说话人分离、语言识别等处理。发起任务后轮询状态,状态为 SUCCESS 时结果可取。

提交转写任务

POST https://platform.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"
}

查询结果:SUCCESS 时返回逐字稿

{
  "transcription_id": "task_exec_xxx",
  "status": "SUCCESS",
  "data": {
    "text": "会议 10 点开始...",
    "language": "zh",
    "duration": 1843,
    "segments": [
      { "start": 0, "end": 4.2, "text": "会议 10 点开始。", "speaker": "发言人 1" }
    ]
  }
}

绑定与加密

绑定,就是把用户的设备与你的应用关联起来。之所以叫「绑定」,是因为一台 S1 同一时间只能绑定到一个应用。绑定后,你的合作方与用户凭据用于对该用户数据的加密、解密与同步,数据只与你的应用同步,不会流向其他 Embedded 应用。这也是离线加密的基础:即使设备丢失或被盗,数据依旧无法被读取。

BLE 与 Wi-Fi 快传

设备默认通过 BLE(低功耗蓝牙)与应用配对并同步音频。对较大的录音文件,Wi-Fi 快传是更快的选择:它在设备与手机之间建立一条直连,同步速度比 BLE 快约一个数量级。Wi-Fi 快传需要在配置 iOS 应用时申请相应的热点权限。

准备好动手就看快速开始;要把 SDK 集成进现有应用,直接进 iOS SDK。

这一页有帮助吗?