Snowflake 账号管理系统 · 完整 API 文档
线上地址: https://snow.51proxy.org/docs
机器可读契约: https://snow.51proxy.org/openapi.json(OpenAPI 3.1)
本文是唯一完整的中文 API 参考;docs/EMAIL_API.md、docs/MUSECODE_API.md已改为指向本文的短指引。
本文档不含任何真实 Token、密钥、卡号或账号数据,示例一律使用占位符。
目录
- 概述与认证
- 约定(时间、分页、错误)
- 认证接口
- 库存统计
- 邮箱(领取 / 订阅 / 读信)
- 银行卡与账单地址
- Snowflake 账号
- 托管人工绑卡(magic link)
- Kiro 账号
- MuseCode 账号
- MuseAI 账号
- Muse 资产
- 接口一览表
- 推荐调用流程
1. 概述与认证
Base URL: https://snow.51proxy.org
除下列例外外,所有 /api/* 接口都需要认证:
| 方式 | 说明 |
|---|---|
Authorization: Bearer <API_TOKEN> | 自动化脚本 / 外部注册程序(Cloudflare Secret API_TOKEN) |
| 管理后台登录 Cookie | POST /api/auth/login 签发,有效期 8 小时,HttpOnly |
无需 Token 的接口:
GET /api/auth/session(返回是否已登录)POST /api/auth/login、POST /api/auth/logout- 绑卡会话接口
GET|POST /api/bind/{id}/*(使用X-Bind-Token校验短期 magic link) - 公开取件接口
POST /api/public/pickup/{token}/fetch与页面GET /pickup/{token}(token 即授权,见 公开取件链接)
未认证访问受保护接口 → 401 {"error":"未授权"}。
文档页(/docs、/openapi.json)公开可读,与当前 openapi.json 一致。
2. 约定(时间、分页、错误)
时间
- 数据库统一存 UTC
YYYY-MM-DD HH:MM:SS。 - API 响应中匹配
*_at的字段一律序列化为北京时间+08:00(如2026-10-20T12:00:00+08:00)。 - 例外: 调用方提交并原样回显的 JSON(如 MuseCode 的
browser_fingerprint/auth_data/proxy_geo)内部时间字段不做时区转换。 - 请求时间:带时区的 ISO 8601 按其时区;不带时区或纯日期按北京时间(UTC+8)。
游标分页
多数列表接口:
{ "items": [ ... ], "has_more": true, "next_cursor": "123" }
limit:默认 50,最大 200(个别接口另有说明)。cursor:上一页返回的next_cursor(正整数字符串)。- 邮箱列表额外支持
order=asc|desc(默认asc);升序时 cursor 取id > cursor,降序取id < cursor。翻页时请保持相同order。 - 邮箱列表与领取还支持可选
id_min/id_max(闭区间,正整数);只传其一亦可;id_min > id_max→ 400。 - 其他账号列表(银行卡、Snowflake、Kiro、MuseCode)按 ID 倒序。
错误格式
{ "error": "人类可读的中文说明" }
常见状态码:400 参数无效、401 未授权、404 资源不存在、409 冲突(重复订阅 / 唯一约束 / 锁不匹配)、415 Content-Type 非 JSON、500 服务器错误、502 上游(Kiro / Outlook / Snowflake)失败。
3. 认证接口
POST /api/auth/login
管理后台登录,签发 8 小时 Cookie。
{ "password": "<管理员密码>" }
成功 → 200;密码错误 → 401。
POST /api/auth/logout
清除管理会话 Cookie。
GET /api/auth/session
{ "authenticated": true }
无需 Token。
4. 库存统计
GET /api/stats
可选 ?service=<name> 额外统计一个尚无记录的服务。
响应字段包括:emails_total、emails_available(不带 service 领取可用数)、emails_unsubscribed、emails_legacy_used、cards_total、cards_available、cards_locked、cards_used(均不含已软删除的银行卡)、cards_deleted(已软删除数)、snowflake_total、kiro_total、musecode_total、musecode_linked、muse_assets_total / muse_assets_unsubmitted / muse_assets_submitted(未删除的 Muse 资产总数、未提交、已提交)、email_services: [{service, subscribed, locked, available}]、musecode_subscription_statuses: [{status, count}]。
5. 邮箱(领取 / 订阅 / 读信)
本章合并原
docs/EMAIL_API.md;请以本文为准。
适用于外部注册程序 / 自动化脚本。生产地址 https://snow.51proxy.org。所有请求带:
Authorization: Bearer <API_TOKEN>
Content-Type: application/json
ID 范围(id_min / id_max)
领取(POST /api/emails/claim 请求体)与列表(GET /api/emails 查询参数)均支持可选闭区间筛选:
| 参数 | 位置 | 说明 |
|---|---|---|
id_min | claim 请求体 / list query | 最小邮箱 ID(含),正整数 |
id_max | claim 请求体 / list query | 最大邮箱 ID(含),正整数 |
- 可只传其一;同时传时必须
id_min <= id_max,否则400。 - 非法值(≤0、小数、前导零字符串、非数字)→
400。 - 领取选号顺序: 在
service/suffix/ 可领取条件之后,按ORDER BY e.id ASC取范围内最小可用 ID(与列表默认order=asc一致);范围内没有可领邮箱时仍返回原来的404(如没有可订阅 claude 的邮箱)。 - 原子锁行为不变:
INSERT INTO email_locks … SELECT … LIMIT 1。
curl -X POST "$BASE/api/emails/claim" -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-d '{"service":"claude","id_min":100,"id_max":200,"suffix":"outlook.com"}'
curl "$BASE/api/emails?id_min=100&id_max=200&order=asc&limit=50" -H "Authorization: Bearer $TOKEN"
邮箱类型(provider):Outlook / iCloud
库存邮箱分两类,由导入行格式决定(与邮箱域名无关,@icloud.com 以外的 Hide My Email 别名也可以按 iCloud 导入):
| provider | 导入格式(每行一个) | 读信方式 |
|---|---|---|
outlook(默认,存量全部) | email----password----client_id----refresh_token(严格 4 个连字符分隔) | Microsoft OAuth → IMAP / Graph |
icloud | email----https://取件链接(3 个及以上连字符,两侧空白可忽略) | 服务端请求取件链接 |
iCloud 导入示例(授权码为占位符):
alias@icloud.com----https://mail.example.com/latest?email=alias@icloud.com&auth_code=YOUR_AUTH_CODE
alias2@icloud.com----https://icloud.mida.vip/messages/alias2%40icloud.com?token=YOUR_64_HEX_TOKEN
导入规则:
- 空行忽略;两种格式可以混在同一批。取件链接后若又拼了
----其他字段,从----处截断。 - 取件链接必须
https;不能是 IP / localhost /.local/.internal主机,不能带账号密码或非 443 端口;链接中带邮箱时必须与本行邮箱一致(大小写不敏感)。 - 支持的取件链接(
<host>任意 https 域名,服务端只请求同一 origin):- icloud.mida.vip 网页:
https://<host>/messages/<邮箱>?token=<token>(邮箱可 URL 编码,如%40)→ 请求https://<host>/api/messages?alias_email=<邮箱>&token=<token>(range=latest|3d|all、start_time会透传); - icloud.mida.vip 接口:
https://<host>/api/messages?alias_email=<邮箱>&token=<token>[&range=…]; - 分享页:
https://<host>/latest?email=<邮箱>&auth_code=<授权码>(也接受code/key)→ 请求/mail-api/<授权码>/<邮箱>?folder=inbox; - 直接的 JSON 接口:
https://<host>/mail-api/<授权码>/<邮箱>。
- 通用识别:其他路径也可以,只要 query 带
token(按 mida 接口请求)或auth_code/code/key(按/mail-api/请求);邮箱取自 query(alias_email/email/mail/address)或含@的路径段,没有时用本行邮箱。token / 授权码只允许A-Z a-z 0-9 . _ ~ -,长度 8–256。 - 缺少 token / 授权码时,错误信息会列出以上全部格式。
- icloud.mida.vip 网页:
- 取件链接(含授权码)用
DATA_ENCRYPTION_KEYAES-GCM 加密保存;列表 / 单个邮箱接口不返回,只有claim响应的fetch_url返回明文。iCloud 行的password/client_id/refresh_token为空串。 - 去重与原来一致(邮箱大小写不敏感):库里已存在 →
skipped;同批重复、格式错误、链接无效 →errors(错误信息不回显链接)。
201 {"imported":2,"skipped":1,"invalid":1,"imported_by_provider":{"outlook":0,"icloud":2},"errors":["第 4 行格式错误"]}
领取 / 列表都可加 provider=outlook|icloud(大小写不敏感,其他值 400);不传则不限,原有 service / suffix / id_min / id_max 规则不变。
核心规则
- 邮箱没有“已使用”状态。一个邮箱可以订阅多个不同服务(
snowflake、kiro、claude、openai…),同一服务只能订阅一次。 service不区分大小写,统一按小写处理,格式^[a-z0-9][a-z0-9._-]{0,63}$。legacy是系统保留值(迁移前已使用、服务未知的邮箱),不能用于领取。- 领取锁按(邮箱, 服务)加,默认 15 分钟后失效(
LOCK_TTL_MINUTES,只用于邮箱;银行卡领取锁不过期,见 6.8);同一邮箱可以同时被不同服务领取。 - 兼容:不传
service时沿用旧行为——只领取“没有订阅任何服务、也没有任何锁”的邮箱,并锁住整个邮箱;回写接口决定记录哪个服务。新程序请务必传service。
1. 领取邮箱 POST /api/emails/claim
curl -X POST https://snow.51proxy.org/api/emails/claim \
-H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"service":"claude","suffix":"outlook.com"}'
| 字段 | 必填 | 说明 |
|---|---|---|
service | 建议 | 目标服务;只返回未订阅该服务、且未被该服务领取的邮箱 |
suffix | 否 | 完整邮箱域名,如 outlook.com、hotmail.com;支持末尾通配 .*,如 hotmail.* 匹配 hotmail.com、hotmail.co.uk 等(前缀须为合法域名标签,* 只能出现一次且为最后一个字符、前面必须是 .,其余 * 位置均无效) |
id_min | 否 | 最小邮箱 ID(含),正整数;可与 id_max 组成闭区间 |
id_max | 否 | 最大邮箱 ID(含),正整数;须 >= id_min |
provider | 否 | outlook 或 icloud,只领取该类型邮箱;不传则不限 |
范围内按 id ASC 取最小可用邮箱;详见上方「ID 范围」。
响应 200:
{
"id": 12,
"email": "a@outlook.com",
"password": "邮箱密码",
"client_id": "Microsoft client_id",
"refresh_token": "Microsoft refresh_token",
"provider": "outlook",
"fetch_url": null,
"service": "claude",
"lock_token": "8a1f…-uuid",
"locked_at": "2026-10-19T12:00:00+08:00",
"subscriptions": [{ "service": "snowflake", "account_ref": "snowflake_accounts:9", "created_at": "2026-10-01T10:00:00+08:00" }]
}
subscriptions 是该邮箱已订阅的其他服务,仅供参考。错误:404 {"error":"没有可订阅 claude 的邮箱"}(范围内无可用邮箱时同样);400 service / suffix / provider / id_min/id_max 无效。
iCloud 邮箱领取({"service":"claude","provider":"icloud"})时:provider 为 icloud,fetch_url 为导入时的取件链接(含授权码,请勿记录到日志),password / client_id / refresh_token 为空串。
2. 读取邮件 / 验证码
方式 A(推荐,不经过本系统):Outlook 用领取返回的 client_id + refresh_token 直接走 Microsoft OAuth → IMAP/Graph 读信;iCloud 直接请求领取返回的 fetch_url 对应的取件接口。
方式 B:通过本系统读取(只需 API Token,不校验领取锁):
# 收件箱 + 垃圾邮件箱的最近邮件(每个文件夹最多 limit 封,默认 50,最大 100)
curl "https://snow.51proxy.org/api/emails/12/messages?limit=10" -H "Authorization: Bearer $API_TOKEN"
{
"email": "a@outlook.com",
"provider": "outlook",
"fetched_at": "2026-10-19T04:01:00.000Z",
"folders": [
{ "kind": "inbox", "name": "收件箱", "messages": [
{ "id": "…", "subject": "Your verification code", "sender_name": "Anthropic", "sender_address": "no-reply@…",
"received_at": "2026-10-19T04:00:30Z", "preview": "Your code is 123456", "is_read": false, "has_attachments": false }
] },
{ "kind": "junkemail", "name": "垃圾邮件", "messages": [] }
]
}
验证码通常在 preview 中,可自行用正则提取。完整正文:GET /api/emails/12/message?message_id=<上面的 id>(返回 text/html)。Microsoft 侧失败返回 502。
iCloud 邮箱走同样两个接口、同样的响应结构,区别:
- 服务端只请求该邮箱导入时保存的取件链接(https、不跟随重定向、20 秒超时),不会访问其他地址。
folders只有收件箱(kind: "inbox");还没有邮件时messages为空数组。- 每封邮件额外带
verification_code(上游识别出的验证码,没有则null);上游没有已读状态,is_read恒为true;received_at统一转换为+08:00;id为上游 Message-ID。 refresh=true|false(默认true):true要求上游实时刷新(分享页链接追加refresh=1,较慢但最新);false允许上游直接返回缓存。- 完整正文:上游没有单封接口,服务端重新拉取列表按
message_id匹配;正文取上游html,没有时把纯文本包成<pre>。找不到返回404。 - 取件链接失效 / 换新、上游返回错误、非 JSON、重定向或超时 →
502(错误信息不含链接)。
{
"email": "alias@icloud.com",
"provider": "icloud",
"fetched_at": "2026-10-20T09:00:00.000Z",
"folders": [
{ "kind": "inbox", "name": "收件箱", "messages": [
{ "id": "<abc@example.com>", "subject": "Your verification code", "sender_name": "Example", "sender_address": "noreply@example.com",
"received_at": "2026-10-20T17:15:13+08:00", "preview": "Your code is 123456", "is_read": true, "has_attachments": false,
"verification_code": "123456" }
] }
]
}
3. 回写订阅
注册成功后必须回写,否则锁到期后该邮箱会再次被同一服务领取。
| 服务 | 回写接口 |
|---|---|
| snowflake | POST /api/snowflake-accounts(email_id + email_lock_token + 账号资料,见 README) |
| kiro | POST /api/kiro-accounts/callback(email_id + email_lock_token + 凭据) |
| 其他(claude、openai…) | POST /api/emails/{id}/subscriptions |
curl -X POST https://snow.51proxy.org/api/emails/12/subscriptions \
-H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"service":"claude","lock_token":"8a1f…-uuid","account_ref":"org_abc","notes":"可选"}'
201 {"id":31,"email_id":12,"service":"claude","account_ref":"org_abc","created":true,"lock_consumed":true,"created_at":"2026-10-19T12:03:00+08:00"}
409 {"error":"该邮箱已订阅 claude 服务,同一邮箱每个服务只能订阅一次"}
409 {"error":"邮箱锁属于 openai 服务,不能用于 claude"}
409 {"error":"邮箱锁不存在或已经失效"}
锁必须来自同一个 service 的领取,或不带 service 的旧版领取。
4. 释放(注册失败时)POST /api/emails/{id}/release
curl -X POST https://snow.51proxy.org/api/emails/12/release \
-H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"lock_token":"8a1f…-uuid"}'
200 {"released":true,"email_id":12,"service":"claude"}
409 {"error":"锁不存在或已经失效"}
只释放这一次领取的锁,不影响该邮箱在其他服务上的锁和订阅。
5. 查询 / 筛选
GET /api/emails?service=claude # 已订阅 claude
GET /api/emails?service=claude&subscribed=false # 未订阅 claude(含正在被领取的)
GET /api/emails?service=claude&claimable=true # 此刻带 service=claude 调 claim 能领到的
GET /api/emails?subscribed=false # 未订阅任何服务
GET /api/emails?claimable=true&suffix=outlook.com # 旧版无 service 领取口径 + 后缀
GET /api/emails?limit=50 # 默认按 ID 升序(最早导入在前)
GET /api/emails?limit=50&cursor=50 # 升序下一页:id > 50
GET /api/emails?order=desc&limit=50 # 按 ID 降序(最新导入在前)
GET /api/emails?order=desc&limit=50&cursor=100 # 降序下一页:id < 100
GET /api/emails?q=alice # 地址包含 alice(忽略大小写)
GET /api/emails?q=alice&provider=icloud&order=desc # 搜索可与其他筛选、排序、翻页叠加
GET /api/emails/12 # 单个邮箱
GET /api/emails/by-address/Alice%40outlook.com # 按完整地址精确取单个邮箱
GET /api/stats?service=claude # 按服务统计 subscribed / locked / available
列表参数:q(按邮箱地址搜索,email 为别名)、service、provider=outlook|icloud、subscribed=true|false、claimable=true|false(不能与 subscribed 同用)、suffix、id_min / id_max(闭区间,正整数)、limit(≤200)、cursor(上一页的 next_cursor)、order=asc|desc、sort=id。
排序:order=asc|desc(默认 asc,即 ID 升序、最早导入在前;大小写不敏感,其他值返回 400)。⚠️ 2026-10-19 之前不传 order 时为降序,依赖“最新在前”的调用方请显式传 order=desc;可选 sort=id(目前只支持 id,其他值 400)。响应带 order 字段。cursor 的含义随方向变化:升序取 id > cursor,降序取 id < cursor,翻页时请保持与首页相同的 order。排序与 ID 范围可与 service、subscribed、claimable、suffix 任意组合。
按邮箱地址搜索:q(别名 email;同时传时以 q 为准,与 GET /api/musecode-accounts 一致)。
- 去首尾空格、忽略大小写、包含匹配:
q=alice命中Alice.Smith@outlook.com、alice2@icloud.com;传完整地址时自然只命中该地址 %、_、\按字面匹配(已转义 LIKE 通配符),例如q=bob_不会命中bobXjones@…- 空串 / 纯空白等于不筛选;超过 254 个字符 →
400 q 过长 - 可与
service、subscribed、claimable、provider、suffix、id_min/id_max、order任意叠加;翻页照常用next_cursor,翻页时请保持q和其他参数不变
GET /api/emails/by-address/{email}
按完整地址精确取单个邮箱,返回结构同 GET /api/emails/{id}(风格同 /api/musecode-accounts/by-email/{email}/subscription)。
{email}需 URL 编码(@可写%40,+须写%2B);去首尾空格、忽略大小写- 精确匹配,不做包含匹配;不存在 →
404 邮箱不存在;不像邮箱地址或编码错误 →400 email 无效
curl -H "Authorization: Bearer $API_TOKEN" "https://snow.51proxy.org/api/emails/by-address/alice.smith%40outlook.com"
# => {"id":1,"email":"Alice.Smith@outlook.com","provider":"outlook","client_id":"…","created_at":"…","subscriptions":[],"locks":[]}
{ "items": [ … ], "order": "asc", "has_more": true, "next_cursor": "50" }
列表 / 单个邮箱的每条记录:
{
"id": 12, "email": "a@outlook.com", "provider": "outlook", "client_id": "…", "created_at": "…",
"subscriptions": [{ "service": "claude", "account_ref": "org_abc", "created_at": "…" }],
"locks": [{ "service": "openai", "locked_at": "…" }]
}
locks[].service 为 * 表示旧版无 service 领取的整邮箱锁。列表和单个邮箱都不返回密码、refresh token 和 iCloud 取件链接(只有 claim 与 GET /api/emails/{id}/pickup-info(支持登录会话与 API Token)返回)。
GET /api/emails/{id}/pickup-info(取件方式详情)
新增(OpenAPI 1.34.0,向后兼容,无需迁移): 后台邮箱列表每行「取件方式」按钮调用,弹窗展示取件方式说明与解密后的取件凭据(带复制按钮)。
- 支持后台登录会话(Cookie)与 API Token(
Authorization: Bearer/x-api-key);未认证 →401 - 只在点击时实时解密;响应头
Cache-Control: no-store、Pragma: no-cache;不写调用日志;前端关闭弹窗即清空,不写 localStorage - 列表 / 单个邮箱接口仍不返回密码、refresh_token、取件链接
- 不存在 →
404 邮箱不存在;解密失败 →500 取件信息解密失败(<字段名>)…(只报字段名,不含密文 / 明文) - 空字段返回
null;warnings[]提示缺少 client_id / refresh_token / 取件链接等
| provider | method | 取件方式 | 返回的凭据 |
|---|---|---|---|
outlook(含 Hotmail) | oauth_refresh_token | client_id + refresh_token 换访问令牌 → 先 IMAP(XOAUTH2,outlook.office365.com,失败再 imap-mail.outlook.com)→ 失败再 Microsoft Graph Mail.Read;微软轮换 refresh_token 时自动加密写回 | client_id、refresh_token、password(如存在);若该行保存了取件链接则一并返回 fetch_url |
icloud | icloud_fetch_url | 服务端直接请求导入时保存的 https 取件链接(upstream_kind = mail-api / mida) | fetch_url(取件链接,含授权码 / token);password / client_id / refresh_token 为 null |
{
"id": 12, "email": "a@outlook.com", "provider": "outlook",
"method": "oauth_refresh_token", "method_label": "Outlook / Hotmail:OAuth refresh_token 换访问令牌,先 IMAP(XOAUTH2),失败再 Microsoft Graph",
"steps": ["…"], "upstream_kind": null,
"password": "…", "client_id": "…", "refresh_token": "…", "fetch_url": null,
"import_format": "email----password----client_id----refresh_token",
"import_line": "a@outlook.com----…----…----…",
"warnings": []
}
公开取件链接(/api/emails/{id}/pickup-links、/pickup/{token})
新增(OpenAPI 1.37.0,向后兼容,需迁移
0033_email_pickup_links): 给 Outlook / Hotmail 与 iCloud 邮箱生成无需登录的取件链接,把链接发给别人,对方打开即可看到白名单发件人(默认 Meta 系)在时间窗口内的最新验证码。后台邮箱列表每行新增「取件链接」按钮(在「取件方式」旁)。
后台接口(API token 或后台登录会话):
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/emails/{id}/pickup-links | 创建链接,返回 201 与完整 url;同一邮箱可有多条 |
| GET | /api/emails/{id}/pickup-links | 列出该邮箱全部链接(新建在前):完整 url、status、use_count、last_used_at、最近 10 条访问记录 |
| DELETE | /api/emails/{id}/pickup-links/{linkId} | 撤销(软删除,写 revoked_at) |
创建请求体(全部可选):
| 字段 | 默认 | 说明 |
|---|---|---|
expires_in | "24h" | "1h" / "24h" / "7d" / "never"(永久,expires_at 为 null) |
sender_allowlist | Meta 系 | 数组或逗号 / 换行分隔字符串,1–50 项;域名匹配该域及其子域,完整地址精确匹配。默认 facebookmail.com、facebook.com、fb.com、meta.com、metamail.com、instagram.com、mail.instagram.com、threads.net |
window_minutes | 15 | 只看最近多少分钟内到达的邮件,1–1440 |
notes | null | 备注,≤ 500 字符 |
- Outlook 邮箱需已保存
client_id+refresh_token,iCloud 邮箱需已保存取件 URL,否则409;邮箱不存在404;参数无效400 - 不设使用次数上限:链接只受有效期(含永久)、撤销与限频控制
status:active/expired/revokeduse_count:仅统计,取到的不同验证码个数(同一验证码重复获取不计数,缓存命中不计数);last_used_at:最近一次真实读信时间- 访问记录:
created_at、ip_hash(IP 的 HMAC 哈希前 12 位)、user_agent(截断 120 字符)、result(found/not_found/error)、cached;不记录验证码,每条链接保留最近 200 条
{
"id": 3, "email_id": 12, "url": "https://snow.51proxy.org/pickup/<43 位 token>", "status": "active",
"sender_allowlist": ["facebookmail.com", "facebook.com", "fb.com", "meta.com", "metamail.com", "instagram.com", "mail.instagram.com", "threads.net"],
"window_minutes": 15, "expires_at": "2026-10-30T16:00:00+08:00", "use_count": 0,
"last_used_at": null, "revoked_at": null, "notes": null, "created_at": "2026-10-29T16:00:00+08:00", "recent_access": []
}
公开页面 GET /pickup/{token}(无需登录):中英双语 HTML,内联 CSS / JS(CSP nonce,不加载任何外部资源);响应头 Cache-Control: no-store、X-Robots-Tag: noindex, nofollow, noarchive、Referrer-Policy: no-referrer。打开页面本身不查库也不读信(聊天软件的链接预览不会触发读信);页面脚本打开后自动调用下面的公开接口,每 5 秒重试,最多约 90 秒;拿到「页面打开之后到达」的验证码即停止,也可点「获取验证码」重新开始。页面上的到达时间**固定按北京时间(UTC+8)**显示,格式 2026-10-30 17:05:12 北京时间,不依赖访问者浏览器的时区与语言。
公开接口 POST /api/public/pickup/{token}/fetch(无需登录,请求体可选 {"since": <页面打开时间,Unix 毫秒>}):
- 用库里已保存的授权读信:Outlook 先 IMAP、失败回退 Graph(收件箱 + 垃圾邮件各最多 10 封,微软轮换 refresh_token 时加密写回);iCloud 请求已保存的取件 URL
- 只看
sender_allowlist内发件人、window_minutes内到达的邮件;取最新一封中最靠前的验证码。iCloud 优先用上游verification_code;Outlook 从主题 + 摘要提取(识别 Meta 的FB-12345,以及 code / 验证码 / confirmation / security / verification 等关键词附近的 4–8 位数字,忽略链接、邮箱地址、颜色、样式尺寸中的数字),摘要里没有时最多再读 1 封正文(只在服务端用于提取) - 只返回下面这些字段;绝不返回密码、refresh_token、client_id、取件 URL、邮件正文或更早的邮件
{
"email": "a@outlook.com", "status": "found", "code": "48213",
"sender": "Facebook <security@facebookmail.com>", "subject": "FB-48213 is your Facebook confirmation code",
"received_at": "2026-10-29T15:59:00+08:00", "fresh": true,
"fetched_at": "2026-10-29T16:00:00+08:00", "expires_at": "2026-10-30T16:00:00+08:00", "window_minutes": 15
}
status 为 not_found 时不含 code / sender / subject / received_at。fresh:邮件在 since 前 30 秒之后到达(未传 since 恒为 true)。
| 情况 | 响应 |
|---|---|
| token 不存在 / 格式错误 / 已撤销 / 已过期 | 统一 404 {"error":"链接无效或已失效 / Link is invalid or expired"} |
| 同一链接约 3 秒内重复真实读信,或该链接 1 小时内真实读信 ≥ 60 次 | 429,带 retry_after(秒)与 Retry-After |
| 同一 IP(哈希)1 小时内请求 > 300 次,或 10 分钟内无效 token ≥ 20 次(防枚举) | 429 |
| 读信失败 | 502 暂时无法读取邮件,请稍后重试(不透露上游错误细节) |
结果按链接缓存约 5 秒(加密存放),缓存命中不算真实读信。
安全说明:
- token 为 32 字节随机数(base64url,43 字符);库里只存 SHA-256(
token_hash,用于查找)和DATA_ENCRYPTION_KEY加密的一份(token_enc,供后台再次复制),日志与访问记录都不含 token 和验证码 - 持有链接即可取码:请只发给可信的人,用完撤销;尽量设置较短有效期(链接不设使用次数上限)
- token 位于 URL 路径中,可能留在对方浏览器历史 / 聊天记录里;页面设置
Referrer-Policy: no-referrer,不会通过 Referer 外泄 - 发件人白名单只比对
From地址,不校验 DKIM / SPF,伪造发件人的邮件可能通过白名单;页面只显示验证码与主题,不显示正文 - 认证中间件只放行
/pickup/*与/api/public/pickup/*,其余接口鉴权不变(wrangler.toml的run_worker_first新增/pickup/*)
推荐流程
claim {service} → 注册 → 读验证码 → 成功:回写(snowflake / kiro / subscriptions)
→ 失败:release
6. 银行卡与账单地址
⚠️ 不兼容变更(OpenAPI 1.29.0,2026-10-25,无迁移):
- 用 API token 取卡
POST /api/cards/claim必须带locked_by(锁定人,trim 后 1–100 字符),缺少 / 空白 →400 缺少字段: locked_by(锁定人,同一锁定人同时只能锁定一张卡);后台登录会话取卡可省略,缺省记"admin"(同 1.28.0),但 admin 同样受一人一卡限制。API token 调用PATCH /api/cards/{id}/status改为locked时也必须带locked_by(后台登录会话可省略,记"admin")。- 一人一卡:同一锁定人(trim 后、ASCII 不区分大小写)同时只能持有一张领取锁定的卡;还没处理完上一张时再取卡 →
409,提示「请先处理完上一张锁定的卡」并返回locked_card_id,见 6.8。- 银行卡领取锁不再过期:原来的 15 分钟(
LOCK_TTL_MINUTES)自动释放已取消,锁定的卡只能通过 release(失败回写)、订阅回写 / 改为已使用、unlock / 改为可用离开锁定状态。lock_expires_at字段保留但恒为null。LOCK_TTL_MINUTES现在只影响邮箱领取锁(第 5 节)。
⚠️ 不兼容变更(OpenAPI 1.28.0,migration 0028): 取卡
POST /api/cards/claim、失败回写POST /api/cards/{id}/release必须带PATCH /api/cards/{id}/status与POST /api/cards/{id}/unlock用 API token 调用时也必须带400 缺少字段: email(当前使用该卡的账号邮箱),格式无效 →400 email 格式无效(例如 user@example.com,最长 254 个字符),此时不改卡、不写记录。旧调用方(例如不带请求体的取卡)升级后会收到 400,需先补上/api/snowflake-accounts/*,含订阅回写POST /api/snowflake-accounts/{id}/subscription)不变:不要求
认证:Bearer / Cookie(托管绑卡页的 /api/bind/* 见第 8 节)。卡号与 CVC 用 AES-GCM 加密保存;已授权的列表 / 详情 / 领取接口会返回完整卡号与 CVC,请勿在不可信环境调用或记录响应日志。本节示例一律使用 Stripe 公开测试卡号(4242424242424242、4000056655665556、5555555555554444)。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/cards | 列表(limit/cursor;sort=recent|status;status;notes;locked_by;deleted=exclude|include|only) |
| GET | /api/cards/{id} | 单卡详情(含账单地址、锁信息、绑定信息;已删除卡需 include_deleted=true) |
| POST | /api/cards | 单卡写入(可带 notes、expiry、billing_profiles,地址可省略) |
| POST | /api/cards/import | 批量导入:每行 卡号 有效期 CVV 邮编(空格或 Tab 分隔),或 JSON;可带本批 notes |
| POST | /api/cards/claim | 领取一张可用卡并锁定(不过期,需回写或解锁);必填 email;API token 必填 locked_by(后台会话缺省 admin);一人一卡;可选 notes、max_bind_failure_count 筛选 |
| POST | /api/cards/{id}/release | 用 lock_token 释放领取锁,失败次数 +1 |
| POST | /api/cards/{id}/unlock | 管理员强制解锁(临时锁或手动锁),不计失败次数 |
| PATCH | /api/cards/{id}/status | 管理员修改状态:可用 / 已锁定(手动;API token 必填 locked_by)/ 已使用 |
| GET | /api/cards/{id}/history | 该卡的操作历史(时间 / 账号 email / 操作 / 备注),最新在前(6.17) |
| PATCH | /api/cards/{id}/notes | 修改备注 |
| POST | /api/cards/batch-delete | 批量软删除(ids 数组) |
| POST | /api/cards/{id}/billing-profiles/import | 为卡导入 / 更新账单地址 |
| PATCH | /api/cards/{id}/billing-profiles/{profileId} | 切换账单地址 status(available / unavailable) |
| POST | /api/snowflake-accounts/{id}/subscription | 绑卡成功回写:消耗领取锁,卡变为已使用(见第 7 节) |
6.1 状态模型
对外 status 只有三个取值;「已锁定」再用 lock_kind 区分来源,「已删除」是独立的软删除标记(deleted_at),与 status 正交。
| 后台显示 | status | lock_kind | deleted_at | 含义 |
|---|---|---|---|---|
| 可用 | available | null | null | 可被 claim 领取、出现在托管绑卡选卡列表 |
| 已锁定(领取) | locked | claim | null | claim 或托管绑卡选卡产生的锁,带 lock_token;不会自动过期(1.29.0 起),需 release / 改为已使用 / unlock 处理;lock_expires_at 恒为 null |
| 已锁定(手动) | locked | manual | null | 管理员用 PATCH status 锁定,无 lock_token,不会自动过期 |
| 已使用 | used | null | null | 绑卡成功(订阅回写 / 托管绑卡完成)或管理员手动标记,记录 used_at |
| 已删除 | 保留删除前的值 | — | 时间 | 软删除:默认不出现在列表 / 领取 / 选卡 / 统计中,数据保留。没有单独的恢复接口;用 POST /api/cards/import 或 POST /api/cards 重新写入同一卡号即可恢复(规则见 6.7) |
POST /api/cards、/api/cards/import(新卡)
│
▼
┌─────────────────────── 可用 available ◀─────────────────────────┐
│ │ ▲ ▲ │
│ claim / 托管选卡 │ PATCH │ │ release(失败+1) │ PATCH status=available
▼ │ status= │ │ unlock │ 或 unlock
已锁定 locked (claim) ───────┼────────────┼───┘ │
│ ▼ │ │
│ 已锁定 locked (manual)─┘(PATCH status=available / unlock)
│ 订阅回写 / 托管绑卡完成 │
▼ │
已使用 used ─────── PATCH status=available(仅未绑定 Snowflake 账号的卡)───┘
任意非 locked 状态 ──POST /api/cards/batch-delete──▶ 已删除(deleted_at 非空,status 保持原值)
PATCH status可在三种状态间任意切换;改为locked一律是手动锁(lock_kind: "manual")。已绑定 Snowflake 账号的卡不能改回available(409)。- 已锁定(任一种)的卡不能被批量删除,需先
unlock或改为可用。 - 锁定人
locked_by(2026-10-22 起,migration 0024):记录「谁锁的」,规则见 6.16。加锁时写入;释放 / 解锁 / 改为可用 / 变为已使用时都清空,只有锁定中的卡有锁定人。 - 失败次数
bind_failure_count/last_bind_failure_at与状态独立:只有release(以及托管绑卡上报失败)会 +1,改状态、解锁、重复导入都不会清零。
6.2 字段表(列表 / 详情)
| 字段 | 类型 | 说明 |
|---|---|---|
id | integer | 银行卡 ID |
card_number | string | 完整卡号(仅授权接口返回) |
last4 | string | 卡号后 4 位 |
expiry_month / expiry_year | integer | 有效期月 / 四位年 |
cvc | string | CVC / CVV(3–4 位,字段名沿用 cvc) |
holder_name / billing_address | string | null | 旧版单字段持卡人 / 地址,新数据请用 billing_profiles |
status | string | available / locked / used |
lock_kind | string | null | status=locked 时为 claim 或 manual,否则 null |
locked_at | string | null | 领取锁的加锁时间(手动锁为 null) |
lock_expires_at | null | 已废弃,恒为 null(1.29.0 起领取锁不再过期,保留字段只为兼容) |
locked_by | string | null | 锁定人(≤100 字符,见 6.16)。只有 status=locked 的卡可能有值;可用、已使用的卡为 null |
used_at | string | null | 首次标记已使用的时间 |
notes | string | null | 备注(≤500 字符);来源:导入时的本批 notes、单卡写入的 notes、PATCH /api/cards/{id}/notes。列表、详情、领取都返回该字段,没有备注时为 null(不会省略) |
bind_failure_count | integer | 累计绑卡失败次数 |
last_bind_failure_at | string | null | 最近一次失败时间 |
bound_email | string | null | 已绑定的 Snowflake 账号邮箱 |
bound_snowflake_account_id | integer | null | 已绑定的 Snowflake 账号 ID |
billing_profile_id | integer | null | 绑定时使用的账单地址 ID |
deleted | boolean | 是否已软删除 |
deleted_at | string | null | 软删除时间 |
created_at / updated_at | string | 创建 / 最近更新时间 |
billing_profiles | array | 账单地址,见下表(管理接口包含 unavailable 的地址) |
账单地址 billing_profiles[]:id、first_name、last_name、address、country(2 位字母,可为空)、state_province、city、postal_code、status(available / unavailable)。除 id、status 外各字段都可能是空字符串。
时间字段统一为 UTC+8 ISO 8601(如 2026-10-22T10:00:00+08:00),见第 2 节。
6.3 错误码
| HTTP | 典型 error | 场景 |
|---|---|---|
400 | 请求体不是有效的 JSON(claim)、卡号无效、有效期月份无效、expiry 必须为 MMYY、MM/YY 或 MM/YYYY、CVC 无效、status 必须为 available、locked 或 used、increment_bind_failure 必须为布尔值、notes 必须是字符串或 null,且不超过 500 个字符、cursor 无效、deleted 必须为 exclude、include 或 only、缺少字段: email(…)、缺少字段: locked_by(…) | 参数校验失败 |
401 | 未授权 | 缺少或错误的 Bearer / Cookie |
404 | 银行卡不存在 | ID 不存在或卡已软删除(详情可用 include_deleted=true 查看) |
404 | 没有可用银行卡 / 没有符合条件的可用银行卡 | claim 无可领取的卡 |
409 | 该银行卡已存在 | POST /api/cards 卡号与未删除的卡重复(带 existing_id、deleted: false);与已删除的卡重复时会恢复(200,见 6.6) |
409 | 锁不存在或已经失效 | release 的 lock_token 错误、已用过或卡已被解锁 / 改状态 |
409 | 锁定人 X 已有一张锁定中的银行卡 #N,请先处理完上一张锁定的卡… | claim 时该 locked_by 已持有一张领取锁定的卡(带 locked_card_id,见 6.8) |
409 | 银行卡当前未锁定 | unlock 一张非 locked 的卡 |
409 | 该银行卡已绑定 Snowflake 账号 #N,不能改为可用 | PATCH status=available 已绑定的卡 |
415 | 请求必须使用 application/json | 需要 JSON 请求体的接口未带 Content-Type: application/json |
错误响应统一为 { "error": "..." },部分接口附带额外字段(如导入的 errors / results、重复卡的 existing_id)。
6.4 GET /api/cards
| 参数 | 默认 | 说明 |
|---|---|---|
limit | 50 | 1–200 |
sort | recent | recent 按 ID 倒序(游标为卡 ID);status 按 可用 → 已锁定 → 已使用 归类(游标为偏移量)。后台页面默认传 status |
cursor | — | 上一页的 next_cursor |
status | — | available / locked / used |
notes | — | 备注包含匹配(ASCII 不区分大小写) |
locked_by | — | 锁定人包含匹配(ASCII 不区分大小写,≤100 字符)。只有锁定中的卡有锁定人,因此结果都是锁定中的卡 |
deleted | exclude | exclude 不含已删除;include 一并返回;only 只返回已删除 |
每条记录都带 notes(备注,无则 null),后台列表的「备注」列即该字段(长文本截断,悬停显示全文,点击可编辑)。
GET /api/cards?sort=status&limit=50
GET /api/cards?status=available¬es=批次 A
GET /api/cards?deleted=only
GET /api/cards?status=locked&locked_by=worker-01
{
"items": [
{
"id": 12, "card_number": "4242424242424242", "last4": "4242", "expiry_month": 10, "expiry_year": 2028, "cvc": "123",
"holder_name": null, "billing_address": null,
"status": "locked", "lock_kind": "claim", "locked_at": "2026-10-22T10:00:00+08:00", "lock_expires_at": null,
"locked_by": "worker-01", "used_at": null, "notes": "批次 A", "bind_failure_count": 1, "last_bind_failure_at": "2026-10-21T18:00:00+08:00",
"bound_email": null, "bound_snowflake_account_id": null, "billing_profile_id": null,
"deleted": false, "deleted_at": null, "created_at": "2026-10-20T09:00:00+08:00", "updated_at": "2026-10-22T10:00:00+08:00",
"billing_profiles": [
{ "id": 30, "first_name": "", "last_name": "", "address": "", "country": "US", "state_province": "", "city": "", "postal_code": "90001", "status": "available" }
]
}
],
"has_more": true,
"next_cursor": "12"
}
6.5 GET /api/cards/{id}
返回单张卡,字段同列表项。已软删除的卡默认 404(与 status / notes / unlock 等写接口一致);加 ?include_deleted=true 可查看,此时 deleted: true、deleted_at 为删除时间。include_deleted 只接受 true / false。
6.6 POST /api/cards(单卡写入)
{
"card_number": "4242424242424242",
"expiry": "10/28",
"cvc": "123",
"notes": "批次 A",
"billing_profiles": [{ "first_name": "Jane", "last_name": "Doe", "postal_code": "90001", "country": "US" }]
}
- 有效期二选一:
expiry_month+expiry_year(原有字段),或expiry字符串(MMYY/MM/YY/MM/YYYY,与导入一致) notes、billing_profiles、holder_name、billing_address都可省略;地址各字段可为空(country非空时须为 2 位字母)。不传地址时补一条空地址(与批量导入一致),以便出现在托管绑卡选卡列表- 卡号与未删除的卡重复 →
409,不会覆盖旧数据;需要更新有效期 / CVC 请用/api/cards/import - 卡号与已软删除的卡重复(2026-10-22 起)→ 恢复该卡,返回
200(不是201,因为没有新建):created: false、restored: true、id为原卡 ID、status为恢复后的状态。规则与批量导入恢复一致(6.7):新有效期 / CVC 覆盖;notes、holder_name、billing_address只在本次传了时覆盖;billing_profiles追加(重复地址忽略),不传且该卡没有任何地址时才补空地址;失败次数保留;状态按原样保留(used仍used,未绑定的locked清锁改为available)
// 201 新建
{ "id": 12, "created": true, "status": "available", "notes": "批次 A", "billing_profiles_created": 1 }
// 200 恢复已删除的同号卡
{ "id": 9, "created": false, "restored": true, "status": "used", "notes": "批次 A", "billing_profiles_created": 0 }
// 409 与未删除的卡重复
{ "error": "该银行卡已存在", "existing_id": 12, "deleted": false }
6.7 POST /api/cards/import(批量导入)
文本格式(推荐,可直接从表格复制):data 为字符串,每行一张卡,列之间用空格或 Tab 分隔(可混用):
4242424242424242 1028 123 90001
4000056655665556 0329 456 10001
5555555555554444 1230 789
| 列 | 必填 | 规则 |
|---|---|---|
| 卡号 | 是 | 12–19 位数字,可带连字符,做 Luhn 校验;不能带空格(4242 4242 4242 4242 会被拆成多列 → 格式错误) |
| 有效期 | 是 | MMYY(1028 = 2028 年 10 月),也接受 MM/YY、MM/YYYY;不能已过期 |
| CVV | 是 | 3–4 位数字 |
| 邮编 | 否 | 5 位美国邮编(可带 -1234),可省略或为空单元格;有邮编时生成一条只含邮编、country: "US" 的账单地址,其余字段留空,在托管绑卡页人工补全 |
分列规则:
- 先去掉行首尾空白(含 Tab);空行忽略
- 行内有 Tab:按单个 Tab 切列,连续 Tab 产生空单元格并保留列位置(与表格对齐);各单元格去掉首尾空白后,若内部还有空白(Tab 与空格混用,如
卡号 1028<Tab>123<Tab>90001),再按空白拆成多列 - 行内没有 Tab:按任意连续空白切列(多个空格算一个分隔)
- 行尾的空列忽略;邮编为空等同于不填邮编
- 卡号 / 有效期 / CVV 为空 → 该行失败,错误为
卡号为空/有效期为空/CVV为空(不会把后面的列前移错位)。有 Tab 的行缺少前 3 列时同样报对应列为空(如卡号<Tab>1028→CVV为空) - 列数超过 4(含按位置第 5 列有值)或无 Tab 且不足 3 列 →
格式错误,应为「卡号 有效期 CVV 邮编(空格或 Tab 分隔)」 - 邮编中间不能有空格(
90001 1234会被当成多一列 → 格式错误),ZIP+4 请写90001-1234
同一批内重复卡号记为失败;单次最多 500 张。
{ "data": "4242424242424242\t1028\t123\t90001\n4000056655665556\t0329\t456", "notes": "2026-10-22 批次 A" }
JSON 格式(旧格式,保持兼容):数组,或 { "data": [...] } / { "data": "<JSON 字符串>" }:
[
{
"card": { "card_number": "4242424242424242", "expiry": "12/30", "cvc": "123" },
"billing_profiles": [
{ "first_name": "Jane", "last_name": "Doe", "address": "1 Main St", "country": "US", "state_province": "CA", "city": "Los Angeles", "postal_code": "90001" }
]
}
]
billing_profiles 可省略或为空;没有任何账单地址的新卡会补一条空地址。
备注:可选 notes(≤500 字符)写到本批每张卡上。
重复导入已存在的卡(按卡号判断):更新卡号密文、有效期、CVC,追加尚不存在的账单地址(有邮编时按上面的规则追加);本批填写了 notes 时覆盖旧备注,未填写则保留;失败次数 bind_failure_count / last_bind_failure_at 始终保留。
- 未删除的卡:状态和锁都不变(与以前一致)
- 已软删除的卡(2026-10-22 起自动恢复):只恢复为未删除,状态基本按原样保留——清空
deleted_at;原used保持used(不论是否绑定,不会被领取)、原available保持available;原locked且未绑定 Snowflake 账号的清除锁(lock_token/locked_at/locked_by)并改为available,已绑定的卡状态与锁保持原状。失败次数、used_at都保留。有效期 / CVC 覆盖、备注与地址规则同上。该行带deleted: true(导入前是已删除的卡)、restored: true和恢复后的restored_status,分别计入cards_deleted_existing和cards_restored;action仍为updated,并计入cards_updated - 只有恢复后为
available的卡才会再被领取 / 用于托管绑卡选卡;恢复后仍为used的卡要重新启用,需另外调用PATCH /api/cards/{id}/status改为available - 同一批里重复的卡号:第二次出现的行按「卡号与本批前面的行重复」记为失败,恢复只计一次
逐行结果:有效行照常导入,失败行不影响其他行。错误只显示行号(JSON 为项号)和卡号尾号,不回显完整卡号或 CVV。
{
"format": "text",
"cards_processed": 2, "cards_created": 1, "cards_updated": 1, "cards_failed": 1, "cards_deleted_existing": 0, "cards_restored": 0,
"billing_profiles_imported": 2,
"notes": "2026-10-22 批次 A",
"errors": ["第 3 行(尾号 4241):卡号无效"],
"results": [
{ "row": 1, "last4": "4242", "ok": true, "action": "created" },
{ "row": 2, "last4": "5556", "ok": true, "action": "updated" },
{ "row": 3, "last4": "4241", "ok": false, "error": "卡号无效" }
]
}
成功返回 201;全部行都失败时返回 400,响应同样带 error、errors、results。
6.8 POST /api/cards/claim(领取)
请求体必填,至少要有 email(1.28.0 起);API token 调用还必须带 locked_by(1.29.0 起),均为不兼容变更。后台登录会话可不传 locked_by,缺省记 "admin"。不带请求体、{}、或非 JSON 请求 → 400 缺少字段: email(当前使用该卡的账号邮箱);API token 调用有 email 没有 locked_by → 400 缺少字段: locked_by(锁定人,同一锁定人同时只能锁定一张卡),不会领取任何卡。成功领取时与加锁在同一事务里写一条 claim 操作记录;400、无卡可领(404)不写记录。
领取锁不过期(1.29.0 起):领到的卡一直保持锁定,直到你处理它——绑卡成功调订阅回写(或 PATCH status=used)、绑卡失败调 release、不用了调 unlock / PATCH status=available。响应里的 lock_expires_at 恒为 null。
一人一卡(1.29.0 起):同一 locked_by(trim 后、ASCII 不区分大小写,Worker-01 与 worker-01 视为同一人)同时只能持有一张 status=locked、未删除、带 lock_token 的卡。还持有上一张时再取卡 → 409,请先处理完上一张锁定的卡(release / 改为已使用 / 解锁),之后即可再取:
{ "error": "锁定人 worker-01 已有一张锁定中的银行卡 #12,请先处理完上一张锁定的卡(失败回写 release、改为已使用或解锁)后再取卡", "locked_card_id": 12 }
- 409 只返回已持有卡的 ID,不返回卡号、CVC、
lock_token;即使此时已没有可领的卡,也先返回 409 - 409 会在已持有的卡上写一条
operation = claim、result = rejected的操作记录(6.17),email 为本次请求的 email - 「检查是否已持有」与加锁在同一条 UPDATE 里完成,并发的多次同人取卡最多一次成功,其余 409
- 不计入:手动锁定(
PATCH status=locked,没有lock_token)、托管绑卡页选卡锁(snowflake_accounts:{id},不受此限制)、历史上locked_by为空的锁、已软删除的卡
选卡顺序(在 status = available 且未删除,以及可选的 notes / max_bind_failure_count 筛选之后):
bind_failure_count ASC— 优先失败次数少的;last_bind_failure_at ASC— 次数相同时优先更早失败的(「冷却」更久);NULL(从未失败,或异常地有次数但无时间)按 SQLite ASC 排在有时间戳之前,即当作最旧;id ASC— 次数与时间都相同(或都为NULL)时按 ID 升序兜底。
{ "email": "user@example.com", "notes": "批次 A", "max_bind_failure_count": 2, "locked_by": "worker-01" }
| 字段 | 说明 |
|---|---|
email | 必填。当前使用该卡的账号邮箱:trim 后转小写保存,≤254 字符,须形如 user@example.com。只用于操作记录,不要求与 Snowflake 账号邮箱一致,也不会自动作为 locked_by |
notes | 只领取备注包含该字符串的卡(同列表 notes 筛选) |
max_bind_failure_count | 只领取失败次数 ≤ 该值的卡(非负整数) |
locked_by | API token 调用必填(1.29.0 起)。锁定人,字符串,trim 后 1–100 字符;API token 调用缺少 / null / 空白 → 400 缺少字段: locked_by(锁定人,同一锁定人同时只能锁定一张卡);后台登录会话缺少 / null / 空白时记 "admin",admin 与其他锁定人一样同时只能持有一张领取锁定的卡;非字符串或超长 → 400 locked_by 必须为字符串,最多 100 个字符。同一锁定人同时只能持有一张领取锁定的卡(见上) |
只领取 status = available 且未删除的卡。成功返回 200:
{
"id": 12, "card_number": "4242424242424242", "expiry_month": 10, "expiry_year": 2028, "cvc": "123",
"holder_name": null, "billing_address": null, "bind_failure_count": 0, "last_bind_failure_at": null,
"billing_profiles": [{ "id": 30, "first_name": "", "last_name": "", "address": "", "country": "US", "state_province": "", "city": "", "postal_code": "90001", "status": "available" }],
"lock_token": "8f2c…", "locked_at": "2026-10-22T10:00:00+08:00", "lock_expires_at": null,
"status": "locked", "lock_kind": "claim", "locked_by": "worker-01", "notes": "批次 A", "email": "user@example.com"
}
billing_profiles 只包含 available 的地址,地址字段可能为空字符串。无可领取的卡 → 404(带筛选时为 没有符合条件的可用银行卡);该锁定人已持有锁定卡 → 409(见上)。
6.9 POST /api/cards/{id}/release(失败回写)
绑卡失败时调用,释放领取锁并原子地 bind_failure_count + 1。重复调用或令牌失效不会重复计数。
{ "lock_token": "<领取时的 lock_token>", "email": "user@example.com" }
{ "released": true, "failure_recorded": true, "id": 12, "status": "available", "bind_failure_count": 1, "last_bind_failure_at": "2026-10-22T10:05:00+08:00", "email": "user@example.com" }
email 必填(规则同 6.8)。成功时与释放在同一事务里写一条 fail 操作记录。令牌错误 / 已过期 / 已用过 → 409 锁不存在或已经失效,卡存在时另写一条 result = rejected 的记录(卡状态不变)。
6.10 POST /api/cards/{id}/unlock
管理员强制释放锁(临时锁或手动锁),同时清除未完成托管绑卡会话对该卡的选择,不计失败次数。请求体 {"email": "user@example.com"}:API token 调用 email 必填;后台登录会话可传 {}(记录里 email 为 null)。成功时同一事务写 unlock 操作记录;卡未锁定(409)时写 result = rejected 记录。
{ "released": true, "id": 12, "status": "available", "previous_lock_kind": "claim", "previous_locked_by": "worker-01", "email": "user@example.com" }
locked_by 被清空;previous_locked_by 为解锁前的锁定人(可能为 null)。
卡不存在或已删除 → 404;卡未锁定 → 409。
6.11 PATCH /api/cards/{id}/status
{ "status": "locked", "increment_bind_failure": true, "locked_by": "alice", "email": "user@example.com" }
| 字段 | 必填 | 说明 |
|---|---|---|
status | 是 | available / locked / used |
email | API token 调用必填 | 当前账号邮箱(规则同 6.8);后台登录会话可省略。每次成功调用写一条操作记录:increment_bind_failure=true → fail(回写失败);改为 used → complete(回写完成);其他 → status。已绑定卡改为可用(409)写 result = rejected 记录 |
locked_by | 改为 locked 时 API token 调用必填(1.29.0 起) | 锁定人,只能在 status=locked 时传(其他状态传了 → 400 locked_by 只能在 status=locked 时传)。字符串,trim 后 ≤100 字符。改为 locked 时:API token 调用缺少 / 空白 → 400 缺少字段: locked_by(锁定人,同一锁定人同时只能锁定一张卡);后台登录会话可省略,记 "admin"。总是覆盖原锁定人(包括领取锁转手动锁)。手动锁定不受一人一卡限制,也不计入取卡的一人一卡检查 |
increment_bind_failure | 否 | 布尔值,默认 false。为 true 时在同一条 UPDATE 里把 bind_failure_count +1 并更新 last_bind_failure_at(与改状态原子完成);不传或 false 时失败次数不变。非布尔值(如 "true"、1、null)→ 400 increment_bind_failure 必须为布尔值 |
available:清除锁(含locked_by),并清除未完成托管绑卡会话中对该卡的选择;已绑定 Snowflake 账号的卡 →409(此时不会 +1)locked:手动锁定(lock_kind: "manual"),不会自动过期;原来是领取临时锁的会转为手动锁(lock_token失效)used:标记已使用(首次记录used_at),清空locked_by- 与当前状态相同也照常处理(返回
200,previous_status等于status),因此{"status": "<当前状态>", "increment_bind_failure": true}等于「只把失败次数 +1」 - 卡不存在或已删除 →
404(不会 +1);所有校验都在更新前完成,失败的请求不会改动失败次数
{ "id": 12, "status": "locked", "used_at": null, "bind_failure_count": 2, "last_bind_failure_at": "2026-10-22T11:20:00+08:00",
"locked_by": "alice", "previous_status": "available", "lock_kind": "manual", "updated": true, "failure_recorded": true, "email": "user@example.com" }
failure_recorded:本次请求是否把失败次数 +1(不传或 false 时为 false)。
6.12 PATCH /api/cards/{id}/notes
{ "notes": "新的备注" }
notes 为字符串(≤500,空串视为清空)或 null。响应 { "id": 12, "notes": "新的备注", "updated": true }。
6.13 POST /api/cards/batch-delete(软删除)
ids 为银行卡 ID 数组(正整数,1–500 个,重复自动去重)。已锁定(临时锁或手动锁)的卡会被跳过;已删除或不存在的 ID 不报错,分别列出。
{ "ids": [12, 13, 14] }
{ "requested": 3, "deleted": 1, "deleted_ids": [12], "skipped_locked_ids": [13], "already_deleted_ids": [], "not_found_ids": [14] }
已删除的卡:不出现在默认列表(deleted=include|only 可查)、不会被领取、不出现在托管绑卡选卡、不计入 /api/stats 的 cards_total / cards_available / cards_locked / cards_used(单独计入 cards_deleted);对其调用详情(未带 include_deleted)、unlock、status、notes、billing-profiles/import、billing-profiles/{profileId} 均返回 404。要恢复,用 POST /api/cards/import 重新导入或 POST /api/cards 重新写入同一卡号(规则见 6.7;恢复后 used 仍为 used)。已绑定 Snowflake 账号的历史记录不受影响,Snowflake 账号列表会以 card_deleted: 1 标出。
6.14 账单地址
POST /api/cards/{id}/billing-profiles/import:请求体为地址数组,或 { "data": [...] }。重复地址(按内容判断)更新资料及状态。
[{ "first_name": "Jane", "last_name": "Doe", "address": "1 Main St", "country": "US", "state_province": "CA", "city": "Los Angeles", "postal_code": "90001", "status": "available" }]
{ "card_id": 12, "billing_profiles_processed": 1, "errors": [] }
PATCH /api/cards/{id}/billing-profiles/{profileId}:{ "status": "unavailable" },响应 { "updated": true, "card_id": 12, "id": 30, "status": "unavailable" }。不可用地址仍显示在管理列表 / 详情中,但不会出现在领取结果和绑卡选卡界面。卡已删除 → 404 银行卡不存在;地址不属于该卡 → 404 账单信息不存在。
6.15 典型流程:导入 → 领取 → 绑卡 → 回写 / 释放
# 1. 导入(文本格式,本批备注)
curl -X POST https://snow.51proxy.org/api/cards/import -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"data":"4242424242424242\t1028\t123\t90001","notes":"批次 A"}'
# 2. 领取(可只取本批、失败次数 ≤ 2 的卡)
curl -X POST https://snow.51proxy.org/api/cards/claim -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"email":"user@example.com","locked_by":"worker-01","notes":"批次 A","max_bind_failure_count":2}'
# => {"id":12,"card_number":"4242424242424242",...,"lock_token":"8f2c…","lock_expires_at":null,"locked_by":"worker-01","email":"user@example.com"}
# 同一 worker-01 在处理完这张卡之前再取卡 → 409 {"error":"…请先处理完上一张锁定的卡…","locked_card_id":12}
# 3a. 在 Snowflake 绑卡成功 → 回写订阅(卡变为 used,锁被消耗;锁不过期,但请尽快回写)
curl -X POST https://snow.51proxy.org/api/snowflake-accounts/34/subscription -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"card_id":12,"card_lock_token":"8f2c…","billing_profile_id":30,"subscription_status":"active"}'
# => {"id":5,"updated":true,"subscription_status":"active","billing_profile_id":30,"bound_email":"user@example.com","card_id":12,"card_status":"used"}
# (Snowflake 账号接口,不要求 email,也不写卡操作记录)
# 3b. 绑卡失败 → 释放并记录失败次数(卡回到可用,可被再次领取)
curl -X POST https://snow.51proxy.org/api/cards/12/release -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"lock_token":"8f2c…","email":"user@example.com"}'
# 4. 查看这张卡的操作历史(取卡 → 回写失败 / 改状态 / 解锁等)
curl https://snow.51proxy.org/api/cards/12/history -H "Authorization: Bearer $API_TOKEN"
如果绑卡失败但不想让卡回到可用(例如怀疑卡有问题,要先锁住人工排查,或直接标记为已使用),或者是手动锁定的卡(没有 lock_token,无法 release),请改用 PATCH /api/cards/{id}/status 并带 "increment_bind_failure": true:一次请求同时完成改状态和失败次数 +1。例如 {"status":"locked","increment_bind_failure":true,"locked_by":"worker-01","email":"user@example.com"}(API token 改为 locked 须带 locked_by)。
不想自动化取卡时,可用托管绑卡链接(第 8 节):/api/bind/{id}/cards 会列出地址为空或只有邮编的卡,选卡后只预填已有字段(国家为空时默认 US),其余地址在页面人工填写;POST /api/bind/{id}/complete 仍要求提交完整账单资料(姓名、地址、城市、州、邮编、国家)。
6.16 锁定人 locked_by
2026-10-22 起(migration 0024 新增可空列 cards.locked_by,向后兼容;之前的锁没有锁定人,均为 null)。
| 何时 | locked_by |
|---|---|
POST /api/cards/claim | 请求体 locked_by;API token 调用必填(1.29.0 起),后台登录会话未传为 "admin"(同样受一人一卡限制) |
PATCH /api/cards/{id}/status 改为 locked | 请求体 locked_by;API token 调用必填(1.29.0 起),后台登录会话未传为 "admin"。总是覆盖原值 |
托管绑卡页面选卡(/api/bind/{id}/card-selection,无登录身份) | snowflake_accounts:{Snowflake 账号 ID} |
release(失败回写)、unlock、PATCH status=available、托管绑卡失败 | 清空为 null(1.29.0 起领取锁不会因超时被释放) |
订阅回写 / 托管绑卡完成 / PATCH status=used(任何变为已使用的路径) | 清空为 null(不保留为使用人) |
| 已删卡被重新导入 / 写入而恢复(6.7) | 恢复后不是 locked 的卡清空(含未绑定的 locked → available);只有已绑定、保持 locked 的卡保留 |
- 取值:字符串,trim 后 1–100 字符;空白、
null、不传都视为未传(取卡时即 400)。任意文本,建议用稳定的程序名 / 机器名 / 人名,便于筛选 - 一人一卡(1.29.0 起):按 trim 后、ASCII 不区分大小写比较,同一锁定人同时只能持有一张领取锁(有
lock_token)的卡,规则见 6.8。手动锁定与托管绑卡选卡锁不计入 - 后台登录只有一个共享密码、没有用户名,所以会话调用
claim/PATCH status=locked不传时默认值固定为"admin"(claim时 admin 也只能同时持有一张领取锁定的卡);后台「改状态 → 已锁定」会弹窗询问锁定人,留空即为"admin" - 列表 / 详情 / 领取响应都返回
locked_by;列表可按locked_by包含匹配筛选(6.4) - 邮箱领取(
email_locks)目前没有锁定人字段,本次未改动 locked_by与操作记录的email互相独立:不传locked_by时不会用email代替
6.17 银行卡操作历史 GET /api/cards/{id}/history
2026-10-25 起(migration 0028 新增表 card_operation_logs,OpenAPI 1.28.0)。取卡与回写(完成 / 失败)等每次调用都会写一条操作记录;管理后台银行卡列表每行的「操作历史」按钮弹窗展示(时间 / 账号 email / 操作 / 备注 / 来源,最新在前)。
操作 operation | 后台显示 | 何时写入 |
|---|---|---|
claim | 取卡 | POST /api/cards/claim 成功;托管绑卡页选卡(/api/bind/{id}/card-selection) |
complete | 回写完成 | PATCH /api/cards/{id}/status 改为 used;托管绑卡完成(/api/bind/{id}/complete)。订阅回写 POST /api/snowflake-accounts/{id}/subscription 属于 Snowflake 账号接口,不写记录 |
fail | 回写失败 | POST /api/cards/{id}/release;PATCH 带 increment_bind_failure=true;托管绑卡失败 |
unlock | 释放锁定 | POST /api/cards/{id}/unlock |
status | 修改状态 | PATCH /api/cards/{id}/status 改为 available / locked(不计失败次数时) |
expire | 锁超时释放(已停用) | 1.29.0 起不再产生(领取锁不再过期);仅保留以显示此前的历史记录:领取锁超过 LOCK_TTL_MINUTES 未回写、被系统自动释放(source = system,email 取该卡最近一次成功 claim 的 email) |
email:取卡 / release 必填;PATCH status、unlock仅 API token 调用必填;托管绑卡记 Snowflake 账号邮箱;后台登录会话未传时为null。保存前 trim + 转小写result:ok成功;rejected已存在的卡上被拒绝的调用(HTTP 409:锁失效、状态冲突、已绑定的卡改为可用、一人一卡取卡被拒等),卡状态未改变,detail为「HTTP 状态码 错误信息」。不记录:参数校验失败(400 / 415,包括缺少 / 无效 email、JSON 无效,claim 的 400 也不记)、卡不存在(404)、无卡可领、Snowflake 账号接口的所有调用source:api_token/session(后台登录)/bind_session(托管绑卡页)/system- 一致性:成功记录与卡状态变更在同一个 D1 batch(事务)里写入,任一条失败则整体回滚;被拒绝的记录单独尽力写入
- 不含敏感数据:记录只有
card_id,不含卡号、CVC、lock_token - 永久保存:记录跟随银行卡永久保留。软删除 / 重新导入不清理;
card_id不设外键,即使直接在库里硬删卡也不会级联删除记录;没有任何清理任务。已软删除的卡仍可查询历史(deleted: true)
参数:limit(1–200,默认 50)、cursor(上一页的 next_cursor)。认证:Bearer / Cookie。卡不存在 → 404 银行卡不存在;limit / cursor 无效 → 400。
{
"card_id": 12, "last4": "4242", "status": "used", "deleted": false, "next_cursor": null,
"items": [
{ "id": 31, "card_id": 12, "created_at": "2026-10-25T10:05:00+08:00", "email": "user@example.com", "operation": "complete", "result": "ok",
"source": "api_token", "endpoint": "PATCH /api/cards/{id}/status", "status_before": "locked", "status_after": "used",
"detail": "改为 used" },
{ "id": 30, "card_id": 12, "created_at": "2026-10-25T10:01:00+08:00", "email": "user@example.com", "operation": "claim", "result": "ok",
"source": "api_token", "endpoint": "POST /api/cards/claim", "status_before": "available", "status_after": "locked", "detail": "领取并临时锁定" }
]
}
7. Snowflake 账号
认证:Bearer / Cookie。密码、Snowsight 会话、TOTP seed、注册元数据等敏感字段加密保存;已授权列表会返回解密后的密码等字段。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/muse-assets | Muse 资产列表(明文 api_key / access_token,可按状态、邮箱、created_by、备注筛选) |
| POST | /api/muse-assets | 上传一条 Muse 资产(同 email + api_key 已存在则更新 access_token) |
| POST | /api/muse-assets/import | 批量上传 Muse 资产(JSON 或每行 email api_key access_token;已存在的更新 access_token) |
| GET | /api/muse-assets/{id} | Muse 资产详情 |
| PATCH | /api/muse-assets/{id} | 修改 Muse 资产(状态、备注、created_by、关联银行卡号 card_number 等) |
| POST | /api/muse-assets/batch-status | 批量修改 Muse 资产状态 |
| POST | /api/muse-assets/batch-delete | 批量软删除 Muse 资产 |
| GET / POST | /api/muse-assets/export | 导出 TSV(email api_key access_token,Tab 分隔) |
| GET | /api/muse-assets/logs | Muse 资产 API 调用日志(写操作摘要,已脱敏) |
| GET | /api/snowflake-accounts | 列表(limit/cursor) |
| POST | /api/snowflake-accounts | 注册回写(需 email_id + email_lock_token,自动记 snowflake 订阅) |
| POST | /api/snowflake-accounts/import | 手工导入(可带 registration_metadata) |
| GET | /api/snowflake-accounts/export-bound | 导出绑卡记录(payment_status=bound|unbound) |
| PATCH | /api/snowflake-accounts/{id}/notes | 更新备注 |
| GET | /api/snowflake-accounts/{id}/registration-metadata | 解密返回注册元数据 |
| GET | /api/snowflake-accounts/{id}/totp | 当前 TOTP 验证码 |
| POST | /api/snowflake-accounts/{id}/subscription | 记录订阅/绑卡结果 |
| POST | /api/snowflake-accounts/{id}/bind-session | 创建托管人工绑卡会话,返回 magic_url |
| PUT | /api/snowflake-accounts/{id}/snowsight-auth | 写入/更新 Snowsight 认证 |
| POST | /api/snowflake-accounts/{id}/refresh-snowsight-auth | 用账号密码刷新认证 |
| GET | /api/snowflake-accounts/{id}/payment-method-status | 查询是否已绑卡 |
POST /api/snowflake-accounts(回写示例)
{
"email_id": 12,
"email_lock_token": "<claim 返回的 lock_token>",
"username": "USER1",
"password": "<snowflake-password>",
"account_name": "ORG-ACCOUNT1",
"host": "acct1.us-east-1.snowflakecomputing.com",
"region": "us-east-1",
"totp_seed": "<optional-base32>",
"registration_metadata": {
"schema_version": 1,
"captured_at": "2026-10-20T04:00:00Z",
"browser": { "engine": "chrome", "version": "130.0", "fingerprint_id": "fp-1", "fingerprint": { "userAgent": "…" } },
"network": { "proxy": "socks5://proxy.example:1080", "exit_ip": "203.0.113.10" }
}
}
邮箱锁须来自 {"service":"snowflake"} 或不带 service 的领取;成功后锁被消耗并记录 snowflake 订阅。
列表中的银行卡信息:card_number 只显示尾号(**** **** **** 4242),card_id 为绑定的银行卡 ID,card_deleted 为 1 表示该卡之后已被软删除(未绑卡时两者均为 null),可用 GET /api/cards/{id}?include_deleted=true 查看。
POST /api/snowflake-accounts/{id}/subscription(绑卡成功回写)
{ "card_id": 12, "card_lock_token": "<POST /api/cards/claim 返回的 lock_token>", "billing_profile_id": 30, "subscription_status": "active" }
校验并消耗银行卡领取锁,与订阅记录在同一个 D1 batch 中把卡置为 used。billing_profile_id 可选,须属于该卡。成功 201:
{ "id": 5, "updated": true, "subscription_status": "active", "billing_profile_id": 30, "bound_email": "user@example.com", "card_id": 12, "card_status": "used" }
相同账号 + 相同卡重复提交返回 200 且 idempotent: true;锁失效 → 409 银行卡锁不存在或已经失效;账号已绑其他卡 → 409。
POST /api/snowflake-accounts/{id}/bind-session
{ "ttl_seconds": 600 }
{
"bind_session_id": "<uuid>",
"magic_url": "https://snow.51proxy.org/bind?…",
"expires_in": 600
}
8. 托管人工绑卡(magic link)
这些接口不使用 API Token,而是校验绑卡页携带的短期 X-Bind-Token(或等价会话参数)。面向终端用户打开的 /bind 页面。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/bind/{id}/bootstrap | 初始化绑卡页(Stripe publishable key、账号摘要等) |
| GET | /api/bind/{id}/cards | 可选银行卡列表 |
| POST | /api/bind/{id}/card-selection | 选定卡与账单地址并锁定 |
| POST | /api/bind/{id}/complete | 提交 Stripe PaymentMethod,完成绑定 |
{id} 为绑卡会话 UUID。会话过期或 Token 无效 → 401/404/409(视具体状态)。
9. Kiro 账号
认证:Bearer / Cookie。密码与 AccessToken / RefreshToken / mfaSecret 加密保存;已授权列表返回解密值。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/kiro-accounts | 列表(limit/cursor) |
| POST | /api/kiro-accounts | 单条写入 |
| POST | /api/kiro-accounts/import | 批量导入(JSON 数组 / 对象 / NDJSON,≤500) |
| POST | /api/kiro-accounts/callback | 外部注册回写 + 记 kiro 订阅(需邮箱锁) |
| POST | /api/kiro-accounts/{id}/refresh-status | 刷新 Plan / Credits(访问 Kiro Web Portal) |
POST /api/kiro-accounts/callback
{
"email_id": 12,
"email_lock_token": "<claim 返回的 lock_token>",
"password": "<kiro-password>",
"AccessToken": "<optional>",
"RefreshToken": "<optional>",
"mfaSecret": "<optional>",
"UserId": "<optional>"
}
锁须来自 {"service":"kiro"} 或不带 service 的领取;同邮箱重复回写幂等。
10. MuseCode 账号
本章合并原
docs/MUSECODE_API.md;请以本文为准。
新增(OpenAPI 1.31.0,向后兼容,无需迁移): 列表新增筛选
notes(备注包含)与has_bank_card_last4=true|false;新增导出接口GET / POST /api/musecode-accounts/export(CSV,可选列,按筛选或勾选的 ids 导出),见下文「导出 CSV」。
新增(OpenAPI 1.30.0,向后兼容,需 migration 0029): 账号新增可选字段
bank_card_last4(银行卡尾号,只存 4 位数字)。创建 / 回写 / 批量导入可选传入,列表与详情输出,列表可按bank_card_last4精确筛选;新增单独更新接口PUT /api/musecode-accounts/{id}/bank-card-last4与按邮箱版本PUT /api/musecode-accounts/by-email/{email}/bank-card-last4;PATCH /api/musecode-accounts/{id}也支持。
本文面向调用方(外部注册程序、运维脚本)。所有接口与其他 /api/* 相同:请求头 Authorization: Bearer <API_TOKEN>,或管理后台登录 Cookie。未认证返回 401。
时间约定:数据库以 UTC 存储;响应中的时间一律为北京时间 +08:00(如 2026-10-19T12:00:00+08:00)。请求中的时间接受 ISO 8601:带时区(Z / +08:00)按其时区;不带时区(2026-10-19T12:00、2026-10-19 12:00:00)或纯日期(2026-10-19)按北京时间解释。
数据模型
| 字段 | 类型 | 说明 |
|---|---|---|
id | integer | 自增主键 |
email | string | 邮箱,统一存小写,大小写不敏感唯一 |
email_id | integer / null | 关联的邮箱库存 ID。创建时若邮箱在库存中自动关联;库存邮箱被删除后置为 null |
meta_user_id | string / null | MuseCode 侧用户 ID,最长 128;非空时唯一,可多个账号为空 |
registered_at | string | 注册时间,创建时可省略(当前时间) |
notes | string / null | 备注,最长 2000 |
bank_card_last4 | string / null | 银行卡尾号(1.30.0 起,migration 0029):恰好 4 位数字的字符串(如 "4242",保留前导 0),只存后 4 位,不存完整卡号,不关联银行卡库;null = 未填。与 Muse 资产的 card_number / card_last4 无关 |
subscription_status | string | 账号自身套餐状态:none(默认)/ trialing / active / past_due / cancelled / expired(拼写与 Snowflake subscription_bindings 对齐) |
subscription_plan | string / null | 套餐名,自由文本 ≤128,如 pro |
subscription_started_at | string / null | 订阅开始(UTC 存,API 出 +08:00) |
subscription_expires_at | string / null | 订阅到期 |
subscription_updated_at | string / null | 最近一次套餐字段更新时间(只读,写套餐时自动刷新) |
subscription_meta | object / null | 明文 JSON ≤16KB,放供应商原始字段;勿放密钥 |
browser_fingerprint | object / null | 注册时的浏览器指纹,任意 JSON 对象,≤64KB,明文保存(仅详情返回完整内容) |
proxy_ip | string / null | 代理出口 IP(IPv4 / IPv6,IPv6 存小写) |
proxy_geo | object / null | 代理出口地理位置,≤8KB(键见下) |
proxy_country | string / null | 只读,取自 proxy_geo.country_code(大写),用于筛选 |
proxy_index | string / null | 代理池索引 / 标识,≤128;整数会转成字符串(如 17 → "17"),便于兼容 pool-a:17 这类写法 |
auth_data | object / null | 注册时的认证会话(cookies、storage、tokens、headers),≤1.4MB(明文 JSON;加密后约 ≤1.87MB,受 D1 单值/单行 2MB 上限约束),AES-GCM 加密保存(DATA_ENCRYPTION_KEY),只在详情接口解密返回 |
has_browser_fingerprint / has_auth_data | boolean | 只读,是否保存了指纹 / 认证信息 |
fingerprint_summary | object / null | 只读,从指纹提取的 user_agent、platform、timezone、language |
auth_updated_at | string / null | 只读,最近一次写入 auth_data 的时间(清除时为 null) |
created_at / updated_at | string | 记录创建 / 最后修改时间 |
注册上下文字段
{
"browser_fingerprint": {
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/130.0 Safari/537.36",
"platform": "Win32",
"language": "en-US",
"languages": ["en-US", "en"],
"timezone": "America/Los_Angeles",
"screen": { "width": 1920, "height": 1080, "pixel_ratio": 1, "color_depth": 24 },
"webgl": { "vendor": "Google Inc. (NVIDIA)", "renderer": "ANGLE (NVIDIA GeForce RTX 3060)" },
"canvas_hash": "c4a1f0…",
"audio_hash": "9b2e…",
"fonts": ["Arial", "Segoe UI"],
"hardware_concurrency": 8,
"device_memory": 8
},
"proxy_ip": "203.0.113.7",
"proxy_geo": {
"country_code": "US", "country": "United States", "region": "California", "city": "Los Angeles",
"latitude": 34.05, "longitude": -118.24, "timezone": "America/Los_Angeles",
"isp": "Example ISP", "asn": "AS64500", "org": "Example Hosting"
},
"proxy_index": "pool-a:17",
"auth_data": {
"cookies": [
{ "name": "session", "value": "…", "domain": ".musecode.example", "path": "/",
"expires": 1793000000, "httpOnly": true, "secure": true, "sameSite": "Lax" }
],
"localStorage": { "auth.token": "…" },
"sessionStorage": {},
"tokens": { "access_token": "…", "refresh_token": "…", "session_token": "…" },
"headers": { "x-device-id": "…" }
}
}
校验规则:
- 三个 JSON 字段都必须是对象(不能是数组或字符串);超过大小上限(按 UTF-8 字节计算)返回 400。
browser_fingerprint、proxy_geo、auth_data中除下述约束外允许任意键,原样保存、原样返回(内部的时间字段不做时区转换)。proxy_geo.country_code必须是两位字母;latitude∈ [-90, 90]、longitude∈ [-180, 180]。auth_data.cookies必须是数组,每项必须有字符串name(非空)和value;domain/path/sameSite为字符串,httpOnly/secure为布尔,expires为数字(Unix 秒)或字符串。localStorage/sessionStorage/tokens/headers必须是对象。proxy_ip必须是合法 IPv4 / IPv6。
auth_data 的返回位置
| 接口 | 是否返回 auth_data 明文 |
|---|---|
GET /api/musecode-accounts(列表) | ❌ 只有 has_auth_data、auth_updated_at |
POST / PATCH / 回写 / 导入的响应 | ❌ 同上 |
GET /api/musecode-accounts/{id}(详情) | ✅ 解密后的完整对象(无则 null;无法解密返回 500) |
数据库中 auth_data_enc 列只有密文。与 Snowflake / Kiro 一样,认证边界是 API Token / 管理员登录:拿到 Token 的调用方可以读取明文,请妥善保管。
与邮箱订阅的关系
- 邮箱在库存中时,创建账号会在同一个 D1 batch 中写入
email_subscriptions(service='musecode', account_ref='musecode_accounts:<id>'),之后POST /api/emails/claim {"service":"musecode"}不会再发放该邮箱(其他服务不受影响)。 - 该邮箱已订阅
musecode(例如之前手工登记过)时,创建返回409。 - 修改账号邮箱时,订阅随之从旧库存邮箱移到新邮箱。
- 删除账号默认保留订阅记录(该邮箱确实注册过 MuseCode,避免再次被领取注册);传
?release_subscription=true才一并删除。
账号套餐 vs 邮箱订阅(勿混淆)
| 概念 | 存哪里 | 含义 |
|---|---|---|
| 邮箱 musecode 订阅 | email_subscriptions(service='musecode') | 该库存邮箱曾用于注册 MuseCode,之后 POST /api/emails/claim {"service":"musecode"} 不会再发放该邮箱 |
| 账号套餐状态 | musecode_accounts.subscription_* | MuseCode 账号本身是否开通/试用/过期等套餐;由外部程序回写,后台列表展示 |
创建账号时仍会写入邮箱侧 email_subscriptions;套餐状态是另一套字段,默认 none。
推荐注册流程
# 1. 按服务领取邮箱(也可不带 service,旧版整邮箱锁同样可用于回写)
curl -X POST "$BASE/api/emails/claim" -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' -d '{"service":"musecode"}'
# 也可限制 ID 闭区间(取范围内最小可用 ID,ORDER BY id ASC):
# -d '{"service":"musecode","id_min":100,"id_max":200}'
# => {"id":12,"email":"a@outlook.com","password":"...","refresh_token":"...","service":"musecode","lock_token":"uuid",...}
# 2. 在 MuseCode 完成注册(验证码可用 GET /api/emails/12/messages 读取)
# 3. 回写账号:校验并消耗锁,记录 musecode 订阅
curl -X POST "$BASE/api/musecode-accounts" -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-d '{"email_id":12,"email_lock_token":"uuid","meta_user_id":"1234567890","registered_at":"2026-10-19T12:00:00+08:00"}'
# 注册失败则释放锁
curl -X POST "$BASE/api/emails/12/release" -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' -d '{"lock_token":"uuid"}'
接口
GET /api/musecode-accounts
按 ID 倒序,游标分页。
| 参数 | 说明 |
|---|---|
limit | 默认 50,最大 200 |
cursor | 上一页的 next_cursor |
q(别名 email) | 邮箱模糊搜索,大小写不敏感;%、_ 按字面匹配 |
meta_user_id | 精确匹配 |
proxy_index | 精确匹配 |
bank_card_last4 | 银行卡尾号精确匹配,必须是 4 位数字(1.30.0 起) |
proxy_country | 两位国家代码,大小写不敏感(匹配 proxy_geo.country_code) |
proxy_ip | 精确匹配 |
has_auth_data | true / false |
registered_from | 注册时间下界(含);纯日期为当天 00:00:00(北京时间) |
registered_to | 注册时间上界(含);纯日期为当天 23:59:59(北京时间) |
notes | 备注包含匹配,忽略大小写,≤500 字符(1.31.0 起) |
has_bank_card_last4 | true = 已填银行卡尾号,false = 未填(1.31.0 起) |
curl "$BASE/api/musecode-accounts?q=outlook®istered_from=2026-10-01®istered_to=2026-10-31&limit=50" \
-H "Authorization: Bearer $TOKEN"
{
"items": [
{
"id": 3,
"email": "a@outlook.com",
"email_id": 12,
"meta_user_id": "1234567890",
"registered_at": "2026-10-19T12:00:00+08:00",
"notes": null,
"bank_card_last4": "4242",
"proxy_ip": "203.0.113.7",
"proxy_country": "US",
"proxy_index": "pool-a:17",
"proxy_geo": { "country_code": "US", "region": "California", "city": "Los Angeles" },
"has_browser_fingerprint": true,
"fingerprint_summary": { "user_agent": "Mozilla/5.0 …", "platform": "Win32", "timezone": "America/Los_Angeles", "language": "en-US" },
"has_auth_data": true,
"auth_updated_at": "2026-10-19T12:00:05+08:00",
"created_at": "2026-10-19T12:00:05+08:00",
"updated_at": "2026-10-19T12:00:05+08:00"
}
],
"has_more": true,
"next_cursor": "3"
}
错误:cursor、时间参数、proxy_country、proxy_ip、bank_card_last4 或 has_auth_data 格式错误 → 400。
导出 CSV:GET / POST /api/musecode-accounts/export
1.31.0 起。按与列表相同的筛选参数(见上表,不含 limit / cursor)导出全部匹配账号,或用 ids 只导出勾选的账号;只读,不改变任何状态,不写调用日志。需认证,未认证 401。后台 MuseCode 页「导出 CSV」按钮使用 POST。
| 参数 | 说明 |
|---|---|
columns | 导出列,按给定顺序(GET 逗号分隔;POST 可传数组或逗号字符串),重复去重。省略或为空 = 默认列。未知列或敏感列 → 400(错误信息列出可选列) |
ids | 只导出这些账号 ID(GET ids=1,2,3;POST 数组),≤1000,去重;与筛选条件取交集,不存在的 ID 忽略 |
header_labels | true 时表头用中文列名;默认用字段名(便于程序处理) |
| 其他 | 与 GET /api/musecode-accounts 相同的筛选参数(q、subscription_status、notes、has_bank_card_last4…);POST 中数字 / 布尔值会转成字符串 |
- 格式:
text/csv; charset=utf-8,UTF-8 带 BOM(Excel 直接打开不乱码),CRLF 换行,首行表头,按 ID 升序;没有匹配记录时只有表头。 - 转义:含逗号、双引号、换行的单元格用双引号包裹,内部双引号写成
""。 - 防公式注入:以
=+-@Tab、CR 开头的单元格前加'(如-42→'-42)。 - 文件名:
Content-Disposition: attachment; filename="musecode-accounts-YYYYMMDD-HHMMSS.csv"(北京时间);响应头X-Export-Count为导出条数;Cache-Control: no-store。 - 上限:单次最多 10000 条,超过返回
400(请缩小筛选或分批勾选)。 - 时间列:北京时间
YYYY-MM-DD HH:MM:SS(UTC+8)。
可导出列(默认列加 ★):
| 列 | 说明 |
|---|---|
id ★ | 账号 ID |
email ★ | 邮箱 |
email_id | 关联的库存邮箱 ID |
meta_user_id ★ | |
subscription_status ★ / subscription_plan ★ | 账号套餐状态 / 套餐 |
subscription_started_at / subscription_expires_at ★ / subscription_updated_at | 订阅时间 |
subscription_meta | 订阅附加信息(JSON 文本,明文) |
bank_card_last4 ★ | 银行卡尾号(只有 4 位) |
registered_at ★ | 注册时间 |
proxy_location ★ | 地理位置:country_code(或 country)· region · city,同后台列表 |
proxy_country / proxy_region / proxy_city | 代理国家 / 地区 / 城市(取自 proxy_geo) |
proxy_ip / proxy_index ★ | 代理 IP / 代理索引 |
proxy_geo | 完整代理地理信息(JSON 文本) |
has_auth_data ★ / auth_updated_at | 是否有认证信息(true/false)/ 认证更新时间(不含认证内容) |
has_browser_fingerprint | 是否有浏览器指纹 |
fingerprint_user_agent / fingerprint_platform / fingerprint_timezone / fingerprint_language | 指纹摘要字段 |
notes ★ | 备注 |
created_at / updated_at | 创建 / 更新时间 |
不可导出:auth_data / auth_data_enc(加密保存的 cookies、tokens 等认证信息)、完整 browser_fingerprint;请求这些列返回 400 columns 含敏感列,不可导出。导出只读取列表接口本就返回的字段,从不解密。MuseCode 账号没有密码、令牌或代理密码字段。
# 导出 active 账号的默认列
curl -OJ "$BASE/api/musecode-accounts/export?subscription_status=active" -H "Authorization: Bearer $TOKEN"
# 只导出勾选的 3 个账号的指定列,中文表头
curl -OJ "$BASE/api/musecode-accounts/export" -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-d '{"ids":[1,2,3],"columns":["id","email","subscription_status","bank_card_last4"],"header_labels":true}'
id,email,subscription_status,bank_card_last4
1,user@example.com,active,4242
GET /api/musecode-accounts/{id}
返回列表中的全部字段,外加完整 browser_fingerprint 和解密后的 auth_data。不存在 → 404;auth_data 无法解密(密钥不匹配 / 数据损坏)→ 500。
{
"id": 3,
"email": "a@outlook.com",
"email_id": 12,
"meta_user_id": "1234567890",
"registered_at": "2026-10-19T12:00:00+08:00",
"notes": null,
"proxy_ip": "203.0.113.7",
"proxy_country": "US",
"proxy_index": "pool-a:17",
"proxy_geo": { "country_code": "US", "region": "California", "city": "Los Angeles" },
"has_browser_fingerprint": true,
"fingerprint_summary": { "user_agent": "Mozilla/5.0 …", "platform": "Win32", "timezone": "America/Los_Angeles", "language": "en-US" },
"has_auth_data": true,
"auth_updated_at": "2026-10-19T12:00:05+08:00",
"created_at": "2026-10-19T12:00:05+08:00",
"updated_at": "2026-10-19T12:00:05+08:00",
"browser_fingerprint": { "user_agent": "Mozilla/5.0 …", "platform": "Win32", "timezone": "America/Los_Angeles", "language": "en-US", "screen": { "width": 1920, "height": 1080 } },
"auth_data": {
"cookies": [{ "name": "session", "value": "…", "domain": ".musecode.example", "path": "/", "httpOnly": true, "secure": true, "sameSite": "Lax" }],
"localStorage": {}, "sessionStorage": {},
"tokens": { "access_token": "…", "refresh_token": "…" },
"headers": {}
}
}
POST /api/musecode-accounts
两种用法:
直接创建(后台、脚本):
{ "email": "User@Example.com", "meta_user_id": "1234567890", "registered_at": "2026-10-19 12:00", "notes": "手工录入", "bank_card_last4": "4242" }
bank_card_last4(银行卡尾号,1.30.0 起)在直接创建、回写、批量导入中都是可选字段:恰好 4 位数字的字符串(前后空白会去掉);省略、null、"" 都存为 null;其他值(3/5 位、含字母、全角数字、JSON 数字 4242 等)→ 400 bank_card_last4 必须是恰好 4 位数字的字符串…。只存尾号,不要传完整卡号。
外部注册程序回写(带领取锁):
{
"email_id": 12, "email_lock_token": "uuid", "meta_user_id": "1234567890",
"registered_at": "2026-10-19T12:00:00+08:00",
"browser_fingerprint": { "user_agent": "Mozilla/5.0 …", "platform": "Win32", "timezone": "America/Los_Angeles" },
"proxy_ip": "203.0.113.7",
"proxy_geo": { "country_code": "US", "city": "Los Angeles" },
"proxy_index": "pool-a:17",
"auth_data": { "cookies": [{ "name": "session", "value": "…" }], "tokens": { "access_token": "…" } }
}
两种用法都可以带上注册上下文字段;字段无效时返回 400,不会消耗领取锁。
- 带锁时必须传
email_id,email可省略(取库存邮箱);若传了email须与库存邮箱一致,否则400。 - 锁须由
{"service":"musecode"}或不带 service 的领取获得;其他服务的锁返回409;锁无效/过期返回409。成功后锁被删除。 - 同一邮箱带锁重试:已存在账号且
meta_user_id一致或未传 →200 {"id":3,"created":false,"idempotent":true};meta_user_id不同 →409。 - 不带锁只传
email_id→400(直接创建请传email)。
成功响应 201:
{
"id": 3,
"email": "a@outlook.com",
"email_id": 12,
"meta_user_id": "1234567890",
"registered_at": "2026-10-19T12:00:00+08:00",
"notes": null,
"proxy_ip": "203.0.113.7",
"proxy_country": "US",
"proxy_index": "pool-a:17",
"proxy_geo": { "country_code": "US", "city": "Los Angeles" },
"has_browser_fingerprint": true,
"fingerprint_summary": { "user_agent": "Mozilla/5.0 …", "platform": "Win32", "timezone": "America/Los_Angeles", "language": null },
"has_auth_data": true,
"auth_updated_at": "2026-10-19T12:00:05+08:00",
"created_at": "2026-10-19T12:00:05+08:00",
"updated_at": "2026-10-19T12:00:05+08:00",
"created": true,
"email_inventory_linked": true,
"lock_consumed": true
}
错误:
| 状态 | 情况 |
|---|---|
| 400 | 缺少 email、邮箱格式错误、meta_user_id 超过 128、时间格式错误、请求体不是对象 |
| 409 | 该邮箱的 MuseCode 账号已存在 / meta_user_id 已被其他 MuseCode 账号使用 / 该邮箱已订阅 musecode 服务… / 锁无效或属于其他服务 |
PATCH /api/musecode-accounts/{id}
部分更新,只修改传入的字段:email、meta_user_id(null 或 "" 清除)、registered_at、notes(null 清除)、bank_card_last4(4 位数字字符串;null 或 "" 清除;格式错误 → 400),以及注册上下文字段 browser_fingerprint、proxy_ip、proxy_geo、proxy_index、auth_data(传值整体替换,传 null 清除,不传保持不变;写入 auth_data 时更新 auth_updated_at)。
{ "meta_user_id": "9876543210", "notes": "已核对" }
{ "auth_data": { "cookies": [{ "name": "session", "value": "rotated" }] }, "proxy_index": "pool-b:3" }
{ "auth_data": null, "browser_fingerprint": null }
响应与列表字段一致,不含 auth_data 明文。
响应 200:更新后的账号 + "updated": true(未传任何字段时 "updated": false)。修改邮箱时订阅从旧库存邮箱移到新邮箱;新邮箱已订阅 musecode → 409。不存在 → 404。
DELETE /api/musecode-accounts/{id}
# 默认:删除账号,保留邮箱的 musecode 订阅
curl -X DELETE "$BASE/api/musecode-accounts/3" -H "Authorization: Bearer $TOKEN"
# => {"id":3,"deleted":true,"subscription_released":false}
# 同时释放订阅,邮箱可再次被 musecode 领取
curl -X DELETE "$BASE/api/musecode-accounts/3?release_subscription=true" -H "Authorization: Bearer $TOKEN"
# => {"id":3,"deleted":true,"subscription_released":true}
release_subscription 只接受 true/false/1/0/yes/no,其他值 → 400。不存在 → 404。
PUT /api/musecode-accounts/{id}/bank-card-last4
单独更新银行卡尾号(1.30.0 起):只改 bank_card_last4(和 updated_at),请求体里的其他字段一律忽略,不影响邮箱、备注、套餐等。后台列表「银行卡尾号」列点击编辑即调用此接口。
| 请求体字段 | 说明 |
|---|---|
bank_card_last4 | 必填键。4 位数字字符串设置;null 或 "" 清空 |
curl -X PUT "$BASE/api/musecode-accounts/12/bank-card-last4" -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' -d '{"bank_card_last4":"4242"}'
# 清空
curl -X PUT "$BASE/api/musecode-accounts/12/bank-card-last4" -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' -d '{"bank_card_last4":null}'
响应 200:更新后的账号(字段同列表)+ "updated": true。缺少 bank_card_last4 键或格式错误 → 400;账号不存在 → 404。
PUT /api/musecode-accounts/by-email/{email}/bank-card-last4
同上,按邮箱定位(路径需 URL 编码,大小写不敏感)。外部程序只知邮箱时用这个;邮箱无对应账号 → 404。
curl -X PUT "$BASE/api/musecode-accounts/by-email/user%40example.com/bank-card-last4" \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"bank_card_last4":"0005"}'
PUT /api/musecode-accounts/{id}/subscription
轻量回写账号套餐。字段均可选,至少传一个;未传的保持不变;null 清除(subscription_status 只能改为枚举值,不能清空)。
curl -X PUT "$BASE/api/musecode-accounts/12/subscription" -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' \
-d '{"subscription_status":"active","subscription_plan":"pro","subscription_expires_at":"2026-12-31T23:59:59+08:00","subscription_meta":{"provider":"stripe"}}'
PUT /api/musecode-accounts/by-email/{email}/subscription
同上,按邮箱定位(路径需 URL 编码)。外部程序只知邮箱时用这个。
curl -X PUT "$BASE/api/musecode-accounts/by-email/user%40example.com/subscription" \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"subscription_status":"past_due"}'
列表筛选:subscription_status、subscription_plan、subscription_expires_from / subscription_expires_to。GET /api/stats 增加 musecode_subscription_statuses: [{status, count}]。
POST /api/musecode-accounts/import
格式与 Kiro 导入相同:JSON 数组、单个对象,或 {"data": "..."} 包装的 JSON / NDJSON 字符串;单次最多 500 条。每条读取 email(必填)、meta_user_id、registered_at、notes、bank_card_last4(可选,规则同创建)以及注册上下文字段(auth_data 逐条加密)。
{ "data": [
{ "email": "a@outlook.com", "meta_user_id": "111", "registered_at": "2026-10-01T10:00:00+08:00", "bank_card_last4": "4242" },
{ "email": "b@example.com" }
] }
响应 201:
{ "imported": 2, "skipped": 0, "errors": [] }
- 已存在的邮箱 /
meta_user_id(含本批重复)计入skipped。 - 库存中已订阅 musecode 的邮箱、格式错误的行在
errors中逐条说明,不影响其他行。 - 库存中的邮箱同样会关联
email_id并记录 musecode 订阅。
GET /api/stats
新增 musecode_total(账号数)和 musecode_linked(其中已关联库存邮箱的数量);email_services 默认包含 musecode。
11. MuseAI 账号
新增(OpenAPI 1.32.0,需迁移
0030_museai_accounts): MuseAI 账号增删改查。与 MuseCode 账号相互独立(独立表museai_accounts),不关联邮箱库存、不写email_subscriptions。Usage 字段对应 MuseAI 后台的 Usage 面板:Free plan「x% used / Weekly limit resets on Nov 3」、Additional tokens「x% used (1B tokens left) / Never expires」。新增(OpenAPI 1.33.0,需迁移
0031_museai_browser_context): 照 MuseCode 账号的设计保存指纹浏览器上下文,以便重现登录状态:指纹浏览器 Profile ID、完整浏览器指纹(加密)、代理 IP / 地理位置 / 索引、认证信息auth_data(cookies / localStorage / sessionStorage / tokens / headers,加密)。列表与写接口响应只返回摘要和has_*标记;GET /{id}与GET /by-email/{email}详情才返回解密后的完整内容。
新增(OpenAPI 1.36.0,需迁移
0032_museai_usage_redesign): 按 muse.ai 设置页 Server Action 返回的subscription结构重新设计 Usage 字段:新增套餐(tier_*)、Free plan 状态(free_plan_state/free_plan_quota_status/ 显示文案)与 Additional tokens 原始余额(topup_balance/topup_total/topup_eligible/ 显示文案),并保存原始结构usage_raw。POST/PATCH/PUT …/usage都可以直接提交 muse.ai 原始响应(subscription或muse_response,支持 RSC 原文),由服务端拆分字段。旧 Usage 字段(free_plan_used_percent等 5 个)保留并继续使用,语义不变。单位:topupBalance/topupTotal为 muse.ai 内部单位,按 HAR 推断 1 单位 = 25 tokens(40000000↔「1B tokens left」)。
数据模型
| 字段 | 类型 | 说明 |
|---|---|---|
id | integer | 主键 |
email | string | 必填;去首尾空格后转小写存储,大小写不敏感唯一(重复 → 409) |
invite_code | string | null | 账号自己的邀请码(允许重复);≤128 字符,去首尾空格,不能含控制字符;空串 / null = 无 |
registered_at | string | 注册时间;创建时不传 = 当前时间 |
free_plan_used_percent | number | null | Usage · Free plan「x% used」;0–100,可小数,null = 未知 |
free_plan_resets_at | string | null | Usage · Free plan「Weekly limit resets on …」每周重置时间;null = 未知 |
additional_tokens_used_percent | number | null | Usage · Additional tokens「x% used」;0–100,可小数,null = 未知 |
additional_tokens_left | integer | null | Usage · Additional tokens 剩余 tokens(「1B tokens left」= 1000000000);非负整数,null = 未知 |
additional_tokens_expires_at | string | null | Usage · Additional tokens 到期时间;null = Never expires(或未知) |
tier_id | string | null | 套餐 ID ← subscription.tier.tierId(如 hatch_free);0032 |
tier_name | string | null | 套餐名称 ← tier.name(如 Muse Free);0032 |
tier_code | string | null | 套餐代码 ← tier.tierCode(如 HATCH_FREE);0032 |
tier_is_paid | boolean | null | 是否付费套餐 ← tier.isPaid;0032 |
free_plan_state | string | null | Free plan 计量状态 ← usage.state(HAR 中为 METERED;大写存储);0032 |
free_plan_quota_status | string | null | Free plan 额度状态 ← usage.quotaStatus(HAR 中为 SUFFICIENT;大写存储);0032 |
free_plan_label | string | null | Free plan 显示文案 ← usageRowValueLabel(如 0% used);0032 |
free_plan_subtitle | string | null | Free plan 副标题 ← statusSubtitle(如 Weekly limit resets on Nov 3);0032 |
topup_balance | integer | null | Additional tokens 余额,muse.ai 原始单位 ← topupBalance(推断 1 单位 = 25 tokens);0032 |
topup_total | integer | null | Additional tokens 总额,原始单位 ← topupTotal;0032 |
additional_tokens_label | string | null | Additional tokens 显示文案 ← topupRowValueLabel(如 0% used (1B tokens left));0032 |
topup_eligible | boolean | null | 是否可充值 ← topupEligible;0032 |
usage_raw | object | null | 最近一次解析的 subscription 原始结构(去掉 managementActions / agreement,≤16KB);仅详情返回;0032 |
usage_updated_at | string | null | Usage 最近写入时间:写入任一 Usage 字段时自动更新为当前时间;也可显式传入(例如外部程序抓取 Usage 的时间) |
notes | string | null | 备注,≤2000 字符 |
browser_profile_id | string | null | 指纹浏览器 profile / 环境 ID(明文);≤128 字符,整数会转字符串,不能含控制字符 |
has_browser_fingerprint | boolean | 是否已保存浏览器指纹(只读) |
fingerprint_summary | object | null | 只读;写入 browser_fingerprint 时派生的明文摘要 {user_agent, platform, timezone, language},供列表展示 |
fingerprint_updated_at | string | null | 浏览器指纹最近写入时间(只读) |
proxy_ip | string | null | 代理出口 IP(IPv4 / IPv6,IPv6 存小写,明文) |
proxy_geo | object | null | 代理地理位置 JSON(≤8KB,明文),结构同 MuseCode:country_code(两位)、country、region、city、latitude、longitude、timezone、isp、asn 等 |
proxy_country | string | null | 只读;由 proxy_geo.country_code 派生的两位大写国家代码 |
proxy_index | string | null | 代理池索引 / 标识(≤128,整数转字符串) |
has_auth_data | boolean | 是否已保存认证信息(只读) |
auth_updated_at | string | null | 认证信息最近写入时间(只读) |
created_at / updated_at | string | 创建 / 更新时间 |
仅详情接口返回(解密后):
| 字段 | 类型 | 说明 |
|---|---|---|
browser_fingerprint | object | null | 完整浏览器指纹 / 指纹浏览器 profile 配置,任意 JSON 对象(≤64KB),AES-GCM 加密保存(DATA_ENCRYPTION_KEY)。推荐键:user_agent、platform、language、languages、timezone、screen、webgl、canvas、audio、fonts、hardware_concurrency、device_memory;代理凭据如需保存请放在 proxy{type,host,port,username,password} 内(随指纹加密) |
auth_data | object | null | 登录状态,AES-GCM 加密保存(≤1.4MB,明文 JSON;加密后约 ≤1.87MB,受 D1 单值/单行 2MB 上限约束),结构同 MuseCode:cookies[](name、value、domain、path、expires、httpOnly、secure、sameSite)、localStorage、sessionStorage、tokens、headers |
存储:browser_fingerprint → browser_fingerprint_enc、auth_data → auth_data_enc,库中只有密文;列表 / 创建 / 修改响应都不含这两项。与 MuseCode 的区别:MuseCode 的 browser_fingerprint 明文保存,MuseAI 加密保存。
输入规则:
- 百分比字段接受 JSON 数字或数字字符串(可带
%,如"12.5%"),超出 0–100 → 400<field> 必须是 0–100 的数值。 additional_tokens_left接受非负整数,或带千分位逗号 /K/M/B后缀的字符串(大小写不敏感,可小数):"1B"= 1000000000、"1.5M"= 1500000、"250K"= 250000、"1,234,567"= 1234567;其他 → 400additional_tokens_left 必须是非负整数…。- 时间字段(
registered_at、free_plan_resets_at、additional_tokens_expires_at、usage_updated_at)为 ISO 8601,不带时区按北京时间解释,仅日期(如"2026-11-03")= 北京时间当日 00:00;响应统一为+08:00。 - 指纹浏览器字段(
browser_profile_id、proxy_ip、proxy_index、proxy_geo、browser_fingerprint、auth_data):传值替换,传null或""清除,不传保持不变。proxy_geo/browser_fingerprint/auth_data必须是 JSON 对象,超限 → 400;校验规则与 MuseCode 相同(如proxy_geo.country_code必须两位字母、auth_data.cookies必须是数组)。写入browser_fingerprint/auth_data时刷新fingerprint_updated_at/auth_updated_at,清除时置null。
表中不保存账号密码。
接口
GET /api/museai-accounts
按 ID 倒序、cursor 分页(limit 默认 50,最大 200)。响应 {items, has_more, next_cursor}。
| 参数 | 说明 |
|---|---|
q(别名 email) | 邮箱模糊搜索,忽略大小写 |
invite_code | 邀请码精确匹配 |
has_invite_code | true / false |
free_plan_exhausted | true = free_plan_used_percent ≥ 100;false = < 100 或未知 |
has_additional_tokens | true = additional_tokens_left > 0;false = 为 0 或未知 |
additional_tokens_never_expires | true = additional_tokens_expires_at 为 null;false = 有到期时间 |
tier_id | 套餐 ID 精确匹配(如 hatch_free) |
tier_is_paid / topup_eligible | true / false |
free_plan_state / free_plan_quota_status | 精确匹配,不区分大小写(如 METERED / SUFFICIENT) |
registered_from / registered_to | 注册时间区间(含);纯日期为北京时间当日 00:00:00 / 23:59:59 |
notes | 备注包含匹配,忽略大小写,≤500 字符 |
browser_profile_id | 指纹浏览器 Profile ID 精确匹配 |
proxy_index / proxy_ip | 精确匹配 |
proxy_country | 两位国家代码,大小写不敏感 |
has_browser_fingerprint / has_auth_data | true / false |
limit / cursor | 分页 |
POST /api/museai-accounts
curl -X POST https://snow.51proxy.org/api/museai-accounts \
-H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"email":"user@example.com","invite_code":"INV-001","registered_at":"2026-10-27 10:00:00","free_plan_used_percent":0,"free_plan_resets_at":"2026-11-03","additional_tokens_used_percent":0,"additional_tokens_left":"1B","additional_tokens_expires_at":null,"notes":"可选"}'
# => 201 {"id":1,"email":"user@example.com","invite_code":"INV-001","registered_at":"2026-10-27T10:00:00+08:00",
# "free_plan_used_percent":0,"free_plan_resets_at":"2026-11-03T00:00:00+08:00",
# "additional_tokens_used_percent":0,"additional_tokens_left":1000000000,"additional_tokens_expires_at":null,
# "usage_updated_at":"…+08:00","notes":"可选","created_at":"…","updated_at":"…","created":true}
只有 email 必填。邮箱已存在(大小写不敏感)→ 409 该邮箱的 MuseAI 账号已存在。
创建时可同时保存指纹浏览器上下文(响应只含 has_browser_fingerprint / has_auth_data / fingerprint_summary,不含明文):
curl -X POST https://snow.51proxy.org/api/museai-accounts \
-H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"email":"user@example.com","browser_profile_id":"adspower-k1a2b3","proxy_ip":"203.0.113.10","proxy_index":"7","proxy_geo":{"country_code":"US","region":"California","city":"Los Angeles"},"browser_fingerprint":{"user_agent":"Mozilla/5.0 …","platform":"Win32","timezone":"America/Los_Angeles","language":"en-US","screen":{"width":1920,"height":1080}},"auth_data":{"cookies":[{"name":"session","value":"…","domain":".example.com","path":"/","httpOnly":true,"secure":true}],"localStorage":{},"tokens":{}}}'
GET / PATCH / DELETE /api/museai-accounts/{id}
GET:详情 = 列表字段 +usage_raw(0032)+ 解密后的browser_fingerprint与auth_data(无则null),用于重现登录状态;不存在 → 404MuseAI 账号不存在;无法解密(DATA_ENCRYPTION_KEY不匹配或数据损坏)→ 500。PATCH:只更新传入的字段——传值替换、传null清除(email、registered_at不可清除)、不传保持不变;无任何改动时返回updated:false。写入任一 Usage 字段且未显式传usage_updated_at时自动刷新usage_updated_at;只改备注等不刷新。新邮箱已被占用 → 409。DELETE:直接删除(物理删除,不可恢复),返回{"id":1,"deleted":true}。
GET / PATCH / DELETE /api/museai-accounts/by-email/{email}
与按 ID 的接口相同(GET 同样返回解密后的详情),供外部程序只知道邮箱时使用。{email} 需 URL 编码(如 user%40example.com),大小写不敏感。
# 回写 Usage(外部程序抓取后)
curl -X PATCH "https://snow.51proxy.org/api/museai-accounts/by-email/user%40example.com" \
-H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"free_plan_used_percent":12.5,"free_plan_resets_at":"2026-11-10","additional_tokens_used_percent":5,"additional_tokens_left":"950M"}'
PUT /api/museai-accounts/{id}/usage 与 PUT /api/museai-accounts/by-email/{email}/usage
新增(OpenAPI 1.35.0,向后兼容,无需迁移): 专门的用量回写接口(照 MuseCode
PUT …/subscription风格),供外部程序抓取 muse.ai 设置页 Usage 后回写 Free plan、剩余 tokens 与 tokens 到期时间。API token(Authorization: Bearer/x-api-key)或后台登录会话均可调用。
- 只更新本次传入的 Usage 字段,未传的保持不变;传
null清除(additional_tokens_expires_at: null= Never expires)。其他字段(email、invite_code、notes、指纹 / 认证等)一律忽略——改这些请用PATCH。 - 成功即自动刷新
usage_updated_at(可显式传usage_updated_at指定抓取时间)。 - 账号不存在 → 404
MuseAI 账号不存在;字段无效 / 标签无法解析 / 没有任何 Usage 字段 → 400(不改库)。 - 响应:账号摘要(同列表字段)+
updated: true+usage_fields_updated(本次写入的字段名数组)。
| 字段 | 说明 |
|---|---|
free_plan_used_percent | Free plan 已用百分比,0–100(可小数,可写 "12.5%") |
free_plan_resets_at | 每周重置时间:日期(视为北京时间 00:00)、ISO 8601(无时区按北京时间)或 Unix 秒(> 1e12 视为毫秒) |
additional_tokens_used_percent | Additional tokens 已用百分比,0–100 |
additional_tokens_left | 剩余 tokens:非负整数,或 "1B" / "500M" / "2.5K"(1B = 1000000000,可带千分位逗号) |
additional_tokens_expires_at | tokens 到期时间,格式同 free_plan_resets_at;null = Never expires |
tier_id / tier_name / tier_code / tier_is_paid | 套餐(0032) |
free_plan_state / free_plan_quota_status / free_plan_label / free_plan_subtitle | Free plan 状态与文案(0032) |
topup_balance / topup_total / additional_tokens_label / topup_eligible | Additional tokens 原始余额 / 总额 / 文案 / 是否可充值(0032) |
usage_updated_at | 可选,抓取时间;不传则为当前时间 |
subscription | 可选,muse.ai 原始结构(见下) |
muse_response | 可选,与 subscription 二选一:整个 muse.ai 响应(对象或 JSON 字符串),或 Server Action 的 RSC 原文(见下) |
可选:直接传 muse.ai 原始响应(0032 起 POST / PATCH / PUT …/usage 通用)。 接受以下任一形式,服务端拆分字段:
subscription字段:设置页 Server Action 响应中的subscription对象,或整个{"success":true,"subscription":{…}};muse_response字段:同上(对象或 JSON 字符串),或 RSC 原文字符串,如"0:{\"a\":\"$@1\",…}\n1:{\"success\":true,\"subscription\":{…}}"(取第一行含subscription的 JSON);- 仅
PUT …/usage:请求体直接是整个 JSON 响应({"success":true,"subscription":{…}}),或以Content-Type: text/x-component/text/plain直接提交 RSC 原文。
success:false → 400;RSC 中找不到 subscription → 400。
| 原始字段 | 写入 |
|---|---|
tier.tierId / tier.name / tier.tierCode / tier.isPaid | tier_id / tier_name / tier_code / tier_is_paid |
usage.state / usage.quotaStatus | free_plan_state / free_plan_quota_status |
usage.percentUsed | free_plan_used_percent |
usage.resetsAt(Unix 秒) | free_plan_resets_at |
usageRowValueLabel(如 "0% used") | free_plan_label;percentUsed 缺失时也解析出 free_plan_used_percent |
statusSubtitle(如 "Weekly limit resets on Nov 3") | free_plan_subtitle |
topupBalance / topupTotal(原始单位) | topup_balance / topup_total |
topupRowValueLabel(如 "0% used (1B tokens left)") | additional_tokens_label + additional_tokens_used_percent + additional_tokens_left |
topupEligible | topup_eligible |
整个 subscription(去掉 managementActions / agreement) | usage_raw(仅详情返回) |
单位换算:HAR 中 topupBalance = topupTotal = 40000000,文案为 0% used (1B tokens left),邀请奖励文案为「1 billion Muse tokens」,即 1 单位 = 25 tokens(1,000,000,000 ÷ 40,000,000)。topupRowValueLabel 缺失时:additional_tokens_left = topupBalance × 25 tokens,additional_tokens_used_percent = (1 − topupBalance / topupTotal) × 100(保留两位小数)。有文案时以文案为准(文案是 muse.ai 页面实际显示值;1B 为取整值)。
顶层显式字段优先于原始响应的解析结果;原始响应里没有的字段保持不变。原始结构中没有到期字段(邀请奖励文案为「no expiration」),additional_tokens_expires_at 不会被原始响应改动,需要时单独传。
# 按邮箱回写(显式字段)
curl -X PUT "https://snow.51proxy.org/api/museai-accounts/by-email/user%40example.com/usage" \
-H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"free_plan_used_percent":12.5,"free_plan_resets_at":1793690439,"additional_tokens_used_percent":0,"additional_tokens_left":"1B","additional_tokens_expires_at":null}'
# 按 ID 回写(直接转发 muse.ai 原始 subscription 结构)
curl -X PUT "https://snow.51proxy.org/api/museai-accounts/1/usage" \
-H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" \
-d '{"subscription":{"usage":{"percentUsed":0,"resetsAt":1793690439},"usageRowValueLabel":"0% used","topupRowValueLabel":"0% used (1B tokens left)"}}'
# 直接提交 Server Action 的 RSC 原文(抓包得到的响应正文原样转发)
curl -X PUT "https://snow.51proxy.org/api/museai-accounts/by-email/user%40example.com/usage" \
-H "Authorization: Bearer $API_TOKEN" -H "Content-Type: text/x-component" \
--data-binary @subscription-response.txt
响应示例:
{"id":1,"email":"user@example.com","free_plan_used_percent":0,"free_plan_resets_at":"2026-11-03T…+08:00","additional_tokens_used_percent":0,"additional_tokens_left":1000000000,"additional_tokens_expires_at":null,"tier_id":"hatch_free","tier_name":"Muse Free","tier_code":"HATCH_FREE","tier_is_paid":false,"free_plan_state":"METERED","free_plan_quota_status":"SUFFICIENT","free_plan_label":"0% used","free_plan_subtitle":"Weekly limit resets on Nov 3","topup_balance":40000000,"topup_total":40000000,"additional_tokens_label":"0% used (1B tokens left)","topup_eligible":true,"usage_updated_at":"2026-10-28T16:30:00+08:00","…":"…","updated":true,"usage_fields_updated":["free_plan_used_percent","free_plan_resets_at","additional_tokens_used_percent","additional_tokens_left"]}
后台:左侧导航「账号 → MuseAI 账号」,支持搜索筛选、无限滚动、新增 / 编辑 / 删除、行内编辑备注。列表新增「套餐」列(tier_name / tier_id,付费标记);Usage 按 MuseAI 面板格式展示(有 muse.ai 原始文案时直接显示文案,额度状态 free_plan_quota_status 非 SUFFICIENT 时高亮):Free plan「12.5% used」+「Weekly limit resets on Nov 3」,Additional tokens「0% used (1B tokens left)」+「Never expires」/「Expires on …」。列表另有「指纹 Profile」「地理位置」「代理索引」「浏览器指纹」「认证信息」列(指纹 / 认证只显示已保存 / 无,悬停看摘要和更新时间);编辑对话框从详情接口载入并可编辑代理与 JSON(未改动的 JSON 字段不提交,关闭时清空表单)。
12. Muse 资产
收集外部程序通过 API 上传的 email / api_key / access_token,后台「Muse资产」页列表展示、多选导出 TSV、手动改状态与备注。所有接口需 Authorization: Bearer <API_TOKEN> 或后台登录 Cookie。 写操作(上传 / 导入 / 修改 / 批量改状态 / 软删除 / 导出)会记入 api_call_logs,见下方「调用日志」;列表与详情不记。
数据模型
| 字段 | 说明 |
|---|---|
id | 自增 ID |
email | 必填,去首尾空格并转小写保存 |
api_key | 必填,≤1024 字符,去首尾空格,不能含空格 / Tab / 换行等空白或控制字符;AES-GCM 加密保存(DATA_ENCRYPTION_KEY),库里不存明文 |
access_token | 必填,≤16384 字符,规则同 api_key,加密保存 |
generated_at | 生成时间;ISO 8601 或 YYYY-MM-DD HH:MM:SS,不带时区按北京时间;不传为写入时间。响应为北京时间 +08:00 |
created_by | 上传人,选填,≤100 字符,去首尾空格,空白视为 null。不传时:API Token 调用记 null,后台会话记 admin |
status | unsubmitted(未提交,默认)/ submitted(已提交);写入时也接受中文「未提交」「已提交」 |
status_updated_at | 最近一次改状态的时间;从未改过为 null(上传时直接 submitted 则为上传时间) |
notes | 备注,≤500 字符,空白视为 null |
card_number | 关联银行卡号,选填(migration 0027)。去首尾空白后须为 12–19 位纯数字(内部空格 / 连字符拒绝)且通过 Luhn 校验(与银行卡模块一致),否则 400 card_number 必须是 12–19 位纯数字且通过 Luhn 校验…(错误信息不回显卡号);null / 空白 = 不填 / 清空。AES-GCM 加密保存(DATA_ENCRYPTION_KEY),列表 / 详情返回明文(Muse 资产不打码)。不要求卡在银行卡库中存在,也不改变银行卡状态 |
card_last4 | 只读,卡号后 4 位(库内明文列,仅用于筛选);未填为 null |
created_at / updated_at | 上传时间 / 最后修改时间 |
deleted_at / deleted | 软删除时间(UTC 原样)/ 是否已删除 |
去重 / 重复上传规则: 未删除记录中 email(不分大小写)+ api_key 唯一(库内用 api_key 的 HMAC 指纹比对)。重复上传不新建,而是更新已有记录:总是更新 access_token(重新加密)和 updated_at;上传里显式带了 generated_at(非空)时一并更新;行内显式带了 notes 时一并更新(null / 空白清空;批量导入外层的本批默认 notes 不算);显式带了 card_number 时一并更新(null / 空白清空),未带则不变;created_by、status、status_updated_at 不变。同一 email 可以有多个不同 api_key(各自一条);已软删除的记录不参与,重新上传会新建一条。
GET /api/muse-assets
列表,默认按 ID 升序,limit(默认 50,最大 200)+ cursor 游标分页,order=asc|desc。
筛选:status、email(别名 q,包含匹配、忽略大小写)、created_by(包含、忽略大小写)、notes(包含、忽略大小写)、card_last4(4 位数字 = 卡号后 4 位等于;none = 未填卡号;any = 已填卡号;其他值 400。暂不支持按完整卡号筛选)、deleted=exclude|include|only(默认 exclude)。
响应 { items, total, has_more, next_cursor },total 为当前筛选下的总数;每条返回解密后的 api_key / access_token / card_number 明文(与银行卡列表返回完整卡号一致)。
{
"items": [{
"id": 1, "email": "user@example.com", "api_key": "sk-example", "access_token": "example-token",
"generated_at": "2026-10-23T12:00:00+08:00", "created_by": "uploader-1", "status": "unsubmitted",
"status_updated_at": null, "notes": null, "card_number": "4242424242424242", "card_last4": "4242",
"created_at": "2026-10-23T12:00:05+08:00",
"updated_at": "2026-10-23T12:00:05+08:00", "deleted_at": null, "deleted": false
}],
"total": 1, "has_more": false, "next_cursor": null
}
POST /api/muse-assets(上传一条)
{ "email": "user@example.com", "api_key": "sk-example", "access_token": "example-token", "generated_at": "2026-10-23 12:00:00", "created_by": "uploader-1", "notes": "可选", "card_number": "4242424242424242" }
- 新建:201,返回该记录 +
"created": true, "updated": false。 - 未删除记录中已有同 email + api_key:更新
access_token(及显式带的generated_at/notes/card_number),200,返回更新后的记录 +"created": false, "updated": true。 - 字段无效 400;非 JSON 415;极少见的并发写入冲突 409(带
existing_id,重试即可)。
POST /api/muse-assets/import(批量上传)
单次最多 500 条。请求体任选:
MuseAssetInput数组;{ "data": 数组或文本, "created_by": "可选", "status": "可选", "notes": "可选" }:外层三个字段是本批默认值,行内字段优先;- 文本
data:每行email api_key access_token [generated_at] [card_number],Tab 或空白分隔(与导出的 TSV 互通),空行跳过,首行以email开头的表头跳过;data也可以是 JSON / NDJSON 字符串。 - 文本行的卡号识别: 第 4 列起,最后一个非空单元格若是 12–19 位纯数字即视为
card_number,其余单元格拼成generated_at。generated_at必含-(如2026-10-23 12:00:00),因此无歧义;卡号本身不能含空格(带空格会被拆成多列 → 该行报错)。外层不支持本批默认card_number。
{ "created_by": "uploader-1", "data": "user@example.com\tsk-example\texample-token\nuser2@example.com sk-example-2 example-token-2 2026-10-23 12:00:00 4242424242424242" }
外层 created_by / status / notes 只作用于新建的记录;已存在的记录按上面的重复上传规则只更新 access_token(文本行第 4 列或行内 generated_at、行内 notes、文本行卡号列或行内 card_number 显式带了才更新)。同一批内同 email + api_key 出现多次时以最后一行为准,较早的行不单独写入。
响应 201:{ processed, created, updated, duplicates, failed, created_by, status, notes, results: [{ row, ok, action, id, email, card_last4?, superseded_by?, error? }] }(带了卡号的行只回 card_last4,不回完整卡号):
action | 含义 |
|---|---|
created | 新建,id 为新记录 |
updated | 已存在,已更新 access_token,id 为该记录 |
duplicate | 本批内被后面的同 email + api_key 行覆盖,未单独写入;superseded_by 为生效行号,id 为生效行写入的记录 |
计数 duplicates 只统计本批内被覆盖的行。单行错误不影响其他行(如卡号格式 / Luhn 不通过 → 该行 ok: false);全部失败返回 400。
GET /api/muse-assets/{id} · PATCH /api/muse-assets/{id}
GET 返回单条(不存在或已删除 404)。PATCH 部分更新,至少一个字段:status、notes、created_by、card_number(null 或空字符串清除)、generated_at(不能清空)、email、api_key、access_token。改状态时更新 status_updated_at;改 email / api_key 后与其他记录重复返回 409。
{ "status": "submitted", "notes": "已交付" }
{ "card_number": "4242424242424242" }
{ "card_number": null }
POST /api/muse-assets/batch-status
{ "ids": [1, 2, 3], "status": "submitted" }
ids ≤1000,重复去重。响应 { requested, updated, status, updated_ids, not_found_ids }(not_found_ids 含已删除)。
POST /api/muse-assets/batch-delete(软删除)
{ "ids": [1, 2] },写入 deleted_at,数据保留;删除后不出现在默认列表、导出和统计中。响应 { requested, deleted, deleted_ids, not_found_ids }。
导出 TSV:GET / POST /api/muse-assets/export
- 响应
text/tab-separated-values; charset=utf-8,附件名muse-assets-YYYY-MM-DD.tsv(北京时间日期),响应头X-Export-Count为条数。 - 每行
email<Tab>api_key<Tab>access_token,\n换行、末尾带换行,按 ID 升序;默认无表头,header=true时首行加email api_key access_token。 - 传
ids只导出这些记录(未删除的);不传ids时按status/email(q)/created_by/notes/card_last4筛选导出全部未删除记录。TSV 仍只有三列,不含卡号。 - 导出不会自动改状态,需要时再调用 batch-status。
POST /api/muse-assets/export
{ "ids": [1, 2, 3] }
GET /api/muse-assets/export?status=unsubmitted&header=true
GET /api/muse-assets/logs(调用日志)
Muse 资产写操作会写入通用表 api_call_logs(module = muse_assets)。本接口按 ID 降序分页查询,需 Bearer / Cookie。
- 记入:
POST /api/muse-assets(create)、POST /import(import)、PATCH /{id}(update)、POST /batch-status、POST /batch-delete、GET|POST /export。成功与 4xx 都会记;日志写入失败不影响主请求。 - 不记:
GET列表 / 详情,以及本日志查询接口本身(与其它模块列表不记请求日志一致;项目内原先无统一请求日志中间件)。 - 字段:
id、created_at(北京时间)、method、path(模板路径,如/api/muse-assets/{id})、action、caller_type(api_token/session)、caller(api/admin,不含 token 明文)、summary(JSON 摘要:id / email / 条数 / ids 等)、status_code、ok、error(失败时的错误摘要,≤500)。 - 脱敏:
summary写入前会去掉api_key/access_token/card_number/cvc/password/token/secret等键;Muse 资产的卡号绝不写入日志,最多记card_last4(后 4 位);响应与库中均不含这些明文。导出日志只记export_count,不记 TSV 内容。 - 筛选:
action、caller_type、ok=true|false;limit(默认 50,最大 200)+cursor(上一页最后一条 id,向更旧翻页)。
{
"items": [{
"id": 12, "module": "muse_assets", "method": "POST", "path": "/api/muse-assets",
"action": "create", "caller_type": "api_token", "caller": "api",
"summary": { "id": 1, "email": "user@example.com", "created": true, "updated": false },
"status_code": 201, "ok": true, "error": null, "created_at": "2026-10-23T19:00:00+08:00"
}],
"total": 1, "has_more": false, "next_cursor": null
}
13. 接口一览表
| 方法 | 路径 | 摘要 | 认证 |
|---|---|---|---|
| POST | /api/auth/login | 后台登录 | 公开 / Cookie |
| POST | /api/auth/logout | 退出登录 | 公开 / Cookie |
| GET | /api/auth/session | 检查登录状态 | 公开 / Cookie |
| GET | /api/bind/{id}/bootstrap | 初始化托管 Stripe 绑卡页 | X-Bind-Token |
| POST | /api/bind/{id}/card-selection | 为绑卡会话选择并锁定库存卡 | X-Bind-Token |
| GET | /api/bind/{id}/cards | 列出可用于当前绑卡会话的库存卡 | X-Bind-Token |
| POST | /api/bind/{id}/complete | 提交 Stripe 验证结果并绑定到 Snowflake | X-Bind-Token |
| GET | /api/cards | 银行卡列表(可按状态、备注、锁定人、删除状态筛选) | Bearer / Cookie |
| GET | /api/cards/{id} | 银行卡详情 | Bearer / Cookie |
| POST | /api/cards | 添加银行卡 | Bearer / Cookie |
| POST | /api/cards/batch-delete | 批量软删除银行卡 | Bearer / Cookie |
| POST | /api/cards/claim | 领取并锁定银行卡(必填 email,API token 必填 locked_by,一人一卡,锁不过期;可按备注、失败次数筛选) | Bearer / Cookie |
| POST | /api/cards/import | 批量导入银行卡(每行 卡号 有效期 CVV 邮编,空格或 Tab 分隔,或 JSON),可带本批备注 | Bearer / Cookie |
| POST | /api/cards/{id}/billing-profiles/import | 为单张银行卡导入账单地址 | Bearer / Cookie |
| PATCH | /api/cards/{id}/billing-profiles/{profileId} | 更新账单地址状态 | Bearer / Cookie |
| POST | /api/cards/{id}/release | 记录绑卡失败并释放银行卡 | Bearer / Cookie |
| POST | /api/cards/{id}/unlock | 管理员强制释放银行卡锁定 | Bearer / Cookie |
| PATCH | /api/cards/{id}/status | 修改银行卡状态(可用 / 已锁定 / 已使用) | Bearer / Cookie |
| PATCH | /api/cards/{id}/notes | 修改银行卡备注 | Bearer / Cookie |
| GET | /api/cards/{id}/history | 银行卡操作历史 | Bearer / Cookie |
| GET | /api/emails | 邮箱列表(q 按地址搜索,可与其他筛选叠加) | Bearer / Cookie |
| POST | /api/emails/claim | 按服务领取并锁定邮箱(可选 id_min/id_max 闭区间,按 ID 升序取最小可用) | Bearer / Cookie |
| POST | /api/emails/import | 批量导入邮箱 | Bearer / Cookie |
| GET | /api/emails/{id} | 查询单个邮箱 | Bearer / Cookie |
| GET | /api/emails/by-address/{email} | 按完整地址精确查询单个邮箱 | Bearer / Cookie |
| POST | /api/emails/{id}/mark-used | (已废弃)mark-used,等同 POST /api/emails/{id}/subscriptions | Bearer / Cookie |
| GET | /api/emails/{id}/message | 读取完整邮件正文 | Bearer / Cookie |
| GET | /api/emails/{id}/messages | 读取邮箱收件箱 | Bearer / Cookie |
| GET | /api/emails/{id}/pickup-info | 取件方式详情(解密凭据,no-store) | Bearer / Cookie |
| GET | /api/emails/{id}/pickup-links | 列出公开取件链接 | Bearer / Cookie |
| POST | /api/emails/{id}/pickup-links | 创建公开取件链接 | Bearer / Cookie |
| DELETE | /api/emails/{id}/pickup-links/{linkId} | 撤销公开取件链接 | Bearer / Cookie |
| POST | /api/public/pickup/{token}/fetch | 公开取件:读取最新验证码 | 公开(token) |
| POST | /api/emails/{id}/release | 释放邮箱 | Bearer / Cookie |
| POST | /api/emails/{id}/subscriptions | 记录邮箱订阅(外部回写或管理员登记) | Bearer / Cookie |
| DELETE | /api/emails/{id}/subscriptions/{service} | 删除邮箱订阅记录 | Bearer / Cookie |
| GET | /api/kiro-accounts | Kiro 账号列表 | Bearer / Cookie |
| POST | /api/kiro-accounts | 写入 Kiro 账号 | Bearer / Cookie |
| POST | /api/kiro-accounts/callback | 外部回写 Kiro 注册结果 | Bearer / Cookie |
| POST | /api/kiro-accounts/import | 批量导入 Kiro 账号 | Bearer / Cookie |
| POST | /api/kiro-accounts/{id}/refresh-status | 刷新 Kiro Plan 与 Credits | Bearer / Cookie |
| GET | /api/musecode-accounts | MuseCode 账号列表 | Bearer / Cookie |
| POST | /api/musecode-accounts | 新增 MuseCode 账号 | Bearer / Cookie |
| POST | /api/musecode-accounts/import | 批量导入 MuseCode 账号 | Bearer / Cookie |
| GET | /api/musecode-accounts/{id} | MuseCode 账号详情 | Bearer / Cookie |
| PATCH | /api/musecode-accounts/{id} | 修改 MuseCode 账号 | Bearer / Cookie |
| PUT | /api/musecode-accounts/{id}/subscription | 回写 MuseCode 账号套餐状态 | Bearer / Cookie |
| PUT | /api/musecode-accounts/by-email/{email}/subscription | 按邮箱回写套餐状态 | Bearer / Cookie |
| PUT | /api/musecode-accounts/{id}/bank-card-last4 | 单独更新 MuseCode 银行卡尾号 | Bearer / Cookie |
| PUT | /api/musecode-accounts/by-email/{email}/bank-card-last4 | 按邮箱更新银行卡尾号 | Bearer / Cookie |
| DELETE | /api/musecode-accounts/{id} | 删除 MuseCode 账号 | Bearer / Cookie |
| GET | /api/museai-accounts | MuseAI 账号列表(cursor 分页 + 筛选) | Bearer / Cookie |
| POST | /api/museai-accounts | 新增 MuseAI 账号 | Bearer / Cookie |
| GET | /api/museai-accounts/{id} | MuseAI 账号详情(含解密后的指纹与认证信息) | Bearer / Cookie |
| PATCH | /api/museai-accounts/{id} | 修改 MuseAI 账号(含 Usage) | Bearer / Cookie |
| DELETE | /api/museai-accounts/{id} | 删除 MuseAI 账号 | Bearer / Cookie |
| GET | /api/museai-accounts/by-email/{email} | 按邮箱查询 MuseAI 账号(含解密后的指纹与认证信息) | Bearer / Cookie |
| PATCH | /api/museai-accounts/by-email/{email} | 按邮箱修改 MuseAI 账号(含 Usage) | Bearer / Cookie |
| DELETE | /api/museai-accounts/by-email/{email} | 按邮箱删除 MuseAI 账号 | Bearer / Cookie |
| PUT | /api/museai-accounts/{id}/usage | 回写 MuseAI 用量(套餐 / Free plan / Additional tokens;可传 muse.ai 原始响应或 RSC 原文) | Bearer / Cookie |
| PUT | /api/museai-accounts/by-email/{email}/usage | 按邮箱回写 MuseAI 用量 | Bearer / Cookie |
| GET | /api/snowflake-accounts | Snowflake 账号列表 | Bearer / Cookie |
| POST | /api/snowflake-accounts | 回写注册结果、MFA 与 Snowsight 认证信息并记录邮箱 snowflake 订阅 | Bearer / Cookie |
| GET | /api/snowflake-accounts/export-bound | 按绑卡状态导出账号 | Bearer / Cookie |
| POST | /api/snowflake-accounts/import | 直接导入 Snowflake 账号 | Bearer / Cookie |
| POST | /api/snowflake-accounts/{id}/bind-session | 为账号创建人工绑卡链接 | Bearer / Cookie |
| PATCH | /api/snowflake-accounts/{id}/notes | 更新账号备注 | Bearer / Cookie |
| GET | /api/snowflake-accounts/{id}/payment-method-status | 查询是否已绑卡 | Bearer / Cookie |
| POST | /api/snowflake-accounts/{id}/refresh-snowsight-auth | 自动刷新 Snowsight 认证 | Bearer / Cookie |
| GET | /api/snowflake-accounts/{id}/registration-metadata | 查看注册元数据 | Bearer / Cookie |
| PUT | /api/snowflake-accounts/{id}/snowsight-auth | 刷新账号的 Snowsight 认证信息 | Bearer / Cookie |
| POST | /api/snowflake-accounts/{id}/subscription | 回写绑卡与订阅结果并消耗银行卡 | Bearer / Cookie |
| GET | /api/snowflake-accounts/{id}/totp | 获取账号当前 MFA 验证码 | Bearer / Cookie |
| GET | /api/stats | 库存统计 | Bearer / Cookie |
共 57 条路径(与 src/index.ts 的 api() 路由及 openapi.json 完全一致)。
14. 推荐调用流程
按服务注册(以 MuseCode 为例;Snowflake / Kiro 同理)
POST /api/emails/claim传{"service":"musecode"}领取邮箱。- 用返回的
password/refresh_token完成目标站点注册(验证码可用GET /api/emails/{id}/messages)。 - 成功:调用对应回写接口(MuseCode →
POST /api/musecode-accounts;Snowflake →POST /api/snowflake-accounts;Kiro →POST /api/kiro-accounts/callback),带上email_id+email_lock_token。 - 失败:
POST /api/emails/{id}/release释放锁。 - 其他服务可走通用
POST /api/emails/{id}/subscriptions。
Snowflake 绑卡
- (可选)
POST /api/cards/claim取卡(带email、locked_by)。 POST /api/snowflake-accounts/{id}/bind-session拿magic_url,交给人工打开。- 或自行完成 Stripe 后调用
POST /api/snowflake-accounts/{id}/subscription;失败则POST /api/cards/{id}/release(带email)。 - 每张卡的取卡 / 回写记录可在
GET /api/cards/{id}/history或后台「操作历史」查看。
附录
- OpenAPI 版本见
public/openapi.json的info.version。 - 管理后台「API 文档」页跳转到本页;机器集成请直接消费
openapi.json。 - 仓库内历史文档:
docs/EMAIL_API.md、docs/MUSECODE_API.md现为指向本文的短 stub。