948 完整接口文档

自助注册与 API Key（当前接入流程）

1. 主站注册账号，自动开通后台配置的试用天数和调用次数，无需审批。
2. POST /api/account/login：{username,password}。网页会话可在到期后查看套餐并续费。
3. 登录后 POST /api/keys/create：{label}，获取只显示一次的 API Key；GET /api/keys 查询前缀，POST /api/keys/revoke：{id} 撤销。
4. 程序调用 /api/device/ 时使用 Authorization: Bearer xhs_…，不绑定机器码。密钥只能调用设备业务接口，不能管理账号或创建其他密钥。
5. GET /api/billing/summary 查看余额和到期时间；GET /public/plans 查看试用规则与套餐；GET /api/orders 查看订单。

每个携带有效凭据的 /api/device/ 请求消耗一次总额度，失败请求也计数；账号查询、登录和密钥管理不消耗试用总额度。其他每分钟和每日限流仍生效。额度耗尽返回业务 402，业务到期返回 401；网站仍可登录查看账户和续费。

套餐价格未设置，不虚构收费；支付渠道尚未接入。后台可配置套餐与真实收款说明；有实际收款后管理员确认订单到账，自动增加额度和期限。当前没有自动支付网关、支付回调或退款接口，不把创建订单当作支付成功。

以下机器码登录等旧流程仅保留兼容，新的用户使用上述流程。

申请、登录和 Token

1. 在主站申请区申请平台账号，等待管理员审批；客户端标识在首次成功登录时自动绑定。期限从批准时开始计算。
2. POST A /api/auth/login，JSON 提交 username、password、machineCode；无需 Bearer Token。
3. 业务 code=200 后读取 data.token，其他受保护接口携带 Authorization: Bearer <TOKEN>。

Token 默认 24 小时；POST /api/auth/refresh 在当前 Token 有效且账号有效时签发新 Token，旧 Token 保留至过期。账号到期、停用、改机器码、重置密码或撤销 Token 会阻止相关访问。POST /api/auth/logout 撤销当前账号全部 Token。

支持 HTTPS 明文 JSON，也兼容既有 Java AES-GCM 封装。客户端标识由程序自动生成并持久保存，不显示在申请页或用户页面；首次账号密码验证成功后原子绑定。网页使用浏览器本地存储，SDK 使用本地文件。清除存储或换设备后需管理员重置绑定。该标识不是硬件指纹或身份密钥。一个账号的设备只能由该账号访问。

管理员 API 可用管理员密钥 Bearer 调用；网页管理员登录使用一小时 HttpOnly、Secure、SameSite=Strict 会话。管理员 Cookie 请求受 Origin 检查。

平台与申请接口

下表字段为当前契约摘要；所有 POST 使用 JSON 对象。标记“账号”的接口使用平台 Token；“管理员”使用管理员凭据或会话。示例响应可下载 api-contract.json，其中样例是契约示意，不是业务成功证据。

状态、限额、超时与重试

{"code":200,"msg":"success","data":{"…":"接口数据"}}
{"code":401,"msg":"Login required","data":null}

HTTP 成功不代表业务成功。检查业务 code 后再检查设备 phase 和代发的 httpCode/body。CREATED 是档案建立；ACTIVATED 是激活，不能当成完整注册；REGISTERED 仅在必要注册步骤通过后返回；LOGGED_IN 是登录成功状态。

400 参数错误；401 登录、机器码、Token 或期限问题；403 管理会话来源错误；404 设备不属于当前用户或不存在；409 重复账号或设备状态冲突；413 请求超出 1 MiB；429 限额或频率超出；501 尚未实现；502 上游操作失败。申请接口的业务错误可能使用 HTTP 200；限流可能使用 HTTP 429。

默认每个账号 60 次 / 分钟、10,000 次 / UTC 日；管理员可调整。携带有效 Token 的 /api/ 请求计数，包括查询和失败调用。登录、审批结果查询和管理员登录每 IP 每路径 10 次 / 分钟；图形验证码与申请共享每 IP 20 次 / 分钟。429 可按 Retry-After 等待；日额度超出需次日或管理员调整。

代发上游超时 45 秒；代理层最长等待 180 秒。注册链路可能较慢。客户端网络超时后先查询设备状态，不能假定服务器没有执行。短信、注册、删除、审批和修改操作不要自动重试；查询可有限重试。接口未提供幂等键，同设备并发操作由服务端串行处理。

响应 X-Request-ID 可用于排查。密码、Token、代理凭据和完整上游响应不要写入公开日志。

SOCKS5 与代发限制

proxy 使用 socks5://[user:pass@]host:port 或 socks5h://[user:pass@]host:port；空字符串清除。凭据中的特殊字符应 URL 编码。注册、短信和代发沿用设备代理。API 域名由区号选择，并不表示自动更换代理国家。

/api/device/send 仅支持 GET/POST、HTTPS 443、/api/ 路径；目标允许 rec.xiaohongshu.com、edith.xiaohongshu.com、www.xiaohongshu.com、live-room.xiaohongshu.com、edith.rnote.com；不跟随重定向。bizParams.host 必填，其他编码请对照完整契约。

业务支持与证据

29 条已整理路径见 业务接口目录。源码实现、抓包、作者示例和本平台实测是不同证据层级。不能把目录数量当成已验证可用数量。

• 平台申请、登录、账号管理与网页控制台可直接调用平台后端。
• 2026-10-07 实际设备注册复测：返回 ACTIVATED；onboarding 三项成功，cfg 发生 ConnectTimeout，Tiny register=-1，其余 Tiny 步骤返回 0。未达到 REGISTERED。控制台呈现实际结果，不承诺完整注册成功。
• 小红书密码登录和快捷登录目前返回 501。
• 群聊、私信、头像上传完整链、点赞、收藏和笔记发布缺完整契约或验证证据，尚未开放可用承诺；需要完整抓包/测试资料后才能实现验证。

控制台与首页演示互相独立。控制台不会自动发送短信，每次操作需用户点击；敏感上游字段默认隐藏。

数据与隐私

平台存储账号密码散列、绑定机器码、有效期、设备档案、业务会话和设备代理配置。平台代理凭据和业务会话是敏感数据，目前数据库按服务账号权限保护，尚未实现数据库字段级加密。

调用记录只存用户名、接口路径、HTTP/业务状态、耗时、时间和请求编号，不存请求体、Token、手机号、代理密码或上游响应。调用记录保留 30 天；过期 Token 定期清理。备份本地保留 7 天；备份可能包含设备敏感状态，仅管理员可读取。设备删除和账号操作不立即清除已有备份。

网页会话保存在当前标签页的 sessionStorage，刷新后保持登录；退出登录后清除并撤销会话。关闭标签页后本地会话随之清除。密码修改、停用与撤销可以使 Token 失效。管理员可根据账号请求处理设备删除和相关数据问题；公开客服渠道尚未配置。

服务支持

审批、续期、机器码变更及故障请联系向你提供平台的管理员，并提供 X-Request-ID、接口路径、时间和脱敏错误信息。当前没有配置公开邮箱、QQ 或工单地址；不提供虚构联系方式。

更新日志与兼容性

2026-10-07：A 开发者平台、主站账号申请（原 B 地址跳转）；账号中心、真实手动控制台、审批查询、管理员账号管理、调用限额与记录、文档和 Python 下载。固定 iOS 948；未提供 947/949 兼容保证。

桌面和移动布局使用响应式设计；390px 浏览器布局检查通过，仍需真实手机进行最终操作验收。服务健康检查 /health 仅说明平台服务存活，不代表全部小红书接口可用。