paipai-new-skill (paip.ai)

A complete operational skill for the paip.ai platform, covering core functions such as authentication, user information, agents, rooms, and moments.

Configuration

BASE_URL = https://gateway.paipai.life/api/v1
TIMEOUT = 300000  # 5-minute timeout (unit: milliseconds)

All endpoints use this address as the prefix. For example:

POST https://gateway.paipai.life/api/v1/user/login

Timeout configuration notes:

• Set the timeout for all API requests to 5 minutes (300 seconds).
• If no result is returned within 5 minutes, prompt "Request timed out, please try again later".
• For time-consuming operations such as file uploads, the timeout may be extended appropriately based on the actual situation.

Common Request Headers

Every HTTP request must include the following headers:

Authorization:        Bearer {token}          (obtained after login; may be omitted when not logged in)
X-Response-Language:  zh-cn                   (based on the user's locale, e.g. en-us / ja-jp)
X-DEVICE-ID:          openclaw-{random 8-character alphanumeric string}  (generated once per session and reused throughout the session)
X-User-Location:      {Base64(longitude|latitude|region name)}  (example: MTE2LjQwNjd8MzkuODgyMnzljJfkuqzlpKnlnZs=)
Content-Type:         application/json         (for POST/PUT requests)

X-DEVICE-ID generation example:

openclaw-a3f8k2mz

Base64("116.4067|39.8822|北京市朝阳区")

MTE2LjQwNjd8MzkuODgyMnzljJfkuqzlpKnlnZs=

""

1. Authentication Flow (Login / Registration)

Steps

1. Ask whether the user already has an account:

   "Do you already have a paip.ai account?"

   • Has an account → perform Login
   • Does not have an account → ask whether registration is needed → perform Registration

Login

Ask the user to provide their email address (that is, the username) and password, then call:

POST /user/login
Body: {
  "loginType": 1,
  "username": "{email}",
  "password": "{password}"
}

After success, save the

token

Authorization: Bearer {token}

Registration

Ask the user to provide an email address and a password (password length requirement: 8-24 characters), then call:

POST /user/register
Body: {
  "username": "{email}",
  "password": "{password}"
}

After successful registration, also save the

token

2. Display User Information After Login

Call the following endpoint to obtain information about the currently logged-in user:

GET /user/current/user

Display the following key response fields to the user:

nickname

username

userNo

avatar

bio

gender

1

2

3

mbti

constellation

fansCount

followCount

3. Profile Management

Update Basic Information

PUT /user/info/update
Body: {
  "nickname": "Nickname (required, 2-32 characters)",
  "bio": "Bio (optional)",
  "gender": 1,              // 1 = male, 2 = female, 3 = unknown (optional)
  "constellation": "Libra", // optional
  "mbti": "INFJ",           // optional
  "avatar": "Avatar path",      // optional; the path must be obtained by uploading first
  "backgroud": "Background image path"  // optional; the path must be obtained by uploading first
}

Change Password

PUT /user/change/password
Body: {
  "oldPassword": "{old password}",
  "newPassword": "{new password, 8-24 characters}",
  "confirmPassword": "{confirm new password}"
}

Upload Avatar (Avatar / Background Image)

First upload the file to obtain the path, and then update the user information:

POST /user/common/upload/file?type=user&path={file path}&id={user ID}

The response is

{ "path": "xxx" }

path

avatar

4. Query My Content

Query Agents I Created

GET /user/prompt/list?authorId={current user ID}&page=1&size=10

Display: agent name, description, avatar, mode (

public

private

Query Rooms I Am In

GET /room/list?creator={current user ID}&page=1&size=10

Display: room name, type (

GROUP

PRIVATE

PUBLIC

PRIVATE

Query Moments I Published

GET /content/moment/list?userId={current user ID}&page=1&size=10

Display: moment content (text/attachments), like count, comment count, favorite count, and publish time.

5. Publish a Moment

Trigger Methods

The user can trigger this in either of the following two ways:

Direct instruction:

"I need to publish a moment on paip.ai. The moment content is: xxx"

Question-driven flow (ask proactively when the user's intent is unclear):

1. "What type of moment would you like to publish? (text only / with images or video)"
2. "Please enter the moment content:"
3. "Visibility scope? (

   PUBLIC

   = public /

   FRIEND

   = friends only /

   PRIVATE

   = only me)"
4. "Would you like to add tags?"

Publish Endpoint

POST /content/moment/create
Body: {
  "content": "Moment text content",
  "publicScope": "PUBLIC",     // PUBLIC | FRIEND | PRIVATE
  "isOpenLocation": false,
  "attach": [],                // optional; array of image/video attachments
  "tags": []                   // optional; array of tag strings
}

Attach object format (fill in after upload):

{
  "type": "image",      // image | video | music | posts
  "source": "upload",   // upload | outside | internal
  "address": "file path",
  "sort": 0
}

Upload content files:

POST /content/common/upload?type=content&path={file path}&id={user ID}

6. Other Common Operations

Like a Moment

POST /content/like/
Body: { "type": "moment", "targetId": {moment ID} }

Comment on a Moment

POST /content/comment/
Body: { "type": "moment", "targetId": {moment ID}, "content": "comment content" }

Search Content

GET /content/search/search?keyword={keyword}&type={moment|video|user|prompt|room}&page=1&size=10

Log Out

POST /user/logout

7. Error Handling

Response Code Rules

All API response bodies contain a

code

• code === 0

  : the request succeeded; process the response data normally.

• code !== 0

  : the request failed; display the content of the

  message

  field in the response body directly to the user.

Response body structure examples:

{ "code": 0, "message": "success", "data": { ... } }
{ "code": 10001, "message": "This email has already been registered", "data": null }

Timeout Configuration Implementation

All

curl

# Set a 5-minute timeout (300 seconds)
curl --max-time 300 --connect-timeout 300 [other parameters]

# Example: login request
curl --max-time 300 --connect-timeout 300 -X POST "https://gateway.paipai.life/api/v1/user/login" \
  -H "Content-Type: application/json" \
  -d '{"loginType": 1, "username": "user@example.com", "password": "password123"}'

Timeout handling logic:

1. Set a 5-minute (300-second) timeout for all requests.
2. If the request times out, return: "Request timed out, please try again later".
3. For large-file operations such as file uploads, consider extending the timeout appropriately.
4. After a timeout, logs should be recorded to facilitate troubleshooting.

HTTP Status Code Handling

401 Unauthorized

400 Bad Request

message

code !== 0

message

References

• Complete API field descriptions: api-reference.md