01 · Overview
什么是 MCP
MCP（Model Context Protocol）是一种让 AI 客户端调用外部能力的标准协议。接入 kiikii MCP 后，你不需要打开网页，在 Cursor、Claude Desktop、Trae 等对话窗口里说一句话，就能查询积分、克隆形象、生成数字人视频、出图、出片和配音。
快速答案
- MCP 是「AI 客户端 → kiikii 能力」的桥：一套配置同时支持数字人与通用创作。
- 非 WorkBuddy 客户端使用个人 API 密钥（
kii_sk_开头），WorkBuddy 使用 OAuth，不需要密钥。 - 数字人视频是「先出方案、确认后生产」的两阶段流程；图片、通用视频、配音是异步任务。
- 密钥只在创建时显示一次，最多 10 个有效密钥，每个密钥对应一份独立配置。
一个 kiikii MCP 配置同时包含数字人与通用创作能力，不需要为两种需求分别配置；AI 会按「是否需要数字人形象/音色出镜」自动选择工具。
02 · Capabilities
MCP 能做什么
把网页端的主要生产能力搬进对话：既能「问」，也能「做」，还能「改」。
| 能力 | 具体内容 | 典型说法 |
|---|---|---|
| 账户 | 积分余额、套餐、充值链接 | 查询我的 kiikii 积分余额 |
| 数字人形象 | 克隆参考人像、按描述设计新形象、查看我的形象 | 用这张照片克隆我的形象 |
| 音色 | 筛选系统音色、克隆专属音色、按性别年龄匹配 | 找一个 45 岁温柔女声 |
| 数字人视频 | 五种模式、分镜方案、确认生产、改方案、改字幕 | 做一条 45 秒菊花知识讲解 |
| 通用图片 | 文生图、参考图生图、1–4 张批量、最高 4K | 生成一张 4K 16:9 咖啡海报 |
| 通用视频 | 文生视频、图生视频、首尾帧、参考视频、音频驱动 | 生成 5 秒雨夜霓虹街头 |
| 配音 | 文本转语音、音色/语速/格式/语气 | 把这段文案配成中文男声 |
| 素材与任务 | 上传票据、资产中心链接、任务状态与结果 | 把刚生成的视频发我 |
MCP 不会替你做「业务判断」：模式、形象、音色、时长不清楚时，它会先追问或返回可选项，确认后再提交，避免生成一条不符合预期的成片。
03 · API Key
申请 API 密钥
密钥是 MCP 的身份凭证，代表你的账号扣费与素材权限，请按密码级别保管。
登录并打开密钥页
登录后进入「个人中心 → API 密钥」，地址是 /profile?section=apiKeys。
创建密钥
点击「创建密钥」，填写名称（例如 WorkBuddy-1、Cursor-办公室），选择有效期；每个客户端建议单独一个密钥。
立即保存完整配置
创建成功后弹窗会显示完整密钥和一份已填入密钥的 MCP 配置，点「复制 MCP 配置」保存。关闭后无法再次查看完整密钥。
按需撤销
在「我的密钥」里可以随时撤销；撤销立即失效，不影响其他密钥。
| 项目 | 说明 |
|---|---|
| 密钥格式 | kii_sk_ 开头，只在创建时显示一次，服务端仅保存哈希 |
| 有效上限 | 最多 10 个有效密钥，可分别给不同客户端或同事 |
| 权限范围 | 账户读取、素材读取、素材写入；不能登录后台或修改账号设置 |
| 有效期 | 永久有效 / 30 天 / 90 天 / 365 天，到期自动失效 |
| 与 WorkBuddy 的关系 | WorkBuddy 走 OAuth 连接器，不需要这里的密钥 |
不要把密钥写进公开仓库、截图或群聊。多人共用时建议每人单独创建密钥，便于审计和单独撤销。
04 · Connect
接入 AI 客户端
kiikii MCP 使用 Streamable HTTP，不需要本地安装服务，复制配置即可使用。
通用 MCP 配置（把密钥替换成你自己的）
{
"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 密钥 |
粘贴配置
把上面 JSON 里的 mcpServers 合并到客户端配置；多个密钥可以配成不同名字，例如 kiikii-work、kiikii-home。
重启客户端
保存配置后完全退出并重新打开，确保 MCP 服务被加载。
验证连接
先问一句「查询我的 kiikii 积分余额」。能返回昵称与余额，说明密钥与网络都正常。
如果客户端提示 401 或未授权，优先检查 Authorization 是否为 Bearer + 完整密钥、密钥是否已撤销或过期；不要把密钥放在 URL 参数里。
05 · Tools
工具一览
你不需要记工具名，AI 会根据需求自动选择；下面这张表用于排查「为什么它调用了这个工具」。
| 工具 | 作用 | 什么时候用 |
|---|---|---|
| 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 | 生成签名资产中心链接 | 用户只想浏览形象或音色 |
06 · Digital Human
数字人视频
数字人视频是「方案 → 确认 → 生产」的两阶段流程，避免一次性生成一条方向错误的成片。
| 模式 | 适合内容 | 目标时长 | 素材要求 |
|---|---|---|---|
| studio 常规 | 科普、讲解、产品介绍 | 30–150 秒 | 形象 + 音色 |
| continuous 一镜到底 | 单人口播、观点输出 | 20–60 秒 | 形象 + 音色；生成时间更长 |
| mv 音乐 MV | 歌曲、翻唱、品牌主题曲 | 跟随歌曲 | 1–2 个形象 + 歌曲 |
| ecommerce 电商带货 | 单品卖点、活动促销 | 20–80 秒 | 形象 + 音色 + 商品图（+场景图） |
| store_visit 探店宣传 | 门店、本地生活、文旅 | 20–80 秒 | 形象 + 音色 + 1–3 张场景图 |
创建方案
调用 kiikii_create_video 只产出分镜与台词，不生成视频；信息不足时会先追问模式、形象、音色或素材。
展示并等待确认
AI 必须把方案、时长与预估积分展示给你，等你明确回复「确认 / 开始生成」后才调用 kiikii_confirm_video。
修改方案
确认前说「场景 2 改成文生视频」「第 3 段台词更口语」，使用 kiikii_revise_video_plan 在原任务上改，不新建任务。
生产与查结果
确认后异步生产，用 kiikii_get_job 查询阶段与成片；失败分段可单独重跑。
数字人视频提示词示例
用我的形象「知雅」和 45 岁温柔女声，做一条 45 秒知识讲解： 主题是菊花与中国重阳节，开场点题，中间讲品种、花语与习俗， 结尾给一句养护小知识。9:16 竖屏，720p，烧录字幕。 （方案出来后）把场景 2 改成文生视频分镜，画面是雨后的菊花特写； 场景 3 改成 Web 动画，用时间轴讲重阳节习俗。
一镜到底生成时间明显更长；MV 只支持 480p / 720p；用户没有明确要求时不要主动选 1080p。修改形象、音色、画幅、清晰度属于项目设置，需要到工作台调整。
07 · Creation
通用创作：图片、视频与配音
不需要数字人出镜的素材，用通用创作工具直接生成；一次配置、异步返回 jobId。
图片
- 一次最多 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 复刻音色。
可直接复制的创作指令
生成一张 16:9 的咖啡品牌海报，暖色调，产品居中，留出标题空间， 用 nano-banana-2，4K。 生成一条 5 秒文生视频：雨夜霓虹街头，镜头缓慢推进，电影质感，16:9。 把这段文案配成 45 岁温柔女声，语速稍慢：「秋天第一杯茶，从一盏菊花开始。」
通用创作与数字人共用模型路由、并发与积分规则；模型不支持某个比例或分辨率时，服务端会收敛到支持范围，不会静默失败。
08 · Jobs & Credits
任务、轮询与积分
所有生成都是异步任务：创建后马上返回 jobId，结果通过查询工具获取。
| 任务类型 | 创建工具 | 查询工具 | 结果内容 |
|---|---|---|---|
| 数字人形象 | 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，避免重复建项目。
积分规则与网页端一致：图片按张、视频按时长与分辨率、配音按文本长度计费。具体单价见「模型能力与积分」页面。
09 · Tips
使用技巧
把需求写清楚、把修改说具体，MCP 的产出会稳定很多。
先问模式，再写需求
不确定用哪种模式时，先说内容目标和时长，让 AI 返回推荐；不要一上来就指定「一镜到底」。
一次只改一件事
改分镜时说明「第几段 + 改成什么」，一次最多改 3 段；不要在同一句话里同时换形象、音色和画面。
分镜类型可以换
常规模式默认会混排 Web 动画、图文等。想要实拍感空镜，就说「把场景 2 改为文生视频」；要人物长段落讲述，就说「场景 3 改为数字人长镜头」。
素材先上传再引用
对话里不能直接替换素材。先上传拿到 assetToken，再让 AI 引用；网页端可以在资产中心上传后重新规划。
音色用描述而不是猜 ID
直接说「45 岁女性、温柔知性」，比让 AI 随便挑一个音色更准；服务端会返回匹配结果与说明。
成片后的修改分开说
改字幕样式用字幕重烧；改画面或台词需要改分镜；只想重新拼接成片就说「重新合成成片」，不会重做分段。
如果 AI 回复「需要更具体」，直接补充段落号、目标类型或参考素材即可；它在信息不足时追问，比直接生成一条错误成片更省积分。
10 · FAQ
常见问题
第一次接入最容易遇到的几个问题。
MCP 和 WorkBuddy 连接器有什么区别？
两者连接的是同一套 kiikii 能力。WorkBuddy 通过 OAuth 安装连接器，不需要 API 密钥；Cursor、Claude Desktop、Trae 等客户端使用个人 API 密钥接入 MCP。密钥与连接器可以同时使用，互不影响。
为什么我在 MCP 里生成图片只有 1K？
当前只有 nano-banana-2 支持 2K / 4K，其余图片模型固定按 1K 提交。需要高清晰度时，先调用 kiikii_list_creation_models 确认模型，再在 kiikii_generate_image 里传 resolution：1K / 2K / 4K。
为什么让 AI 改方案，它却新建了一条视频？
数字人视频是两阶段流程：kiikii_create_video 只产出方案，确认后才生产。已有待确认方案时，应调用 kiikii_revise_video_plan 在原任务上修改，而不是再次创建。工具本身也会用 needsRevision 拦截重复建任务。
生成任务一直显示处理中怎么办？
图片、视频、配音都是异步任务。创建后拿到 jobId，每 10–20 秒查询一次即可；不要连续高频轮询。任务超时不会重复扣费，查询时以实际扣费字段为准。
API 密钥丢了还能找回吗？
不能。完整的密钥只在创建成功时显示一次，服务端只保存哈希。请在创建弹窗里立即复制，或使用「复制 MCP 配置」保存完整配置；丢失后撤销旧密钥并重新创建。
一个账号可以创建几个密钥？
最多 10 个有效密钥，每个密钥对应一份独立的 MCP 配置，适合不同客户端或不同同事分开使用。撤销后立即失效，不影响其他密钥。
在 MCP 里上传素材和网页端有什么不同？
MCP 需要先调用 kiikii_create_upload_ticket 获取上传地址，把文件字节 PUT 上去，再调用 kiikii_complete_upload 换取 assetToken。后续工具只接受 assetToken，不能直接传本地文件路径。
MCP 生成的视频会计费吗？
会，与网页端使用同一套积分规则，从当前账号余额扣除；失败任务按站内规则退款。每次生成前可以先调用 kiikii_get_account 查看余额。
11 · Get Started
现在开始：三步接入
准备一个密钥、粘贴一份配置、问一句余额，就能开始。
创建密钥
打开个人中心 → API 密钥，创建后立即复制完整 MCP 配置。
粘贴到客户端
Cursor、Claude Desktop 或 Trae 的 MCP 配置里合并 mcpServers，重启客户端。
验证并创作
先问「查询我的 kiikii 积分余额」，再说「用我的形象做一条 45 秒知识讲解」。