# MCP 接入与使用指南

> 更新于 2026-11-03 · 适用于 KiiKii MCP 与 WorkBuddy 连接器  
> HTML 版本：https://kiikii.cc/doc/mcp

## 快速答案

- MCP 是「AI 客户端 → kiikii 能力」的标准化连接，一套配置同时支持数字人与通用创作。
- 非 WorkBuddy 客户端使用个人 API 密钥（`kii_sk_` 开头）；WorkBuddy 使用 OAuth，不需要密钥。
- 数字人视频是「先出方案、确认后生产」的两阶段流程；图片、通用视频、配音是异步任务。
- 密钥只在创建时显示一次，最多 10 个有效密钥，每个密钥对应一份独立配置。

## 1. 什么是 MCP

MCP（Model Context Protocol）让 AI 客户端可以调用外部能力。接入 kiikii MCP 后，你可以在 Cursor、Claude Desktop、Trae 等对话窗口里直接查询积分、克隆形象、生成数字人视频、出图、出片与配音，不需要打开网页。

一个 kiikii MCP 配置同时包含数字人与通用创作能力，AI 会按「是否需要数字人形象/音色出镜」自动选择工具。

## 2. MCP 能做什么

| 能力 | 具体内容 | 典型说法 |
| --- | --- | --- |
| 账户 | 积分余额、套餐、充值链接 | 查询我的 kiikii 积分余额 |
| 数字人形象 | 克隆参考人像、按描述设计新形象、查看我的形象 | 用这张照片克隆我的形象 |
| 音色 | 筛选系统音色、克隆专属音色、按性别年龄匹配 | 找一个 45 岁温柔女声 |
| 数字人视频 | 五种模式、分镜方案、确认生产、改方案、改字幕 | 做一条 45 秒菊花知识讲解 |
| 通用图片 | 文生图、参考图生图、1–4 张批量、最高 4K | 生成一张 4K 16:9 咖啡海报 |
| 通用视频 | 文生视频、图生视频、首尾帧、参考视频、音频驱动 | 生成 5 秒雨夜霓虹街头 |
| 配音 | 文本转语音、音色/语速/格式/语气 | 把这段文案配成中文男声 |
| 素材与任务 | 上传票据、资产中心链接、任务状态与结果 | 把刚生成的视频发我 |

## 3. 申请 API 密钥

1. 登录后进入「个人中心 → API 密钥」，地址：`/profile?section=apiKeys`。
2. 点击「创建密钥」，填写名称（例如 WorkBuddy-1、Cursor-办公室）与有效期。
3. 创建成功后立即复制完整密钥与「已填入密钥的 MCP 配置」；关闭弹窗后无法再次查看完整密钥。
4. 需要停用时在列表中撤销，撤销立即生效，不影响其他密钥。

| 项目 | 说明 |
| --- | --- |
| 密钥格式 | `kii_sk_` 开头，只在创建时显示一次，服务端仅保存哈希 |
| 有效上限 | 最多 10 个有效密钥 |
| 权限范围 | 账户读取、素材读取、素材写入；不能登录后台或修改账号设置 |
| 有效期 | 永久有效 / 30 天 / 90 天 / 365 天 |
| 与 WorkBuddy 的关系 | WorkBuddy 走 OAuth 连接器，不需要这里的密钥 |

不要把密钥写进公开仓库、截图或群聊；多人共用时每人单独创建密钥，便于审计与撤销。

## 4. 接入 AI 客户端

kiikii MCP 使用 Streamable HTTP，不需要本地安装服务。

```json
{
  "mcpServers": {
    "kiikii": {
      "type": "streamableHttp",
      "url": "https://api.kiikii.vip/api/mcp",
      "headers": {
        "Authorization": "Bearer <你的 API KEY>"
      }
    }
  }
}
```

| 客户端 | 配置位置 | 说明 |
| --- | --- | --- |
| Cursor | `~/.cursor/mcp.json` | 合并 mcpServers 片段，重启 Cursor |
| Claude Desktop | `claude_desktop_config.json` | 合并后重启客户端 |
| Trae | 设置 → MCP → 添加 | 选择 HTTP / Streamable HTTP，填地址并在 Header 加 Authorization |
| WorkBuddy | 连接器安装 | 使用 OAuth 授权，不需要 API 密钥 |

验证：先问「查询我的 kiikii 积分余额」。能返回昵称与余额，说明密钥与网络正常。

## 5. 工具一览

| 工具 | 作用 | 什么时候用 |
| --- | --- | --- |
| `kiikii_get_account` | 查询昵称、积分、套餐、充值链接 | 开始生成前确认余额 |
| `kiikii_list_modes` | 列出五种数字人模式与推荐模式 | 用户没说清模式时 |
| `kiikii_list_avatars` | 列出可用形象，返回 avatarId | 生成数字人视频前选形象 |
| `kiikii_create_avatar` | 克隆 / 设计数字人形象（异步） | 需要新形象时 |
| `kiikii_list_voices` | 按性别、年龄、关键词筛选音色 | 选配音或描述音色时 |
| `kiikii_create_voice_clone` | 用样本克隆专属音色 | 需要复刻声音时 |
| `kiikii_create_upload_ticket` | 创建上传票据并返回上传地址 | 需要上传图片/音频/歌曲时 |
| `kiikii_complete_upload` | 校验并登记素材，返回 assetToken | 文件上传完成后 |
| `kiikii_get_upload_ticket` | 查询上传票据状态 | 上传中断或排查时 |
| `kiikii_create_video` | 创建数字人视频方案（只出方案） | 开始一条数字人视频时 |
| `kiikii_confirm_video` | 确认方案并开始生产 | 用户明确回复确认后 |
| `kiikii_revise_video_plan` | 在原任务上修改分镜方案 | 方案确认前提出修改时 |
| `kiikii_update_video_subtitles` | 重烧字幕，不重做画面 | 成片后改字幕样式或文字 |
| `kiikii_get_job` | 查询形象/视频任务状态与结果 | 查方案、进度、成片 |
| `kiikii_list_jobs` | 列出最近任务 | 不知道 jobId 时找回任务 |
| `kiikii_generate_image` | 通用文生图 / 参考图生图 | 海报、配图、封面 |
| `kiikii_generate_video` | 通用文生视频 / 图生视频 / 首尾帧 / 音频驱动 | 不需要数字人出镜的画面 |
| `kiikii_generate_audio` | 文本转语音 | 旁白、配音、口播音频 |
| `kiikii_get_creation` | 查询通用创作任务状态与结果 | 轮询图片/视频/音频任务 |
| `kiikii_list_creation_models` | 列出可用模型与能力 | 指定模型或不确定参数时 |
| `kiikii_open_asset_gallery` | 生成签名资产中心链接 | 用户只想浏览形象或音色 |

## 6. 数字人视频

| 模式 | 适合内容 | 目标时长 | 素材要求 |
| --- | --- | --- | --- |
| studio 常规 | 科普、讲解、产品介绍 | 30–150 秒 | 形象 + 音色 |
| continuous 一镜到底 | 单人口播、观点输出 | 20–60 秒 | 形象 + 音色；生成时间更长 |
| mv 音乐 MV | 歌曲、翻唱、品牌主题曲 | 跟随歌曲 | 1–2 个形象 + 歌曲 |
| ecommerce 电商带货 | 单品卖点、活动促销 | 20–80 秒 | 形象 + 音色 + 商品图（+场景图） |
| store_visit 探店宣传 | 门店、本地生活、文旅 | 20–80 秒 | 形象 + 音色 + 1–3 张场景图 |

流程：

1. `kiikii_create_video` 只产出分镜与台词，不生成视频。
2. AI 必须展示方案、时长与预估积分，等你明确回复「确认 / 开始生成」后才调用 `kiikii_confirm_video`。
3. 确认前说「场景 2 改成文生视频」「第 3 段台词更口语」，使用 `kiikii_revise_video_plan` 在原任务上改，不新建任务。
4. 确认后异步生产，用 `kiikii_get_job` 查询阶段与成片。

提示词示例：

```text
用我的形象「知雅」和 45 岁温柔女声，做一条 45 秒知识讲解：
主题是菊花与中国重阳节，开场点题，中间讲品种、花语与习俗，
结尾给一句养护小知识。9:16 竖屏，720p，烧录字幕。

（方案出来后）把场景 2 改成文生视频分镜，画面是雨后的菊花特写；
场景 3 改成 Web 动画，用时间轴讲重阳节习俗。
```

## 7. 通用创作：图片、视频与配音

### 图片

- 一次最多 4 张，每张独立计费；支持文生图与参考图生图（最多 4 张参考图）。
- 画幅：auto / 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3。
- 清晰度：`resolution` 支持 1K / 2K / 4K；当前只有 nano-banana-2 真正支持 2K / 4K，其余模型按 1K 提交。
- 用户点名模型时，先调用 `kiikii_list_creation_models` 使用返回的 model 值。

### 视频

- 支持文生视频、图生视频、首帧、首尾帧、普通参考图/视频、音频驱动；每次只生成 1 条。
- 画幅：auto / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16；分辨率 480 / 720 / 1080；时长默认 5 秒。
- 需要数字人形象出镜、口播、对口型或唱歌 MV 时，改用数字人工具。

### 配音

- 文本最多 2 万字，支持格式与语速（0.5–2）。
- 用户描述音色时传 `voiceHint`（或 gender + age），服务端按年龄与气质匹配最接近的真实音色。
- 需要专属声音时，先用 `kiikii_create_voice_clone` 复刻音色。

## 8. 任务、轮询与积分

| 任务类型 | 创建工具 | 查询工具 | 结果内容 |
| --- | --- | --- | --- |
| 数字人形象 | `kiikii_create_avatar` | `kiikii_get_job` | 形象 ID、四视图与封面 |
| 数字人视频 | `kiikii_create_video` / `confirm_video` | `kiikii_get_job` | 方案、分段状态、成片地址 |
| 通用图片 | `kiikii_generate_image` | `kiikii_get_creation` | 图片地址、模型、实际扣费 |
| 通用视频 | `kiikii_generate_video` | `kiikii_get_creation` | 视频地址、模型、实际扣费 |
| 通用配音 | `kiikii_generate_audio` | `kiikii_get_creation` | 音频地址、音色、实际扣费 |

- 轮询间隔建议 10–20 秒，任务完成或失败后停止。
- 生成前先调用 `kiikii_get_account` 查看积分，结果会返回实际扣费。
- 失败任务按站内规则退款；超时任务保持运行态，继续用原 jobId 查询，不会重复创建。
- 数字人视频支持幂等键，重试时复用同一个 `idempotencyKey`。

## 9. 使用技巧

1. 不确定模式时先说内容目标与时长，让 AI 返回推荐，不要一上来就指定「一镜到底」。
2. 改分镜时说明「第几段 + 改成什么」，一次最多改 3 段。
3. 分镜类型可以换：想要实拍感空镜说「把场景 2 改为文生视频」；要人物长段落讲述说「场景 3 改为数字人长镜头」。
4. 素材先上传拿到 assetToken 再引用；对话中不能直接替换素材。
5. 音色用描述而不是猜 ID，例如「45 岁女性、温柔知性」。
6. 成片后的修改分开说：改字幕用字幕重烧；改画面或台词需要改分镜；只想重新拼接说「重新合成成片」。

## 10. 常见问题

### MCP 和 WorkBuddy 连接器有什么区别？

两者连接同一套 kiikii 能力。WorkBuddy 通过 OAuth 安装连接器，不需要 API 密钥；Cursor、Claude Desktop、Trae 使用个人 API 密钥。

### 为什么我在 MCP 里生成图片只有 1K？

当前只有 nano-banana-2 支持 2K / 4K，其余图片模型固定按 1K 提交。需要高清晰度时，先调用 `kiikii_list_creation_models` 确认模型，再传 `resolution`：1K / 2K / 4K。

### 为什么让 AI 改方案，它却新建了一条视频？

数字人视频是两阶段流程：`kiikii_create_video` 只产出方案，确认后才生产。已有待确认方案时，应调用 `kiikii_revise_video_plan` 在原任务上修改。

### 生成任务一直显示处理中怎么办？

图片、视频、配音都是异步任务。创建后拿到 jobId，每 10–20 秒查询一次；超时不会重复扣费。

### API 密钥丢了还能找回吗？

不能。完整密钥只在创建时显示一次，服务端只保存哈希。请撤销旧密钥并重新创建。

### 一个账号可以创建几个密钥？

最多 10 个有效密钥，每个密钥对应一份独立配置。

### 在 MCP 里上传素材和网页端有什么不同？

先调用 `kiikii_create_upload_ticket` 获取上传地址，把文件字节 PUT 上去，再调用 `kiikii_complete_upload` 换取 assetToken。后续工具只接受 assetToken。

### MCP 生成的视频会计费吗？

会，与网页端使用同一套积分规则，从当前账号余额扣除；失败任务按站内规则退款。

## 11. 开始使用

1. 创建密钥：个人中心 → API 密钥，创建后复制完整 MCP 配置。
2. 粘贴到客户端：Cursor、Claude Desktop 或 Trae 的 MCP 配置里合并 mcpServers，重启客户端。
3. 验证并创作：先问「查询我的 kiikii 积分余额」，再说「用我的形象做一条 45 秒知识讲解」。

- 创建 API 密钥：https://kiikii.cc/profile?section=apiKeys
- 数字人使用指南：https://kiikii.cc/doc/digital-human
- 模型能力与积分：https://kiikii.cc/doc/models