xhs Documentation

When using xhs for basic operations, you must provide a cookie containing the following three mandatory fields:

• a1
• web_session
• webId

For advanced usage and multi-account support, you can encapsulate playwright into a server-side service. The main application logic then uses requests to call this service to obtain signatures.

Critical Requirement: When using a unified signature service across multiple accounts, ensure that the a1 field in the cookies is consistent across all accounts to avoid continuous signature errors.

If you require the most recent features or fixes, you can install the package directly from the GitHub repository.

$ python -m pip install git+https://github.com/ReaJason/xhs

To use xhs, you must install the package along with playwright for browser simulation (used to execute JS for signature generation) and the stealth.min.js script to bypass environment detection.

Follow these steps to set up your environment:

You can run a Flask-based signature service using Docker. This service allows you to use XhsClient to request signatures. When the service starts, it will print the a1 value. It is highly recommended to ensure the a1 field in your cookies matches the a1 value set in the server to prevent signature errors.

docker run -it -d -p 5005:5005 reajason/xhs-api:latest

If you prefer to run the Flask signature service locally instead of using Docker, install the following dependencies:

pip install flask, gevent, requests

To build Docker images that support multiple architectures (e.g., linux/arm64 and linux/amd64) simultaneously, use the docker buildx command. This requires creating a new builder instance with the docker-container driver.

Follow these steps:

1. Create a new builder named mybuilder using the docker-container driver.
2. Switch to using the newly created mybuilder.
3. Execute the build command specifying the target platforms with the --platform flag and push the resulting image using --push.

docker buildx create --name mybuilder --driver docker-container

docker buildx use mybuilder

docker buildx build --platform linux/arm64,linux/amd64 -t reajason/xhs-api . --push

You can install the stable version of xhs from PyPI using pip.

$ python -m pip install xhs

Execute social actions like following users or interacting with content:

User Interactions:

• follow_user(user_id): Follow a user.
• unfollow_user(user_id): Unfollow a user.

Note Interactions:

• collect_note(note_id): Save/collect a note.
• uncollect_note(note_id): Remove a note from collections.
• like_note(note_id): Like a note.
• dislike_note(note_id): Unlike a note.

Comment Interactions:

• like_comment(note_id, comment_id): Like a specific comment.
• dislike_comment(comment_id): Unlike a specific comment.

# Examples
xhs_client.follow_user("用户ID")
xhs_client.unfollow_user("用户ID")
xhs_client.collect_note("笔记ID")
xhs_client.uncollect_note("笔记ID")
xhs_client.like_note("笔记ID")
xhs_client.dislike_note("笔记ID")
xhs_client.like_comment("笔记ID", "评论ID")
xhs_client.dislike_comment("评论ID")

Use these methods to manage the QR code login flow:

• get_qrcode(): Retrieve a new QR code for login.
• check_qrcode(qrcode_id, qrcode_code): Check the status of a specific QR code to see if it has been scanned/authenticated.

# Examples
xhs_client.get_qrcode()
xhs_client.check_qrcode("二维码ID", "二维码编码")