PalmAI Developer Quick-Start Guide

This document is intended for individual developers / side projects / proof-of-concept scenarios. It walks you through the entire process of onboarding to Tencent Palm Recognition (PalmAI) Community Edition at zero cost — from account registration and key generation to building applications using Personal Skill / MCP and API.

Applicable version: PalmAI Community Edition (Open-Source)

Official documentation site: https://api-docs.intl.palm.tencent.com/

Developer console: https://palm.tencent.com/developer

API credential management: https://palm.tencent.com/developer/api-keys

API endpoint domain: https://open.intl.palm.tencent.com

1. Capabilities Overview

PalmAI Community Edition provides the following capabilities free of charge to individual developers:

Type	Capability	Description
Core API	`RegisterRgbPalm`	Register an RGB palm print (bound to a specified user)
	`CompareRgbPalm`	1:1 RGB palm print comparison
	`SearchRgbPalm`	1:N RGB palm print search
	`DeletePalm`	Delete palm prints by direction or deregister all palm prints
MCP	Palm KYC Community MCP Server	Enables AI Agents to invoke the above capabilities via natural-language conversation
Skill	Palm-KYC-Community Personal Skill	Provides "dangerous-operation palm interception" and "palm registration" in AI coding assistants

Usage boundary: The Community Edition is limited to individual developers for non-commercial purposes and must not be used in production environments. For enterprise-grade RBAC, dual-modality (palm print + palm vein), databases at the tens-of-millions scale, and higher concurrency, please contact the sales team to purchase PalmAI Enterprise Edition.

2. Registration & Key Generation

Step 1 — Register a Developer Account

Open the PalmAI developer center: https://palm.tencent.com/developer
Register with your email and complete account activation.
After logging in, navigate to Developer → API Credentials: https://palm.tencent.com/developer/api-keys

Step 2 — Create Credentials

PalmAI provides two types of keys, each targeting a different development scenario. We recommend creating both:

Credential Type	Prefix	Use Case
API Key	`ak_`	Developers directly calling API endpoints to build applications (backend services, scripts, custom clients)
User Token	`ut_`	Personal user Skill / MCP authentication scenarios (AI coding assistants in IDEs, conversational Agents)

💡 Only one of each type can be created. Once both are created, the "Create new credential" button becomes disabled (standard button + 50% opacity) and displays All credential types have been created.

Operation Flow

Click + Create new credential in the top-right corner.
In the pop-up, select the credential type to create (each option has an English description below it):
- API Key: Used for scenarios where developers directly call API interfaces to build applications.
- User Token: Used for personal user skill authentication scenarios.
Click Create — the system returns the full Key/Token string.

⚠️ Important: The key is displayed in full only once, at creation time. Copy and save it to a secure location immediately (e.g., 1Password, system Keychain, .env file).

Never commit keys to Git. Never expose them in front-end code, browsers, or public repositories.

3. Path A: Develop with the "Personal Skill"

Use case: Integrating palm verification into an AI coding assistant / IDE, so that the AI automatically triggers a "palm second-factor verification" before executing high-risk operations, or lets users complete "palm registration" directly in the conversation.

1. System Requirements

Item	Requirement
Operating system	macOS / Linux / Windows
Python	Python 3
Browser	Google Chrome (must be installed; set `CHROME_BIN` environment variable if not at the default path)
Camera	The device must have an accessible camera with Chrome permission
Network	Must be able to reach `open.intl.palm.tencent.com`
Runtime	Local physical terminal (not supported in sandboxes / containers / restricted remote environments)

2. Install & Configure Skill Credentials

You need 2 credentials:

Field	Description	How to Obtain
`userid`	Current user ID (used for 1:1 comparison)	Log in to the developer console → Profile page
`token`	API authentication JWT	Create a User Token on the API Credentials page

Just say the following to your AI assistant (credentials are stored preferentially in the system Keychain; if unavailable, they fall back to a local encrypted file — they are never written to shell history):

"Help me configure palm-kyc-community credentials — userid is xxx, token is ut_xxx"

3. Two Usage Modes

① Palm Recognition (Dangerous Operation Interception) — AI-Triggered

When the AI detects a genuine operation intent matching any of the following categories in your conversation, it automatically opens a standalone Chrome pop-up window and requires you to perform palm verification as a second confirmation:

Category	Typical Scenarios
Data deletion / clearing	Delete data, truncate tables, `drop`, `truncate`, `rm -rf`, batch delete
Irreversible changes	Rollback, force overwrite, `force push`, `reset --hard`
Permissions / accounts	Privilege escalation, grant/revoke, disable accounts, delete users, reset passwords
Funds / payments	Transfer, pay, refund, withdraw, deduct, settle
Production environment	Deploy to production, release, restart services, shut down, `kill`, `shutdown`
Sensitive data export	Full export, `dump`, database backup

Execution result:

✅ Passed: Continue with the original operation.
❌ Failed: The original operation is forcibly terminated (no bypass, no retry).
⚠️ Timeout / Error: Prompt the user to retry.

Triggered only when the user expresses a genuine operation intent. Examples, discussions, and queries do not trigger it.

② Palm Registration (Palm Print Enrollment) — User-Triggered

Say any of the following keywords in the conversation:

"Register palm" / "Palm registration" / "I want to enroll my palm" / "Start registration" / "Enroll palm print" / "I want to register my palm"

The AI opens a standalone Chrome pop-up window. Follow the on-screen instructions to complete enrollment; a PalmId is returned as the unique credential for subsequent recognition.

4. Quick Reference

Need	How to Trigger
Configure credentials	"Help me configure palm-kyc-community userid and token"
Check credential status	"Check if palm-kyc-community credentials are configured"
Clear credentials	"Clear palm-kyc-community credentials"
Initiate palm recognition	Describe a dangerous operation to the AI — it triggers automatically
Initiate palm registration	Say "I want to register my palm" to the AI

5. Troubleshooting

Issue	Resolution
Credentials missing	"Help me reconfigure palm-kyc-community credentials"
Credentials expired	Re-apply for a User Token, then say "palm-kyc-community token expired, help me update it"
Chrome not found	Install Chrome or set `CHROME_BIN` to point to the executable
Recognition timeout	Retry
Repeated recognition failures	Check camera permissions and lighting; re-enroll palm print if necessary

4. Path B: Use "MCP" to Let an Agent Call PalmAI

Use case: You are building an AI Agent / conversational product and want users to complete the full lifecycle of palm registration, deregistration, 1:1 verification, and 1:N search using natural language — upgrading the traditional GUI to "conversation-as-a-service."

1. Protocol & Endpoint

Protocol: Model Context Protocol (MCP)
Type: streamable-http
Endpoint: https://open.intl.palm.tencent.com/palm/mcp
Authentication: Bearer Token (use User Token, prefix ut_)

2. Configure `mcp.json`

Add the following to your Agent framework's mcp.json (Claude Desktop / Codebuddy / custom Agent, etc.):

{
  "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_YOUR_ACTUAL_TOKEN_FROM_THE_PORTAL"
      },
      "timeout": 60
    }
  }
}

3. Available Tools

The MCP Server exposes 4 tools, corresponding 1-to-1 with the API:

Tool	Function	Key Input	Return
`RegisterRgbPalm`	Register RGB palm print	`RgbImage`, `UserId`, `IsForce?`	`PalmId`
`CompareRgbPalm`	1:1 comparison	`RgbImage`, `CompareUserId`	`IsMatch`, `Score`, `PalmDirection`
`SearchRgbPalm`	1:N search	`RgbImage`	`UserId`, `Score`, `PalmDirection`
`DeletePalm`	Delete palm print	`UserId`, `PalmDirectionList` (`[]` = delete all)	—

In MCP mode, RgbImage.Data accepts the object path of the image; ImageType is fixed at 1 (RGB).

4. Conversation Examples

User: Register this palm image to user001.
Agent: [Calls RegisterRgbPalm] → Registration successful, PalmId = 8db884f9-…

User: Compare this image against user001.
Agent: [Calls CompareRgbPalm] → Match, Score 95, left palm.

User: Search the entire database for this palm.
Agent: [Calls SearchRgbPalm] → Matched user001, Score 92.

User: Delete all palm prints (left and right) for user001.
Agent: [Calls DeletePalm, PalmDirectionList=[1,2]] → Deletion successful.

5. Path C: Develop Directly with the "API"

Use case: Building backend services, mobile apps, or web applications that directly call PalmAI HTTP endpoints in your own service.

1. Authentication

Auth type: HTTP Bearer Auth
Request header: Authorization: Bearer <API Key> (use API Key, prefix ak_)
Default rate limit: 20 requests/second/AppId

2. Base Domain & Request Format

Item	Value
API domain	`open.intl.palm.tencent.com`
HTTP method	`POST /`
Content-Type	`application/json; charset=utf-8`

3. Common Data Structures

Image

Field	Type	Description
`Data`	String	Image data, Base64-encoded
`ThreePointList`	Array<Pointf>	Three-point coordinates (output from detection & alignment, optional)
`ImageType`	Integer	`1` = RGB / `2` = IR
`DataDigest`	String	MD5 of image data (optional)

PalmDirectionType (Palm Direction)

Enum	Description
`1`	Left hand
`2`	Right hand

4. API List

API	Path / Identifier	Rate Limit
Register RGB Palm Print	`RegisterRgbPalm`	20 req/s
Compare RGB Palm Print	`CompareRgbPalm`	20 req/s
Search RGB Palm Print	`SearchRgbPalm`	20 req/s
Delete Palm Print	`DeletePalm`	20 req/s

4.1 RegisterRgbPalm — Register RGB Palm Print

Input

Parameter	Required	Type	Description
`UserId`	Yes	String	Unique user identifier
`RgbImage`	Yes	Image	RGB image; `Data` + `ImageType` are required
`IsForce`	No	Boolean	Whether to force re-binding

Example

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 image data", "ImageType": 1 },
  "IsForce": false
}

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

If the UserId already has a bound palm print, the system automatically updates the data and returns the original PalmId.

4.2 CompareRgbPalm — Compare RGB Palm Print (1:1)

Input

Parameter	Required	Type	Description
`RgbImage`	Yes	Image	RGB image
`CompareUserId`	Yes	String	User ID to compare against

Output: IsMatch (Boolean), Score (0–100), AlgorithmVersion, PalmDirection

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

4.3 SearchRgbPalm — Search RGB Palm Print (1:N)

Input: RgbImage only

Output: UserId, Score, AlgorithmVersion, PalmDirection

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

4.4 DeletePalm — Delete Palm Print

Input

Parameter	Required	Type	Description
`UserId`	Yes	String	User ID
`PalmDirectionList`	Yes	Array<PalmDirectionType>	List of directions to delete; both left and right can be passed simultaneously

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

5. Error Codes

A non-zero code in the response indicates a failed call; message provides the error description. Common error codes:

Error Code	Description
1000000	Parameter error (invalid format / type)
1000002	Missing required parameter
1001003	Image MD5 mismatch
1001004	Liveness detection failed
1001005	Quality check failed
1001007	PalmId does not exist — please re-enroll
1001011	Third-party authentication failed (Token incorrect / expired)
1001012	No data found in the database
1001013	1:N search — no matching user in the hot database
1001020	PalmId already exists
1001021	Highly similar palm print exists
1001027	Palm print already exists
1001029	Palm feature quota exceeded

For the complete list of error codes, see the official API documentation.

6. Minimal Runnable Example (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);

6. Which Integration Path Should I Choose?

Your Goal	Recommended Path	Credential
Add palm second-factor verification for high-risk operations in an IDE / AI coding assistant	Path A (Skill)	User Token (`ut_`)
Build a conversational Agent where users manage palm prints via natural language	Path B (MCP)	User Token (`ut_`)
Directly call HTTP endpoints from a custom backend / App / Web service	Path C (API)	API Key (`ak_`)

7. Security & Best Practices

API Key / User Token is displayed in full only once at creation. Store it securely — we recommend environment variables, Keychain, or a Secrets Manager.
Never embed keys in front-end code, browsers, public repositories, or client apps.
In external SDK packages, inject keys via environment variables; do not hard-code them.
Only one credential of each type can be created. If a key is compromised, go to API Credentials to delete it immediately and regenerate.
The Community Edition is for non-commercial use and proof-of-concept only. For production deployment, contact sales to purchase the Enterprise Edition.

8. More Resources

📘 Official Documentation

Document	Link
Community Edition — Introduction	https://api-docs.intl.palm.tencent.com/open-community-api/introduction
Community Edition — API Overview	https://api-docs.intl.palm.tencent.com/open-community-api/overview
Community Edition — Data Structures	https://api-docs.intl.palm.tencent.com/open-community-api/data-structures
Community Edition — Error Codes	https://api-docs.intl.palm.tencent.com/open-community-api/error-codes
`RegisterRgbPalm` — Register RGB Palm Print	https://api-docs.intl.palm.tencent.com/open-community-api/palm-management/register-rgb-palm
`CompareRgbPalm` — Compare RGB Palm Print	https://api-docs.intl.palm.tencent.com/open-community-api/palm-management/compare-rgb-palm
`SearchRgbPalm` — Search RGB Palm Print	https://api-docs.intl.palm.tencent.com/open-community-api/palm-management/search-rgb-palm
`DeletePalm` — Delete Palm Print	https://api-docs.intl.palm.tencent.com/open-community-api/palm-management/delete-palm
MCP — Introduction	https://api-docs.intl.palm.tencent.com/mcp/introduction
MCP — Features	https://api-docs.intl.palm.tencent.com/mcp/features
MCP — Integration Guide	https://api-docs.intl.palm.tencent.com/mcp/integration
MCP — Tools	https://api-docs.intl.palm.tencent.com/mcp/tools
Skill — Introduction	https://api-docs.intl.palm.tencent.com/skills/introduction
Skill — Features	https://api-docs.intl.palm.tencent.com/skills/features
Skill — Usage Steps	https://api-docs.intl.palm.tencent.com/skills/usage
Skill — System Requirements	https://api-docs.intl.palm.tencent.com/skills/requirements
Skill — Notes	https://api-docs.intl.palm.tencent.com/skills/notes

🔗 Platform Entry Points

Developer console: https://palm.tencent.com/developer
API credential management (create API Key / User Token): https://palm.tencent.com/developer/api-keys
API request domain: open.intl.palm.tencent.com
MCP specification: https://modelcontextprotocol.io/

For Enterprise Edition, dual-modality recognition, databases at the tens-of-millions scale, or enterprise-grade RBAC, please contact our sales team via Talk to our expert on the official website.

Join Our Developer Community

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

👉 https://discord.gg/Gp23ytYk

PalmAI Developer Quick-Start Guide

PalmAI Developer Quick-Start Guide

1. Capabilities Overview

2. Registration & Key Generation

Step 1 — Register a Developer Account

Step 2 — Create Credentials

Operation Flow

3. Path A: Develop with the "Personal Skill"

1. System Requirements

2. Install & Configure Skill Credentials

3. Two Usage Modes

① Palm Recognition (Dangerous Operation Interception) — AI-Triggered

② Palm Registration (Palm Print Enrollment) — User-Triggered

4. Quick Reference

5. Troubleshooting

4. Path B: Use "MCP" to Let an Agent Call PalmAI

1. Protocol & Endpoint

2. Configure mcp.json

3. Available Tools

4. Conversation Examples

5. Path C: Develop Directly with the "API"

1. Authentication

2. Base Domain & Request Format

3. Common Data Structures

Image

PalmDirectionType (Palm Direction)

4. API List

4.1 RegisterRgbPalm — Register RGB Palm Print

4.2 CompareRgbPalm — Compare RGB Palm Print (1:1)

4.3 SearchRgbPalm — Search RGB Palm Print (1:N)

4.4 DeletePalm — Delete Palm Print

5. Error Codes

6. Minimal Runnable Example (Node.js)

6. Which Integration Path Should I Choose?

7. Security & Best Practices

8. More Resources

📘 Official Documentation

🔗 Platform Entry Points

Join Our Developer Community

2. Configure `mcp.json`