Palm Recognition Open API Integration Guide

Audience: backend engineers on the integrating side

This document helps you integrate the backend business APIs and issue SDK user tokens.

1. Quick Start

Integration takes 3 steps:

Apply for an API Key (one-time) — create an application in the Developer Console and generate an api_key.
Call the APIs from your server — call the business APIs over HTTPS with Authorization: Bearer <api_key>.
Handle the business response — check the result using the unified response structure {code, message, requestId, data}.

┌─────────────────┐   HTTPS + Bearer <api_key>   ┌────────────────────────────────┐
│  Your backend   │  ─────────────────────────▶ │ open.intl.palm.tencent.com     │
│  service        │                              │   /palm/openai/*               │
│                 │  ◀───────────────────────── │   (Palm Open Platform gateway) │
└─────────────────┘        JSON response         └────────────────────────────────┘
         │
         │ Server issues on behalf of the end user
         │ CreateSdkUserToken → sdk_user_token (sut_xxx)
         ▼
┌─────────────────┐   HTTPS + Bearer <sdk_user_token> ┌───────────────────────────┐
│  End-user SDK / │  ──────────────────────────────▶ │ open.intl.palm.tencent.com│
│  client (App /  │                                   │   /palm/openai/*          │
│  Mini Program)  │   Can only access this user's data│                           │
└─────────────────┘                                   └───────────────────────────┘

🔐 How the two credentials differ

api_key (ak_ prefix) — server-side only, with the highest privilege: it can access all APIs and all user data. Never distribute it to clients.

sdk_user_token (sut_ prefix) — a restricted credential bound to a single user, issued by your backend for a given UserId via §5.1 CreateSdkUserToken. It can only access that user's own data and has an expiration time. You can use it directly in your own web backend, or distribute it to mobile SDKs / Mini Programs / desktop clients.

2. Applying for a Token (API Key)

2.1 Where to Apply

Apply for an API Key in the Developer Console on the official website:

🔑 https://palm.tencent.com/developer/api-keys

2.2 Application Process

Sign in to the official website with your account.
Go to Developer Center → API Keys.
Click "Create Application", enter an application name, and select the product type (Palm Management).
After the application is created, click "Generate API Key".
Copy and securely store the plaintext api_key (e.g. ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx) immediately — the plaintext is returned only once. Afterwards the console only shows a masked value (e.g. ak_abcd******wxyz). If lost, you must delete it and generate a new one.

2.3 How to Use

Add the following to the HTTP headers of every request:

Authorization: Bearer ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Security Notes

api_key is a server-side credential. It is strictly forbidden to put it in frontend pages / app clients / mobile source code / public repositories. Store it only in server environment variables or a Key Management Service (KMS).

If it is leaked, delete and regenerate it in the console immediately.

Each application can have at most 1 valid api_key. To rotate, create a new key first, then delete the old one.

3. General Conventions

3.1 API Domain

Environment	Domain
Production (International)	`https://open.intl.palm.tencent.com`

All business APIs use HTTPS + POST + JSON.

3.2 URL Prefix

All business API paths start with /palm/openai/ (except CreateSdkUserToken, see §5.1):

POST https://open.intl.palm.tencent.com/palm/openai/<api_name>

3.3 Request Headers (HTTP Headers)

Field	Required	Description
`Content-Type`	Yes	Always `application/json; charset=utf-8`
`Authorization`	Yes	Format `Bearer <credential>`, where `<credential>` is an `api_key` (`ak_` prefix, see §2) or an `sdk_user_token` (`sut_` prefix, see §5.1)
`X-TraceId`	No	32-character lowercase hex string for end-to-end tracing. Generated automatically by the gateway if omitted; we recommend generating and logging it yourself to ease troubleshooting

3.4 Request Body

Always a JSON object.
Field names use PascalCase (upper camel case), e.g. UserId, RgbImage.
The binary image field Data is a Base64-encoded string.

3.5 Common Response Structure

All APIs return the following JSON structure on success:

{
  "code": 0,
  "message": "ok",
  "requestId": "4d5912a82af144f8a982c2da031c1035",
  "data": {}
}

(See each API section for the specific business fields in data.)

Field	Type	Description
`code`	Integer	Business error code. `0` means success; non-zero means failure — see the error code tables in §6
`message`	String	Error description (`"ok"` on success)
`requestId`	String	Unique server-side request ID; please provide it when troubleshooting
`data`	Object	Business data; may be an empty object `{}` on failure

3.6 Rate Limits

Default: 20 requests/second per credential (api_key and sdk_user_token are counted separately).
Exceeding the limit returns HTTP 429. Please control concurrency or contact us to request a higher quota.

4. Common Data Types

The following types are reused across multiple APIs.

4.1 `PalmDirectionType` Enum

Value	Meaning
`1`	LEFT_PALM (left palm)
`2`	RIGHT_PALM (right palm)

4.2 `PalmState` Enum (Palm State)

Value	Constant	Meaning
`1`	`ACTIVATED`	Bound successfully; can be used for comparison / search
`2`	`HIGH_SIMILARITY`	High similarity (at risk of being highly similar to another user; temporarily unavailable)

5. Business APIs

API List

No.	Capability	API Name	Method	Path	Supported Credentials
1	Token authentication	`CreateSdkUserToken`	POST	`/palm/openai/x/oauth/sdk/usertoken/create`	`api_key` only
2	Palm registration query	`GetPalm`	POST	`/palm/openai/get_palm`	`api_key` / `sdk_user_token`
3	1:1 verification	`GetSessionResult`	POST	`/palm/openai/get_session_result`	`api_key` / `sdk_user_token`
4	Palm deletion	`DeletePalm`	POST	`/palm/openai/delete_palm`	`api_key` / `sdk_user_token`

When calling an API with an sdk_user_token, the UserId in the request body must equal the UserId passed when the token was issued (the server treats that UserId as the token's bound user); otherwise 403 is returned.

5.1 Token Authentication (CreateSdkUserToken)

🔗 Note on the path: this API's path is /palm/openai/x/oauth/sdk/usertoken/create, which differs from other business APIs (/palm/openai/<api_name>). Make sure you use the correct path.

Description

Issues a restricted sdk_user_token (JWT, sut_ prefix) for an end user specified by your business. The resulting token can be used directly in your own web backend, or distributed to mobile SDKs / Mini Programs / desktop clients (especially suitable for client-side scenarios where an api_key cannot be stored securely).

An issued sdk_user_token:

Can only access that user's own data: when calling §5.2 / §5.3 / §5.4, the UserId in the request body must equal the UserId passed at issuance; any mismatch returns 403.
Expires: default 30 minutes (1800 seconds), maximum 24 hours (86400 seconds). Passing 0 or omitting TtlSeconds uses the default.
Plaintext is returned only once: have your backend deliver it to the client; do not persist it in untrusted storage.
Is revocable: it becomes invalid once the api_key is revoked or the application is disabled. In abnormal situations, the platform can revoke all issued sdk_user_tokens at once via backend key rotation (you will need to reissue them).

⚠️ This API must be called from your server: it only accepts api_key authentication. Never expose this API (including the api_key) to clients — doing so is equivalent to leaking your api_key.

Default rate limit: 20 requests/second.

Request Parameters

Parameter	Required	Type	Description
`UserId`	Yes	String	End-user identifier defined by your business (your own namespace; Palm does not persist it; same value space as `UserId` in the other business APIs). Length ≤ 64
`TtlSeconds`	No	Integer	Token validity in seconds. `0` or omitted → default `1800` (30 minutes); hard limit `86400` (24 hours). Values above the limit return error code `2090021` directly (no silent truncation)
`Scope`	No	Array<String>	Reserved permission list. Not validated in v1; only written into the JWT. You may pass `[]` or omit it

Response Parameters (`data`)

Parameter	Type	Description
`Token`	String	The issued `sdk_user_token`, e.g. `sut_xxxxxxxxxxxxxxxx` (a JWT internally). The plaintext is returned only this once — save it or deliver it to the corresponding client immediately
`ExpiresAt`	Integer	Token expiration timestamp (Unix seconds, UTC)

Example

Request

POST /palm/openai/x/oauth/sdk/usertoken/create HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
Authorization: Bearer ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "UserId": "user001",
  "TtlSeconds": 1800,
  "Scope": []
}

Response

{
  "code": 0,
  "message": "ok",
  "requestId": "4d5912a82af144f8a982c2da031c1035",
  "data": {
    "Token": "sut_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx.yyy",
    "ExpiresAt": 1783691400
  }
}

cURL

curl -X POST "https://open.intl.palm.tencent.com/palm/openai/x/oauth/sdk/usertoken/create" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "UserId": "user001",
    "TtlSeconds": 1800,
    "Scope": []
  }'

Calling Business APIs with the `sdk_user_token` (applies to web backends / SDKs / Mini Programs)

Once you have an sdk_user_token, call the APIs exactly as you would with an api_key — just replace ak_xxx in the header with sut_xxx:

POST /palm/openai/get_palm HTTP/1.1
Host: open.intl.palm.tencent.com
Content-Type: application/json; charset=utf-8
Authorization: Bearer sut_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxx.yyy

{
  "UserId": "user001"
}

The server automatically decodes the bound UserId from the sdk_user_token (i.e. the UserId in the request body) and performs the following checks:

The sdk_user_token signature is valid and it has not expired.
The UserId in the request body must equal the token's bound UserId; otherwise 403 is returned.
The API being called is on the sdk_user_token allowlist (§5.2 GetPalm / §5.3 GetSessionResult / §5.4 DeletePalm).

✅ Recommended practice (especially for SDK / client scenarios): on every cold start, or when the token's remaining lifetime drops below 20%, the client requests a fresh sdk_user_token from your own backend; your backend calls this API to issue it after verifying the user's login session internally. This way, even if a token is intercepted, only that user is affected and the token expires quickly.

5.2 Palm Registration Query (GetPalm)

Description

Queries the left/right palm information currently registered for the specified user, so your business can display things like "whether palm payment is enabled / when it was registered / whether its state is normal".

Default rate limit: 20 requests/second.
Read-only API; it does not modify any data.
If the user has never registered a palm for a given direction, the corresponding PalmInfo field is omitted or an empty object.

Request Parameters

Parameter	Required	Type	Description
`UserId`	Yes	String	Unique user identifier (same semantics as `UserId` in §5.1)

Response Parameters (`data`)

Top level:

Parameter	Type	Description
`LeftPalm`	PalmInfo	Left palm information
`RightPalm`	PalmInfo	Right palm information

PalmInfo structure:

Parameter	Type	Description
`PalmState`	Integer	Palm state, see §4.2; `1` means bound successfully and available for comparison
`PalmDirection`	PalmDirectionType	Palm direction, see §4.1
`RegisterTime`	Integer	First registration time (Unix seconds, UTC)

Example

Request

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

{
  "UserId": "user001"
}

Response (user has only the left palm enabled)

{
  "code": 0,
  "message": "ok",
  "requestId": "4d5912a82af144f8a982c2da031c1035",
  "data": {
    "LeftPalm": {
      "PalmState": 1,
      "PalmDirection": 1,
      "RegisterTime": 1783600000
    },
    "RightPalm": {
      "PalmState": 0,
      "PalmDirection": 0,
      "RegisterTime": 0
    }
  }
}

cURL

curl -X POST "https://open.intl.palm.tencent.com/palm/openai/get_palm" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "UserId": "user001"
  }'

5.3 Query Recognition Result (GetSessionResult)

Description

Queries the details of the temporary recognition result generated after the client/SDK completes a 1:1 comparison. After the comparison, palm_mgr returns a temporary SessionId (UUID, valid for 2 hours). Your backend uses this SessionId to query the target user ID, palm ID, palm direction, match result, score, and algorithm version of that comparison, so that recognition details are not exposed directly.

Default rate limit: 20 requests/second.
Read-only API; it does not modify any data.
The SessionId is valid for 2 hours. After it expires, start a new comparison to obtain a new SessionId.
No UserId is required in the request; the server looks up the recognition result by SessionId.

Request Parameters

Parameter	Required	Type	Description
`SessionId`	Yes	String	Temporary credential for querying the recognition result, i.e. the `SessionId` from the comparison response

Response Parameters (`data`)

Parameter	Type	Description
`UserId`	String	Target user ID of this recognition
`PalmId`	String	Palm ID involved in the recognition
`PalmDirection`	PalmDirectionType	Palm direction involved in the recognition, see §4.1
`SearchResult`	Object	Recognition result (returned for recognition sessions); structure below
`RegisterResult`	Object	Registration result (returned for registration sessions); currently has no extra fields

SearchResult structure:

Field	Type	Description
`IsMatch`	Boolean	Whether it matched (for 1:1 comparison: whether it is the same person; for 1:N search: whether a user was found)
`Score`	Integer	Recognition score
`AlgorithmVersion`	String	Algorithm version used for this recognition

Example

Request

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

{
  "SessionId": "3f2b1a6d-8c4e-4b7a-9d5f-1e2c3a4b5c6d"
}

Response

{
  "code": 0,
  "message": "ok",
  "requestId": "4d5912a82af144f8a982c2da031c1035",
  "data": {
    "UserId": "user001",
    "PalmId": "8db884f9-1fb8-44f5-bdaa-f98fdcb3cd47",
    "PalmDirection": 1,
    "SearchResult": {
      "IsMatch": true,
      "Score": 92,
      "AlgorithmVersion": "rgb_v3"
    }
  }
}

cURL

curl -X POST "https://open.intl.palm.tencent.com/palm/openai/get_session_result" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "SessionId": "3f2b1a6d-8c4e-4b7a-9d5f-1e2c3a4b5c6d"
  }'

5.4 Palm Deletion (DeletePalm)

Description

Deletes the palm information of the specified user. You can delete the left or right palm individually, or both at once. After deletion, the user's palm for that direction can no longer be matched.

Default rate limit: 20 requests/second.
Deletion is idempotent: deleting a direction that does not exist again will not return an error.

Request Parameters

Parameter	Required	Type	Description
`UserId`	Yes	String	Unique user identifier
`PalmDirectionList`	Yes	Array<PalmDirectionType>	List of palm directions to delete. You can pass both palms, or only the left / only the right. See §4.1

Response Parameters (`data`)

No business fields; data is an empty object {}.

Example

Request (delete both palms)

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

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

Response

{
  "code": 0,
  "message": "ok",
  "requestId": "4d5912a82af144f8a982c2da031c1035",
  "data": {}
}

6. Error Codes

In addition to business error codes, HTTP-level status codes may also be returned. Handle them as follows.

6.1 HTTP Status Codes

HTTP Code	Meaning	Suggested Action
`200`	The request reached the business layer	Parse the `code` field in the body to determine whether it actually succeeded
`401`	Unauthorized	Check whether the `Authorization` header is present, and whether the `api_key` has been deleted or is malformed
`403`	Forbidden	Check whether the application is disabled or the `api_key` has been revoked
`429`	Too many requests	Reduce QPS, or contact us to request a higher quota
`5xx`	Server error	Contact official support with the `requestId`

6.2 Business Error Codes (`code` field)

The code in the response body is the business error code: 0 means success; non-0 means failure. Use the tables below to locate the cause, and troubleshoot together with the message field and requestId.

Error codes are 7-digit decimal numbers in the format XXX YYYY: the first 3 digits are the module number (identifying the error source), and the last 4 digits are the sequence number within the module. PaaS APIs involve the following 4 ranges:

1000xxx Common fallback: parameter validation, internal errors, etc.; may be returned by any API.
2060xxx Credentials / authentication (gateway layer): may be returned by any API during authentication.
2080xxx Palm business (palm_mgr): errors raised by the API's business logic itself.
2090xxx OAuth / SDK credential issuance: may only be returned in the §5.1 CreateSdkUserToken scenario.

6.2.1 Common Error Codes

code	message	Meaning / Troubleshooting
`0`	`ok`	Request succeeded.
`1000000`	`invalid param`	Request parameter validation failed (required field missing / invalid format / length exceeded, etc.). Check against each API's "Request Parameters" table.
`1000001`	`internal error`	Internal server error. Contact official support with the `requestId`.
`1000011`	`database operation failed`	Database operation failed (timeout / connection error, etc.). Retry later; if it persists, report it with the `requestId`.
`1000013`	`forbidden`	No permission for the operation (application disabled / credential revoked, etc.). Check the application status.

6.2.2 Credential and Authentication Error Codes

Returned by the gateway layer during authentication; when an error in this range occurs, the business logic has not been executed yet.

code	message	Meaning / Troubleshooting
`2060000`	`unauthorized`	`Authorization` header missing, or the `api_key`/`sdk_user_token` is invalid or expired. Check the header format in §3.3 and the credential's validity.
`2060002`	`too many requests`	Rate limit triggered. Reduce QPS, or contact us to request a higher quota.
`2060200`	`openapi credential not found`	Credential does not exist. It may have been deleted; check in the console or regenerate it.
`2060201`	`openapi credential of this type already exists`	A credential of the same type already exists (`api_key` is unique per `app_id`; `sdk_user_token` is unique per user). May only occur in the §5.1 `CreateSdkUserToken` scenario; delete the old credential first.
`2060202`	`openapi credential revoked`	Credential has been revoked. Regenerate it in the console.
`2060203`	`openapi credential invalid`	Credential format is invalid or signature verification failed; or a required field for the credential type (e.g. uid for `user_token`, userid/app_id for `sdk_user_token`) is empty. Check that the copied `api_key`/`sdk_user_token` is complete.
`2060204`	`openapi credential type invalid`	Invalid credential type: the `<credential>` in `Authorization: Bearer <credential>` does not start with `ak_` / `ut_` / `sut_` (e.g. a console JWT was mistakenly used as an OpenAPI credential); or in the §5.1 issuance scenario, the requested credential type is not in the `api_key` / `user_token` allowlist.
`2060205`	`openapi credential not allowed for this path`	The scope of the `sdk_user_token` does not cover the current API path. Only occurs with `sut_`-prefixed credentials; check the scope configured at issuance.
`2060207`	`OpenAPI app not configured`	The application for this credential has not been configured on the platform. Contact us to enable it.
`2090021`	`sdk user token ttl exceeds max limit`	The `TtlSeconds` requested in §5.1 `CreateSdkUserToken` exceeds the hard limit (default `86400`, i.e. 24 hours). The platform rejects it directly instead of silently truncating; set `TtlSeconds` within `1~86400` and retry.

6.2.3 Business Error Codes (Palm Business)

Returned by the palm_mgr business layer; see each entry for the related APIs.

code	message	Meaning / Troubleshooting
`2080000`	`no available version`	No available algorithm/palm version. Contact us to confirm that the product version has been enabled for the application.
`2080001`	`unknown image type`	Unknown image type. Make sure `RgbImage.Data` is a valid Base64-encoded JPG/PNG image.
`2080002`	`image MD5 mismatch`	Image MD5 check failed, usually because the data was truncated or tampered with in transit. Retry on the client.
`2080003`	`liveness check failed`	Liveness detection failed. The user may have used a photo/recapture; guide the user to recapture a clear image of a real palm.
`2080004`	`quality check failed`	Image quality check failed (blurry / incomplete palm / poor lighting, etc.). Guide the user to recapture following the SDK prompts.
`2080005`	`liveness video check failed`	Video liveness detection failed (`ActionLiveness` scenario). Guide the user to re-record the action video following the SDK instructions.
`2080006`	`palmId does not exist, please re-record the palm`	`PalmId` has expired or does not exist; the palm needs to be re-recorded.
`2080007`	`already bound`	A palm is already registered for this `UserId + PalmDirection`. If you really need to overwrite it, re-register using forced overwrite.
`2080008`	`palmId may have been bound by someone else`	The retrieved `PalmId` has already been bound by another user, usually in abnormal concurrent scenarios. Contact official support with the `requestId` for verification.
`2080009`	`data not found`	Data does not exist. In the §5.2 `GetPalm` scenario, this means the specified `UserId`/`PalmDirection` has not been registered.
`2080010`	`user not found in search`	1:N search did not match any user in the palm library. This is a normal business result, not a system error.
`2080011`	`table capacity full`	Palm library shard capacity is full. Contact us to expand capacity.
`2080012`	`user's assistant image count exceeds limit`	The user's number of auxiliary images exceeds the limit.
`2080013`	`verification id expired`	Verification ID has expired. Go through the full flow again.
`2080014`	`palm capacity full`	Palm capacity is full (per application). Contact us to expand capacity, or delete historical palms first.
`2080015`	`user has been deleted`	User has been deleted (used only in online palm registration scenarios).
`2080016`	`user does not exist in DB`	User does not exist. Make sure the user has successfully registered a palm before calling comparison/deletion APIs.
`2080017`	`user palm direction does not exist in DB`	No palm exists for the user's specified palm direction. Check the `PalmDirection` parameter or complete registration first.
`2080018`	`concurrent operation in DB, please retry`	Concurrent operation conflict. Retry later on the client; avoid calling registration/deletion APIs in parallel for the same user.
`2080019`	`insertFeatureCurrentSyncIndex already exists`	Feature sync index conflict (internal consistency error). Contact official support with the `requestId` for verification.
`2080020`	`palm capacity quota exceeded`	Palm library feature quota exceeded (insufficient total platform quota). Contact us to request expansion.
`2080021`	`palm mobile (online register) not supported by platform license`	The current platform license does not authorize online palm registration. Contact us to enable it.
`2080022`	`palm capacity cannot be less than current usage`	The quota being set is lower than the current usage.
`2080023`	`app does not exist`	Application does not exist (application-level APIs). Check that the application for this credential has been created correctly.
`2080024`	`compare session expired or not exist`	The comparison result `SessionId` does not exist or has expired (valid for 2 hours). Start a new comparison to obtain a new `SessionId`.

📌 Troubleshooting Tips:

Always keep the requestId: it is returned in every response and is the key clue for us to locate issues.

For any code not listed in these tables or any error you are unsure about, contact official support with the requestId, API name, and request time.

The 1000xxx range consists of common server-side fallback errors. If they occur frequently, first check your request parameters and network conditions; report persistent issues.

7. Integration Example (Go)

The following uses palm registration query (GetPalm) as an example to demonstrate the complete call flow from a Go server. Other APIs are called the same way — just replace the request path and body fields (see §5 for each API's fields).

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

const baseURL = "https://open.intl.palm.tencent.com"

// commonResp is the common response wrapper.
type commonResp struct {
    Code      int             `json:"code"`
    Message   string          `json:"message"`
    RequestID string          `json:"requestId"`
    Data      json.RawMessage `json:"data"`
}

// call sends a POST request and returns the requestId (for troubleshooting).
func call(apiKey, path string, reqBody, out any) (string, error) {
    body, _ := json.Marshal(reqBody)
    req, _ := http.NewRequest("POST", baseURL+path, bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json; charset=utf-8")
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()
    raw, _ := io.ReadAll(resp.Body)

    var wrap commonResp
    if err := json.Unmarshal(raw, &wrap); err != nil {
        return "", fmt.Errorf("decode resp: %w, raw=%s", err, string(raw))
    }
    if wrap.Code != 0 {
        return wrap.RequestID, fmt.Errorf("api error code=%d message=%s requestId=%s", wrap.Code, wrap.Message, wrap.RequestID)
    }
    if out != nil && len(wrap.Data) > 0 {
        if err := json.Unmarshal(wrap.Data, out); err != nil {
            return wrap.RequestID, err
        }
    }
    return wrap.RequestID, nil
}

func main() {
    apiKey := "ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

    reqBody := map[string]any{
        "UserId": "user001",
    }
    var out struct {
        LeftPalm struct {
            PalmState     int   `json:"PalmState"`
            PalmDirection int   `json:"PalmDirection"`
            RegisterTime  int64 `json:"RegisterTime"`
        } `json:"LeftPalm"`
        RightPalm struct {
            PalmState     int   `json:"PalmState"`
            PalmDirection int   `json:"PalmDirection"`
            RegisterTime  int64 `json:"RegisterTime"`
        } `json:"RightPalm"`
    }
    requestID, err := call(apiKey, "/palm/openai/get_palm", reqBody, &out)
    if err != nil {
        fmt.Printf("get palm failed: %v (requestId=%s)\n", err, requestID)
        return
    }
    fmt.Printf("LeftPalm=%+v RightPalm=%+v\n", out.LeftPalm, out.RightPalm)
}

1. Quick Start​

2. Applying for a Token (API Key)​

2.1 Where to Apply​

2.2 Application Process​

2.3 How to Use​

3. General Conventions​

3.1 API Domain​

3.2 URL Prefix​

3.3 Request Headers (HTTP Headers)​

3.4 Request Body​

3.5 Common Response Structure​

3.6 Rate Limits​

4. Common Data Types​

4.1 PalmDirectionType Enum​

4.2 PalmState Enum (Palm State)​

5. Business APIs​

API List​

5.1 Token Authentication (CreateSdkUserToken)​

Description​

Request Parameters​

Response Parameters (data)​

Example​

Calling Business APIs with the sdk_user_token (applies to web backends / SDKs / Mini Programs)​

5.2 Palm Registration Query (GetPalm)​

Description​

Request Parameters​

Response Parameters (data)​

Example​

5.3 Query Recognition Result (GetSessionResult)​

Description​

Request Parameters​

Response Parameters (data)​

Example​

5.4 Palm Deletion (DeletePalm)​

Description​

Request Parameters​

Response Parameters (data)​

Example​

6. Error Codes​

6.1 HTTP Status Codes​

6.2 Business Error Codes (code field)​

6.2.1 Common Error Codes​

6.2.2 Credential and Authentication Error Codes​

6.2.3 Business Error Codes (Palm Business)​

7. Integration Example (Go)​

1. Quick Start

2. Applying for a Token (API Key)

2.1 Where to Apply

2.2 Application Process

2.3 How to Use

3. General Conventions

3.1 API Domain

3.2 URL Prefix

3.3 Request Headers (HTTP Headers)

3.4 Request Body

3.5 Common Response Structure

3.6 Rate Limits

4. Common Data Types

4.1 `PalmDirectionType` Enum

4.2 `PalmState` Enum (Palm State)

5. Business APIs

API List

5.1 Token Authentication (CreateSdkUserToken)

Description

Request Parameters

Response Parameters (`data`)

Example

Calling Business APIs with the `sdk_user_token` (applies to web backends / SDKs / Mini Programs)

5.2 Palm Registration Query (GetPalm)

Description

Request Parameters

Response Parameters (`data`)

Example

5.3 Query Recognition Result (GetSessionResult)

Description

Request Parameters

Response Parameters (`data`)

Example

5.4 Palm Deletion (DeletePalm)

Description

Request Parameters

Response Parameters (`data`)

Example

6. Error Codes

6.1 HTTP Status Codes

6.2 Business Error Codes (`code` field)

6.2.1 Common Error Codes

6.2.2 Credential and Authentication Error Codes

6.2.3 Business Error Codes (Palm Business)

7. Integration Example (Go)