xhshow 0.1.9

XHS API signature generator

xhshow

小红书请求签名生成库，支持GET和POST请求的x-s签名生成。

系统要求

• Python 3.10+

安装

pip install xhshow

使用方法

基本用法（推荐）

from xhshow import Xhshow
import requests

client = Xhshow()

# 准备 cookies（支持字典或字符串格式）
cookies = {
    "a1": "your_a1_value",
    "web_session": "your_web_session",
    "webId": "your_web_id"
}
# 或使用 Cookie 字符串格式:
# cookies = "a1=your_a1_value; web_session=your_web_session; webId=your_web_id"

# 注意: uri 参数可以传递完整 URL 或 URI 路径，会自动提取 URI
headers = client.sign_headers_get(
    uri="https://edith.xiaohongshu.com/api/sns/web/v1/user_posted",  # 完整 URL（推荐）
    # uri="/api/sns/web/v1/user_posted",  # 或者只传 URI 路径
    cookies=cookies,  # 传入完整 cookies
    params={"num": "30", "cursor": "", "user_id": "123"}
)

# 返回的 headers 包含以下字段:
# {
#     "x-s": "XYS_...",
#     "x-s-common": "...",
#     "x-t": "1234567890",
#     "x-b3-traceid": "...",
#     "x-xray-traceid": "..."
# }

# 方式1: 使用 update 方法更新现有 headers（推荐）
base_headers = {
    "User-Agent": "Mozilla/5.0...",
    "Content-Type": "application/json"
}
base_headers.update(headers)
response = requests.get(
    "https://edith.xiaohongshu.com/api/sns/web/v1/user_posted",
    params={"num": "30", "cursor": "", "user_id": "123"},
    headers=base_headers,
    cookies=cookies
)

# 方式2: 使用 ** 解包创建新 headers
response = requests.get(
    "https://edith.xiaohongshu.com/api/sns/web/v1/user_posted",
    params={"num": "30", "cursor": "", "user_id": "123"},
    headers={
        "User-Agent": "Mozilla/5.0...",
        "Content-Type": "application/json",
        **headers  # 解包签名 headers（会创建新字典）
    },
    cookies=cookies
)

# POST 请求示例：使用 sign_headers_post
headers_post = client.sign_headers_post(
    uri="https://edith.xiaohongshu.com/api/sns/web/v1/login",
    cookies=cookies,
    payload={"username": "test", "password": "123456"}
)

response = requests.post(
    "https://edith.xiaohongshu.com/api/sns/web/v1/login",
    json={"username": "test", "password": "123456"},
    headers={**base_headers, **headers_post},
    cookies=cookies
)

# 构建符合xhs平台的GET请求链接
full_url = client.build_url(
    base_url="https://edith.xiaohongshu.com/api/sns/web/v1/user_posted",
    params={"num": "30", "cursor": "", "user_id": "123"}
)
response = requests.get(full_url, headers=headers, cookies=cookies)

# 构建符合xhs平台的POST请求body
json_body = client.build_json_body(
    payload={"username": "test", "password": "123456"}
)
response = requests.post(url, data=json_body, headers=headers, cookies=cookies)

传统方法（单独生成各个字段）

from xhshow import Xhshow
import requests

client = Xhshow()

# 注意: sign_headers_* 系列方法使用 cookies 参数
# 而 sign_xs_* 系列方法使用 a1_value 参数

# 使用统一方法 sign_headers（需要手动指定 method）
cookies = {"a1": "your_a1_value", "web_session": "..."}
headers = client.sign_headers(
    method="GET",  # 或 "POST"
    uri="https://edith.xiaohongshu.com/api/sns/web/v1/user_posted",
    cookies=cookies,  # sign_headers 使用 cookies 参数
    params={"num": "30"}  # GET 请求使用 params，POST 请求使用 payload
)

# GET 请求签名（使用 sign_xs_get - 只需要 a1_value）
x_s = client.sign_xs_get(
    uri="https://edith.xiaohongshu.com/api/sns/web/v1/user_posted",  # v0.1.3及后续版本支持自动提取uri
    # uri="/api/sns/web/v1/user_posted"  # v0.1.2及以前版本需要主动提取uri
    a1_value="your_a1_cookie_value",  # sign_xs_* 系列使用 a1_value
    params={"num": "30", "cursor": "", "user_id": "123"}
)

# POST 请求签名（使用 sign_xs_post - 只需要 a1_value）
x_s = client.sign_xs_post(
    uri="https://edith.xiaohongshu.com/api/sns/web/v1/login",
    a1_value="your_a1_cookie_value",  # sign_xs_* 系列使用 a1_value
    payload={"username": "test", "password": "123456"}
)

# 生成其他 headers 字段
x_t = client.get_x_t()  # 时间戳（毫秒）
x_b3_traceid = client.get_b3_trace_id()  # 16位随机 trace id
x_xray_traceid = client.get_xray_trace_id()  # 32位 trace id

# 手动构建 headers
headers = {
    "x-s": x_s,
    "x-t": str(x_t),
    "x-b3-traceid": x_b3_traceid,
    "x-xray-traceid": x_xray_traceid
}

# 使用统一时间戳（可选，确保所有字段使用相同时间）
import time
timestamp = time.time()

x_s = client.sign_xs_get(
    uri="/api/sns/web/v1/user_posted",
    a1_value="your_a1_cookie_value",
    params={"num": "30"},
    timestamp=timestamp  # 传入统一时间戳
)
x_t = client.get_x_t(timestamp=timestamp)
x_xray_traceid = client.get_xray_trace_id(timestamp=int(timestamp * 1000))

# 生成 x-s-common 签名
# x-s-common 签名需要完整的 cookies
cookies = {
    "a1": "your_a1_value",
    "web_session": "your_web_session",
    "webId": "your_web_id"
}

# 方式1: 使用 sign_xsc 别名方法（推荐）
xs_common = client.sign_xsc(cookie_dict=cookies)

# 方式2: 使用完整方法名
xs_common = client.sign_xs_common(cookie_dict=cookies)

# 方式3: 支持 Cookie 字符串格式
cookie_string = "a1=your_a1_value; web_session=your_web_session; webId=your_web_id"
xs_common = client.sign_xsc(cookie_dict=cookie_string)

# 使用在请求中
headers = {
    "x-s-common": xs_common,
    # ... 其他 headers
}

会话管理（实验性功能）

SessionManager 用于模拟真实用户会话，维护状态化的签名参数，可能有助于提升长期稳定性。

注意：此功能基于 #86 理论分析，实际效果待验证。建议先在测试环境使用。

基本使用

from xhshow import Xhshow, SessionManager
import requests

client = Xhshow()
session = SessionManager()  # 创建会话管理器

cookies = {"a1": "...", "web_session": "...", "webId": "..."}

# 使用 session 参数进行签名
headers = client.sign_headers_get(
    uri="/api/sns/web/v1/user_posted",
    cookies=cookies,
    params={"num": "30"},
    session=session  # 传入 session
)

response = requests.get(
    "https://edith.xiaohongshu.com/api/sns/web/v1/user_posted",
    params={"num": "30"},
    headers=headers,
    cookies=cookies
)

# 同一个 session 可以在多次请求中复用
headers2 = client.sign_headers_get(
    uri="/api/sns/web/v1/homefeed",
    cookies=cookies,
    params={"page": "1"},
    session=session  # 复用同一个 session
)

账户池管理

如果你有多个账户，需要为每个账户创建独立的 SessionManager：

accounts = [
    {"a1": "account1_a1", "web_session": "session1"},
    {"a1": "account2_a1", "web_session": "session2"},
]

# 为每个账户创建独立的 session
sessions = {}
for account in accounts:
    sessions[account["a1"]] = SessionManager()

# 使用时匹配账户和对应的 session
for account in accounts:
    headers = client.sign_headers_get(
        uri="/api/sns/web/v1/user_posted",
        cookies=account,
        params={"num": "30"},
        session=sessions[account["a1"]]  # 使用对应账户的 session
    )

工作原理

• 无 Session：每次请求生成随机参数，可能被识别为机器人行为
• 有 Session：维护固定的页面加载时间戳和单调递增的计数器，模拟真实用户在同一页面中的连续操作

适用场景：

• 长期运行的爬虫或服务

解密签名

# 解密 x3 签名
decoded_bytes = client.decode_x3("mns0101_Q2vPHtH+lQJYGQfhxG271BIvFFhx...")

# 解密完整的 XYS 签名
decoded_data = client.decode_xs("XYS_2UQhPsHCH0c1Pjh9HjIj2erjwjQhyoPT...")

自定义配置

from xhshow import CryptoConfig, Xhshow

custom_config = CryptoConfig().with_overrides(
    X3_PREFIX="custom_",
    SIGNATURE_DATA_TEMPLATE={"x0": "4.2.6", "x1": "xhs-pc-web", "x2": "Windows", "x3": "", "x4": ""},
    SEQUENCE_VALUE_MIN=20,
    SEQUENCE_VALUE_MAX=60
)

client = Xhshow(config=custom_config)

参数说明

sign_headers 系列方法（推荐使用）

• uri: 请求 URI 或完整 URL（会自动提取 URI）
• cookies: 完整的 cookie 字典或 cookie 字符串
  • 字典格式: {"a1": "...", "web_session": "...", "webId": "..."}
  • 字符串格式: "a1=...; web_session=...; webId=..."
• xsec_appid: 应用标识符，默认为 xhs-pc-web
• params: GET 请求参数（仅在 method="GET" 时使用）
• payload: POST 请求参数（仅在 method="POST" 时使用）
• timestamp: 可选的统一时间戳（秒）

sign_xs 系列方法

• uri: 请求 URI 或完整 URL
• a1_value: cookie 中的 a1 值（字符串）
• xsec_appid: 应用标识符，默认为 xhs-pc-web
• params/payload: 请求参数（GET 用 params，POST 用 payload）
• timestamp: 可选的统一时间戳（秒）

sign_xsc 系列方法

• cookie_dict: 完整的 cookie 字典或 cookie 字符串

开发环境

环境准备

# 安装uv包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆项目
git clone https://github.com/Cloxl/xhshow
cd xhshow

# 安装依赖
uv sync --dev

开发流程

# 运行测试
uv run pytest tests/ -v

# 代码检查
uv run ruff check src/ tests/ --ignore=UP036,E501

# 代码格式化
uv run ruff format src/ tests/

# 构建包
uv build

Git工作流

# 创建功能分支
git checkout -b feat/your-feature

# 提交代码（遵循conventional commits规范）
git commit -m "feat(client): 添加新功能描述"

# 推送到远程
git push origin feat/your-feature

功能建议

如果您有任何功能建议或想法，欢迎在 #60 中提交。我们期待您的宝贵建议，共同打造更好的 xhshow！

License

MIT