PalmAI 开发者快速开始指引

本文档面向 个人开发者 / Side Project / 原型验证 场景，介绍如何零成本接入腾讯刷掌（PalmAI）开源社区版（Community Edition），完成从注册账号、生成密钥，到使用 个人 Skill / MCP 与 API 开发应用的全部流程。

适用版本：PalmAI Community Edition（开源社区版）

官方文档站：https://api-docs.intl.palm.tencent.com/

开发者控制台：https://palm.tencent.com/developer

API 凭证管理：https://palm.tencent.com/developer/api-keys

API 接口域名：https://open.intl.palm.tencent.com

一、能力一览

PalmAI 开源社区版面向个人开发者免费提供以下能力：

类型	能力	说明
核心 API	`RegisterRgbPalm`	注册 RGB 掌纹（绑定到指定用户）
	`CompareRgbPalm`	1:1 RGB 掌纹比对
	`SearchRgbPalm`	1:N RGB 掌纹检索
	`DeletePalm`	按手掌方向精细化删除 / 全量注销掌纹
MCP	Palm KYC Community MCP Server	AI Agent 用自然语言对话方式直接调用上述能力
Skill	Palm-KYC-Community 个人 Skill	在 AI 编码助手中提供「危险操作刷掌拦截」与「刷掌注册」

使用边界：开源社区版仅限个人开发者非商业用途，不可用于生产环境。如需企业级 RBAC、双模态（掌纹+掌静脉）、千万级数据库、更高并发，请联系销售团队购买 PalmAI 企业版。

二、注册与密钥生成

步骤 1 - 注册开发者账号

打开 PalmAI 官网开发者中心：https://palm.tencent.com/developer
使用邮箱注册并完成账号激活。
登录后进入 Developer → API Credentials 页面：https://palm.tencent.com/developer/api-keys

步骤 2 - 创建凭证

PalmAI 提供两种密钥，面向不同的开发场景，建议两种都创建：

凭证类型	前缀	使用场景
API Key	`ak_`	开发者直接调用 API 接口构建应用（后端服务、脚本、自研客户端）
User Token	`ut_`	个人用户 Skill / MCP 鉴权场景（IDE 内 AI 编码助手、对话式 Agent）

💡 每种类型只能创建一份。两种都创建后，"Create new credential" 按钮会变为不可点击状态（标准按钮 + 透明度 50%），并提示 All credential types have been created。

操作流程

点击右上角 + Create new credential。
在弹窗中选择要创建的凭证类型（每个选项下方有英文使用说明）：
- API Key：Used for scenarios where developers directly call API interfaces to build applications.
- User Token：Used for personal user skill authentication scenarios.
点击 Create，系统返回完整的 Key/Token 字符串。

⚠️ 重要：密钥仅在创建时完整显示一次，请立即复制保存到安全位置（如 1Password、系统 Keychain、.env 文件）。

切勿将密钥提交到 Git，切勿在前端 / 浏览器 / 公开仓库中暴露。

三、路线 A：使用「个人 Skill」开发

适用场景：在 AI 编码助手 / IDE 中接入掌纹核验，让 AI 在执行高危操作前自动触发「刷掌二次核验」，或让用户在对话中直接完成「刷掌注册」。

1. 系统要求

项目	要求
操作系统	macOS / Linux / Windows
Python	Python 3
浏览器	Google Chrome（必须安装；非默认路径需配置环境变量 `CHROME_BIN`）
摄像头	设备需具备可用摄像头并允许 Chrome 访问
网络	可访问 `open.intl.palm.tencent.com`
运行环境	本地真实终端（不支持沙箱 / 容器 / 远程受限环境）

2. 安装与配置 Skill 凭证

需要 2 个凭证：

字段	说明	获取方式
`userid`	当前用户 ID（用于 1:1 比对）	登录开发者控制台 → 个人信息页
`token`	接口鉴权 JWT	在 API Credentials 页面创建 User Token

直接对 AI 助手说一句即可（凭证会优先存入系统 Keychain，不可用时降级到本地加密文件，不会写入 shell history）：

「帮我配置 palm-kyc-community 的凭证，userid 是 xxx，token 是 ut_xxx」

3. 两种使用方式

① 刷掌识别（危险操作拦截）—— AI 主动触发

当 AI 在你的对话中检测到以下 真实操作意图 时，会自动弹出独立 Chrome 小窗，要求你刷掌二次确认：

类别	典型场景
数据删除 / 清空	删除数据、清空表、`drop`、`truncate`、`rm -rf`、批量删除
不可逆变更	回滚、强制覆盖、`force push`、`reset --hard`
权限 / 账号	提权、授权、吊销、禁用账号、删除用户、重置密码
资金 / 支付	转账、付款、退款、提现、扣款、结算
生产环境	上线、发布生产、重启服务、停服、`kill`、`shutdown`
敏感数据导出	导出全量、`dump`、备份数据库

执行结果：

✅ 通过：继续执行原操作。
❌ 失败：原操作被强制终止（不得绕过、不得重试）。
⚠️ 超时 / 异常：提示用户重新发起。

仅在用户表达真实操作意图时触发；举例、讨论、查询等场景不会触发。

② 刷掌注册（掌纹录入）—— 用户主动触发

在对话中说出以下任一关键词即可：

「录掌」 / 「注册刷掌」 / 「我要录入手掌」 / 「开始注册」 / 「录入掌纹」 / 「我要刷掌注册」

AI 弹出独立 Chrome 小窗，按指引完成录入后返回 PalmId，作为后续识别的唯一凭据。

4. 快速参考

需求	如何触发
配置凭证	「帮我配置 palm-kyc-community 的 userid 和 token」
查看凭证状态	「看下 palm-kyc-community 凭证有没有配好」
清空凭证	「清空 palm-kyc-community 的凭证」
发起刷掌识别	向 AI 描述一项危险操作，AI 自动触发
发起刷掌注册	向 AI 说「我要录掌」

5. 异常排查

异常	处理
凭证缺失	「帮我重新配置 palm-kyc-community 凭证」
凭证失效 / 过期	重新申请 User Token，然后说「palm-kyc-community 的 token 过期了，帮我更新」
Chrome 未找到	安装 Chrome 或设置 `CHROME_BIN` 指向可执行文件
识别超时	重新发起
反复识别失败	检查摄像头权限、光照；必要时重新录入掌纹

四、路线 B：使用「MCP」让 Agent 调用 PalmAI

适用场景：你正在构建一个 AI Agent / 对话产品，希望用户用 自然语言 即可完成掌纹注册、注销、1:1 核验、1:N 检索等全链路操作，把传统 GUI 升维为「对话即服务」。

1. 协议与端点

协议：Model Context Protocol (MCP)
类型：streamable-http
端点：https://open.intl.palm.tencent.com/palm/mcp
鉴权：Bearer Token（使用 User Token，前缀 ut_）

2. 配置 `mcp.json`

在你的 Agent 框架（Claude Desktop / Codebuddy / 自研 Agent 等）的 mcp.json 中加入：

{
  "mcpServers": {
    "palm-kyc-community-mcp-server": {
      "isActive": true,
      "name": "palm-kyc-community-mcp-server",
      "type": "streamable-http",
      "url": "https://open.intl.palm.tencent.com/palm/mcp",
      "headers": {
        "X-MCP-Namespace": "palm-kyc-community",
        "Authorization": "Bearer ut_你在官网申请到的真实 Token"
      },
      "timeout": 60
    }
  }
}

3. 可用工具（Tools）

MCP Server 暴露 4 个工具，与 API 一一对应：

工具	功能	关键入参	返回
`RegisterRgbPalm`	注册 RGB 掌纹	`RgbImage`, `UserId`, `IsForce?`	`PalmId`
`CompareRgbPalm`	1:1 比对	`RgbImage`, `CompareUserId`	`IsMatch`, `Score`, `PalmDirection`
`SearchRgbPalm`	1:N 检索	`RgbImage`	`UserId`, `Score`, `PalmDirection`
`DeletePalm`	删除掌纹	`UserId`, `PalmDirectionList`（`[]` 表示删除全部）	—

RgbImage.Data 在 MCP 模式下传入 图片对应的对象 Path；ImageType 固定填 1（RGB）。

4. 对话样例

用户：帮我把当前这张手掌图片注册给 user001。
Agent：[调用 RegisterRgbPalm] → 注册成功，PalmId = 8db884f9-…

用户：把这张图和 user001 比对一下。
Agent：[调用 CompareRgbPalm] → 匹配，Score 95，左手掌。

用户：从全库找一下这张手掌是谁。
Agent：[调用 SearchRgbPalm] → 命中 user001，Score 92。

用户：把 user001 的左右手掌纹全部删掉。
Agent：[调用 DeletePalm，PalmDirectionList=[1,2]] → 删除成功。

五、路线 C：直接使用「API」开发

适用场景：开发后端服务、移动 App、Web 应用，需要在自有服务中直接调用 PalmAI HTTP 接口。

1. 鉴权方式

鉴权类型：HTTP Bearer Auth
请求头：Authorization: Bearer <API Key>（使用 API Key，前缀 ak_）
默认频率限制：20 次/秒/AppId

2. 公共域名与请求格式

项目	值
接口域名	`open.intl.palm.tencent.com`
请求方式	`POST /`
Content-Type	`application/json; charset=utf-8`

3. 公共数据结构

Image

字段	类型	说明
`Data`	String	图片数据，Base64 编码
`ThreePointList`	Array<Pointf>	三点（检测配准后输出，可选）
`ImageType`	Integer	`1`=RGB / `2`=IR
`DataDigest`	String	图片数据 MD5（可选）

PalmDirectionType（手掌方向）

枚举	说明
`1`	左手
`2`	右手

4. 接口列表

接口	路径 / 标识	频率
注册 RGB 掌纹	`RegisterRgbPalm`	20 次/秒
比对 RGB 掌纹	`CompareRgbPalm`	20 次/秒
检索 RGB 掌纹	`SearchRgbPalm`	20 次/秒
删除掌纹	`DeletePalm`	20 次/秒

4.1 RegisterRgbPalm 注册 RGB 掌纹

输入

参数	必选	类型	说明
`UserId`	是	String	用户唯一标识
`RgbImage`	是	Image	RGB 图片，`Data` + `ImageType` 必填
`IsForce`	否	Boolean	是否强制换绑

示例

POST / HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
Authorization: Bearer ak_*********************************

{
  "UserId": "user001",
  "RgbImage": { "Data": "base64 图片数据", "ImageType": 1 },
  "IsForce": false
}

{
  "code": 0,
  "message": "ok",
  "requestId": "4d5912a82af144f8a982c2da031c1035",
  "data": { "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47" }
}

若该 UserId 已绑定掌纹，系统自动更新数据并返回原 PalmId。

4.2 CompareRgbPalm 比对 RGB 掌纹（1:1）

输入

参数	必选	类型	说明
`RgbImage`	是	Image	RGB 图片
`CompareUserId`	是	String	待对比的用户 ID

输出：IsMatch（Boolean）、Score（百分制）、AlgorithmVersion、PalmDirection

{
  "code": 0,
  "data": {
    "IsMatch": true,
    "Score": 95,
    "AlgorithmVersion": "v2.0",
    "PalmDirection": 1
  }
}

4.3 SearchRgbPalm 检索 RGB 掌纹（1:N）

输入：仅 RgbImage

输出：UserId、Score、AlgorithmVersion、PalmDirection

{
  "code": 0,
  "data": {
    "UserId": "user001",
    "Score": 92,
    "AlgorithmVersion": "v2.0",
    "PalmDirection": 1
  }
}

4.4 DeletePalm 删除掌纹

输入

参数	必选	类型	说明
`UserId`	是	String	用户 ID
`PalmDirectionList`	是	Array<PalmDirectionType>	要删除的方向列表，可同时传左右手

{ "UserId": "user001", "PalmDirectionList": [1, 2] }

5. 错误码

返回结果中，code 非 0 即调用失败，message 为错误描述。常见错误码：

错误码	说明
1000000	参数错误（格式 / 类型不合法）
1000002	缺少必传参数
1001003	图片 MD5 不一致
1001004	活体检测未通过
1001005	质量检测未通过
1001007	PalmId 不存在，请重新录入
1001011	第三方鉴权失败（Token 错误 / 失效）
1001012	数据库中未查询到数据
1001013	1:N 检索热库未匹配到用户
1001020	PalmId 已存在
1001021	存在高相似度的手掌
1001027	掌纹已存在
1001029	掌库特征配额超限

完整错误码请参见官方 API 文档。

6. 最小可运行示例（Node.js）

import fs from 'node:fs/promises';

const API_HOST = 'https://open.intl.palm.tencent.com';
const API_KEY = process.env.PALM_API_KEY; // ak_xxxxxxx

async function registerPalm(userId, imagePath) {
  const buf = await fs.readFile(imagePath);
  const body = {
    UserId: userId,
    RgbImage: { Data: buf.toString('base64'), ImageType: 1 },
    IsForce: false,
  };

  const res = await fetch(`${API_HOST}/`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json; charset=utf-8',
      Authorization: `Bearer ${API_KEY}`,
    },
    body: JSON.stringify(body),
  });

  const json = await res.json();
  if (json.code !== 0) throw new Error(`[${json.code}] ${json.message}`);
  return json.data.PalmId;
}

const palmId = await registerPalm('user001', './palm.jpg');
console.log('Registered PalmId =', palmId);

六、三种接入方式如何选？

你的诉求	推荐方式	凭证
在 IDE / AI 编码助手中给高危操作加掌纹二次核验	路线 A（Skill）	User Token (`ut_`)
构建对话式 Agent，让用户用自然语言完成掌纹管理	路线 B（MCP）	User Token (`ut_`)
自研后端 / App / Web 直接调用接口	路线 C（API）	API Key (`ak_`)

七、安全与最佳实践

API Key / User Token 仅在创建时显示一次，请妥善保管；建议存入环境变量、Keychain、Secrets Manager。
不要把密钥写入前端代码 / 浏览器 / 公开仓库 / 客户端 App 中。
对外 SDK 包请用环境变量注入，不要硬编码。
每种凭证只能创建一份；如果泄露，请进入 API Credentials 立即删除并重新生成。
开源社区版仅限非商业用途与原型验证；上生产请联系销售购买企业版。

八、更多资源

📘 官方文档直达

文档	链接
开源社区版 - 简介	https://api-docs.intl.palm.tencent.com/open-community-api/introduction
开源社区版 - API 概览	https://api-docs.intl.palm.tencent.com/open-community-api/overview
开源社区版 - 数据结构	https://api-docs.intl.palm.tencent.com/open-community-api/data-structures
开源社区版 - 错误码	https://api-docs.intl.palm.tencent.com/open-community-api/error-codes
`RegisterRgbPalm` 注册 RGB 掌纹	https://api-docs.intl.palm.tencent.com/open-community-api/palm-management/register-rgb-palm
`CompareRgbPalm` 比对 RGB 掌纹	https://api-docs.intl.palm.tencent.com/open-community-api/palm-management/compare-rgb-palm
`SearchRgbPalm` 检索 RGB 掌纹	https://api-docs.intl.palm.tencent.com/open-community-api/palm-management/search-rgb-palm
`DeletePalm` 删除掌纹	https://api-docs.intl.palm.tencent.com/open-community-api/palm-management/delete-palm
MCP - 简介	https://api-docs.intl.palm.tencent.com/mcp/introduction
MCP - 功能特点	https://api-docs.intl.palm.tencent.com/mcp/features
MCP - 接入指南	https://api-docs.intl.palm.tencent.com/mcp/integration
MCP - 工具说明	https://api-docs.intl.palm.tencent.com/mcp/tools
Skill - 简介	https://api-docs.intl.palm.tencent.com/skills/introduction
Skill - 功能介绍	https://api-docs.intl.palm.tencent.com/skills/features
Skill - 使用步骤	https://api-docs.intl.palm.tencent.com/skills/usage
Skill - 系统要求	https://api-docs.intl.palm.tencent.com/skills/requirements
Skill - 注意事项	https://api-docs.intl.palm.tencent.com/skills/notes

🔗 平台入口

开发者控制台：https://palm.tencent.com/developer
API 凭证管理（创建 API Key / User Token）：https://palm.tencent.com/developer/api-keys
接口请求域名：open.intl.palm.tencent.com
MCP 协议规范：https://modelcontextprotocol.io/

如需企业版、双模态识别、千万级数据库、企业级 RBAC，请通过官网 Talk to our expert 联系销售团队。

Join Our Developer Community

Join our Discord for dedicated technical support, project discussions, and community updates!

👉 https://discord.gg/Gp23ytYk

PalmAI开发者快速开始指引