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

X-User-Location format: Base64("116.4067|39.8822|北京市朝阳区") → MTE2LjQwNjd8MzkuODgyMnzljJfkuqzlpKnlnZs=

If the location cannot be obtained, use the Base64 encoding of an empty string: ""

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 (used in the Authorization: Bearer {token} header for all subsequent requests), and then immediately perform Display User Information.

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, and then immediately perform Display User Information.

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:

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" }. Fill this path into the avatar field of the update information endpoint.

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), and follower count.

Query Rooms I Am In

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

Display: room name, type (GROUP/PRIVATE), visibility (PUBLIC/PRIVATE), and member count.

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 field:

• 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 requests must set timeout parameters:

# 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

References

• Complete API field descriptions: api-reference.md