InkTalk API 配置与获取指南

1. 服务用途

InkTalk 使用火山引擎双向流式语音识别 WebSocket 接口完成实时语音转写。默认配置为豆包流式语音识别模型 2.0 小时版：

• WebSocket：wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
• 默认资源 ID：volc.seedasr.sauc.duration
• 官方协议文档：双向流式语音识别 WebSocket

2. 开通服务

1. 登录火山引擎豆包语音控制台。
2. 找到「语音识别大模型」或「豆包流式语音识别模型 2.0」。
3. 按实际计费方式开通小时版或并发版。
4. 记录开通的模型版本和计费方式。InkTalk 中选择的资源 ID 必须与控制台开通项一致。

3. 获取新版 API Key

1. 打开豆包语音 API Key 管理。
2. 创建或复制当前项目可用的 API Key。
3. 在 InkTalk 设置页的「语音识别」区域填写「API Key」。
4. 使用新版 API Key 时，将旧版 App ID 和 Access Token 留空。

新版鉴权在 WebSocket 握手时使用 X-Api-Key。InkTalk 会自动生成请求 ID 和协议序号，不需要手工填写。

4. 使用旧版 App ID 与 Access Token

旧版控制台用户可以打开旧版语音服务控制台查询 App ID 和 Access Token。

在 InkTalk 中：

• 「API Key」留空。
• 「App ID」填写旧版 App ID，对应请求头 X-Api-App-Key。
• 「Access Token」填写旧版 Access Token，对应请求头 X-Api-Access-Key。

5. 选择正确的资源 ID

6. 在 InkTalk 中验证

1. 打开 InkTalk 设置。
2. 保存语音凭据和资源 ID。
3. 点击「测试语音识别连接」。
4. InkTalk 会验证 WebSocket 握手、开始请求和服务端首包确认，不会访问麦克风。
5. 出现「ASR 协议验证成功」和 logid 后，再到真实输入框测试麦克风、实时文本和最终定稿。

7. 排错链接

• 流式语音识别错误码
• QPS 与并发查询说明
• 调用量查询说明
• 热词配置
• 热词与上下文最佳实践

1. InkTalk 的接口要求

AI 文本处理是可选功能，用于总结、翻译、整理和自由语音指令。InkTalk 固定使用以下兼容方式：

• 请求地址：{Base URL}/chat/completions
• 请求方法：POST
• 鉴权：Authorization: Bearer {API Key}
• 请求主体：model 与 messages
• 响应读取：choices[0].message.content

因此，提供方必须兼容 OpenAI Chat Completions 的请求和响应结构。填写 Base URL 时不要附加 /chat/completions，InkTalk 会自动追加该路径。

2. 设置字段说明

3. OpenAI API

获取步骤：

1. 登录 OpenAI API Platform。
2. 在 API Keys 页面创建项目 API Key。
3. 根据账号状态配置 API 计费与用量限制。ChatGPT 订阅与 API 用量属于不同产品，API 可用额度以 API Platform 为准。
4. 在 InkTalk 中填写以下内容：

gpt-4o-mini 当前支持 v1/chat/completions。模型能力与可用端点见 OpenAI Docs：GPT-4o mini，鉴权方式见 OpenAI API Authentication。

4. 阿里云百炼与千问

获取步骤：

1. 阅读获取与配置百炼 API Key。
2. 进入阿里云百炼控制台，选择业务空间并创建 API Key。
3. 确认 API Key 所属地域、业务空间和计费方案。
4. 从百炼 Base URL 总览选择与 API Key 匹配的地址。

中国大陆按量付费的简单配置：

生产环境可以使用业务空间专属地址：

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1

将 {WorkspaceId} 替换为控制台显示的业务空间 ID。API Key、地域、业务空间和 Base URL 必须配套，否则通常返回 HTTP 401。

5. 火山方舟豆包大模型

获取步骤：

1. 登录火山方舟控制台。
2. 在模型列表或体验中心选择支持 Chat API 的模型，并记录模型 ID。
3. 在火山方舟 API Key 管理创建 API Key。
4. 参考火山方舟开始使用和 ChatCompletions API确认模型 ID 与接口。

InkTalk 配置示例：

6. DeepSeek API

获取步骤：

1. 登录 DeepSeek Platform。
2. 在 API Keys 页面创建密钥。
3. 根据平台要求充值或确认可用余额。
4. 参考 DeepSeek API Quick Start 选择当前模型。

InkTalk 配置示例：

7. 关闭思考模式开关

InkTalk 的「关闭思考模式」会同时发送多种兼容字段：

• enable_thinking=false
• thinking={"type":"disabled"}
• reasoning_effort="minimal"

8. 常见 AI 错误

InkTalk 的中英文手写识别使用 Google ML Kit Digital Ink Recognition 19.0.0。该功能不需要申请 API Key，也不需要填写 Base URL。

首次选择某种手写语言时，InkTalk 会按需下载对应的语言模型。根据 Google ML Kit Digital Ink Recognition 官方文档，每种语言模型大约需要 20 MB 存储空间。

使用要求：

• 首次下载模型时需要网络连接。
• 设备需要能够访问 Google 提供的模型下载服务。
• 模型下载完成后，识别过程在设备上执行，不需要用户提供云端 API Key。
• 中文和英文模型分别下载；切换语言时可能触发新的下载。

InkTalk 将凭据保存到应用私有的 SharedPreferences，但「配置导出」文件会包含语音识别和 AI 服务密钥。

• 不要把导出的 JSON 文件发送到聊天群、公开仓库或工单附件。
• 更换手机后导入配置，应在确认成功后删除外部存储中的明文备份。
• 手机丢失、备份泄露或怀疑 Key 被复制时，应立即在对应服务控制台撤销并重建 Key。
• API Key 通常关联计费账户。建议在服务商控制台设置预算、额度和模型范围。移动网络 IP 经常变化，配置 IP 白名单前应确认不会阻断手机访问。
• 面向多人或公开发布时，不应继续在客户端保存长期有效的生产密钥，应改用服务端代理和短期凭据。

只使用语音输入

• 已开通豆包流式语音识别。
• 已获取豆包语音 API Key，或旧版 App ID 与 Access Token。
• InkTalk 资源 ID 与控制台开通项一致。
• 「测试语音识别连接」成功。
• 已授予录音权限，并在真实输入框完成录音测试。

使用 AI 文本处理与自由语音指令

• 已选择兼容 OpenAI Chat Completions 的提供方。
• Base URL 不包含 /chat/completions。
• API Key、地域、计费方案和 Base URL 相互匹配。
• 模型 ID 支持 Chat Completions。
• 「测试 AI 连接」成功。
• 已了解文本会发送到所选第三方模型服务，并接受对应服务的隐私与计费条款。

使用手写识别

• 不需要申请 API Key。
• 首次使用时保持网络可用。
• 为每个需要的语言模型预留约 20 MB 存储空间。
• 等待模型下载完成后再开始书写。

以下内容不应填写到 InkTalk 的 API Key 字段：

• ChatGPT 登录密码、ChatGPT 会话 Cookie 或 ChatGPT 订阅信息。
• 阿里云账号登录密码、火山引擎账号登录密码。
• Google 账号密码或 Google Cloud 服务账号密钥。
• Android 输入法授权码、短信验证码或手机解锁密码。