SNOWFLAKE ACCOUNT MANAGER

完整 API 文档

公开可读 · 与 openapi.json 同步 · 不含真实密钥与账号数据

OpenAPI JSON管理后台

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、密钥、卡号或账号数据,示例一律使用占位符。

目录

  1. 概述与认证
  2. 约定(时间、分页、错误)
  3. 认证接口
  4. 库存统计
  5. 邮箱(领取 / 订阅 / 读信)
  6. 银行卡与账单地址
  7. Snowflake 账号
  8. 托管人工绑卡(magic link)
  9. Kiro 账号
  10. MuseCode 账号
  11. MuseAI 账号
  12. Muse 资产
  13. 接口一览表
  14. 推荐调用流程

1. 概述与认证

Base URL: https://snow.51proxy.org

除下列例外外,所有 /api/* 接口都需要认证:

方式说明
Authorization: Bearer <API_TOKEN>自动化脚本 / 外部注册程序(Cloudflare Secret API_TOKEN)
管理后台登录 CookiePOST /api/auth/login 签发,有效期 8 小时,HttpOnly

无需 Token 的接口:

未认证访问受保护接口 → 401 {"error":"未授权"}。

文档页(/docs、/openapi.json)公开可读,与当前 openapi.json 一致。


2. 约定(时间、分页、错误)

时间

游标分页

多数列表接口:

{ "items": [ ... ], "has_more": true, "next_cursor": "123" }

错误格式

{ "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_minclaim 请求体 / list query最小邮箱 ID(含),正整数
id_maxclaim 请求体 / list query最大邮箱 ID(含),正整数
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
icloudemail----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

导入规则:

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 规则不变。

核心规则

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 邮箱走同样两个接口、同样的响应结构,区别:

{
  "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. 回写订阅

注册成功后必须回写,否则锁到期后该邮箱会再次被同一服务领取。

服务回写接口
snowflakePOST /api/snowflake-accounts(email_id + email_lock_token + 账号资料,见 README)
kiroPOST /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 一致)。

GET /api/emails/by-address/{email}

按完整地址精确取单个邮箱,返回结构同 GET /api/emails/{id}(风格同 /api/musecode-accounts/by-email/{email}/subscription)。

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,向后兼容,无需迁移): 后台邮箱列表每行「取件方式」按钮调用,弹窗展示取件方式说明与解密后的取件凭据(带复制按钮)。

providermethod取件方式返回的凭据
outlook(含 Hotmail)oauth_refresh_tokenclient_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
icloudicloud_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_allowlistMeta 系数组或逗号 / 换行分隔字符串,1–50 项;域名匹配该域及其子域,完整地址精确匹配。默认 facebookmail.com、facebook.com、fb.com、meta.com、metamail.com、instagram.com、mail.instagram.com、threads.net
window_minutes15只看最近多少分钟内到达的邮件,1–1440
notesnull备注,≤ 500 字符
{
  "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 毫秒>}):

{
  "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 秒(加密存放),缓存命中不算真实读信。

安全说明:

推荐流程

claim {service} → 注册 → 读验证码 → 成功:回写(snowflake / kiro / subscriptions)
                                    → 失败:release

6. 银行卡与账单地址

⚠️ 不兼容变更(OpenAPI 1.29.0,2026-10-25,无迁移):

  1. 用 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")。
  2. 一人一卡:同一锁定人(trim 后、ASCII 不区分大小写)同时只能持有一张领取锁定的卡;还没处理完上一张时再取卡 → 409,提示「请先处理完上一张锁定的卡」并返回 locked_card_id,见 6.8。
  3. 银行卡领取锁不再过期:原来的 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 必须带 email(当前使用该卡的账号邮箱);PATCH /api/cards/{id}/status 与 POST /api/cards/{id}/unlock 用 API token 调用时也必须带 email(后台登录会话可省略)。缺少 → 400 缺少字段: email(当前使用该卡的账号邮箱),格式无效 → 400 email 格式无效(例如 user@example.com,最长 254 个字符),此时不改卡、不写记录。旧调用方(例如不带请求体的取卡)升级后会收到 400,需先补上 email。每次调用都会写一条操作记录,见 6.17。Snowflake 账号接口(/api/snowflake-accounts/*,含订阅回写 POST /api/snowflake-accounts/{id}/subscription)不变:不要求 email,也不写卡操作记录。

认证: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 正交。

后台显示statuslock_kinddeleted_at含义
可用availablenullnull可被 claim 领取、出现在托管绑卡选卡列表
已锁定(领取)lockedclaimnullclaim 或托管绑卡选卡产生的锁,带 lock_token;不会自动过期(1.29.0 起),需 release / 改为已使用 / unlock 处理;lock_expires_at 恒为 null
已锁定(手动)lockedmanualnull管理员用 PATCH status 锁定,无 lock_token,不会自动过期
已使用usednullnull绑卡成功(订阅回写 / 托管绑卡完成)或管理员手动标记,记录 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 保持原值)

6.2 字段表(列表 / 详情)

字段类型说明
idinteger银行卡 ID
card_numberstring完整卡号(仅授权接口返回)
last4string卡号后 4 位
expiry_month / expiry_yearinteger有效期月 / 四位年
cvcstringCVC / CVV(3–4 位,字段名沿用 cvc)
holder_name / billing_addressstring | null旧版单字段持卡人 / 地址,新数据请用 billing_profiles
statusstringavailable / locked / used
lock_kindstring | nullstatus=locked 时为 claim 或 manual,否则 null
locked_atstring | null领取锁的加锁时间(手动锁为 null)
lock_expires_atnull已废弃,恒为 null(1.29.0 起领取锁不再过期,保留字段只为兼容)
locked_bystring | null锁定人(≤100 字符,见 6.16)。只有 status=locked 的卡可能有值;可用、已使用的卡为 null
used_atstring | null首次标记已使用的时间
notesstring | null备注(≤500 字符);来源:导入时的本批 notes、单卡写入的 notes、PATCH /api/cards/{id}/notes。列表、详情、领取都返回该字段,没有备注时为 null(不会省略)
bind_failure_countinteger累计绑卡失败次数
last_bind_failure_atstring | null最近一次失败时间
bound_emailstring | null已绑定的 Snowflake 账号邮箱
bound_snowflake_account_idinteger | null已绑定的 Snowflake 账号 ID
billing_profile_idinteger | null绑定时使用的账单地址 ID
deletedboolean是否已软删除
deleted_atstring | null软删除时间
created_at / updated_atstring创建 / 最近更新时间
billing_profilesarray账单地址,见下表(管理接口包含 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

参数默认说明
limit501–200
sortrecentrecent 按 ID 倒序(游标为卡 ID);status 按 可用 → 已锁定 → 已使用 归类(游标为偏移量)。后台页面默认传 status
cursor—上一页的 next_cursor
status—available / locked / used
notes—备注包含匹配(ASCII 不区分大小写)
locked_by—锁定人包含匹配(ASCII 不区分大小写,≤100 字符)。只有锁定中的卡有锁定人,因此结果都是锁定中的卡
deletedexcludeexclude 不含已删除;include 一并返回;only 只返回已删除

每条记录都带 notes(备注,无则 null),后台列表的「备注」列即该字段(长文本截断,悬停显示全文,点击可编辑)。

GET /api/cards?sort=status&limit=50
GET /api/cards?status=available&notes=批次 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" }]
}
// 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" 的账单地址,其余字段留空,在托管绑卡页人工补全

分列规则:

  1. 先去掉行首尾空白(含 Tab);空行忽略
  2. 行内有 Tab:按单个 Tab 切列,连续 Tab 产生空单元格并保留列位置(与表格对齐);各单元格去掉首尾空白后,若内部还有空白(Tab 与空格混用,如 卡号 1028<Tab>123<Tab>90001),再按空白拆成多列
  3. 行内没有 Tab:按任意连续空白切列(多个空格算一个分隔)
  4. 行尾的空列忽略;邮编为空等同于不填邮编
  5. 卡号 / 有效期 / CVV 为空 → 该行失败,错误为 卡号为空 / 有效期为空 / CVV为空(不会把后面的列前移错位)。有 Tab 的行缺少前 3 列时同样报对应列为空(如 卡号<Tab>1028 → CVV为空)
  6. 列数超过 4(含按位置第 5 列有值)或无 Tab 且不足 3 列 → 格式错误,应为「卡号 有效期 CVV 邮编(空格或 Tab 分隔)」
  7. 邮编中间不能有空格(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 始终保留。

逐行结果:有效行照常导入,失败行不影响其他行。错误只显示行号(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 }

选卡顺序(在 status = available 且未删除,以及可选的 notes / max_bind_failure_count 筛选之后):

  1. bind_failure_count ASC — 优先失败次数少的;
  2. last_bind_failure_at ASC — 次数相同时优先更早失败的(「冷却」更久);NULL(从未失败,或异常地有次数但无时间)按 SQLite ASC 排在有时间戳之前,即当作最旧;
  3. 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_byAPI 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
emailAPI 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 必须为布尔值
{ "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 的卡保留

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)

参数: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-assetsMuse 资产列表(明文 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/logsMuse 资产 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
}

这些接口不使用 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)按北京时间解释。

数据模型

字段类型说明
idinteger自增主键
emailstring邮箱,统一存小写,大小写不敏感唯一
email_idinteger / null关联的邮箱库存 ID。创建时若邮箱在库存中自动关联;库存邮箱被删除后置为 null
meta_user_idstring / nullMuseCode 侧用户 ID,最长 128;非空时唯一,可多个账号为空
registered_atstring注册时间,创建时可省略(当前时间)
notesstring / null备注,最长 2000
bank_card_last4string / null银行卡尾号(1.30.0 起,migration 0029):恰好 4 位数字的字符串(如 "4242",保留前导 0),只存后 4 位,不存完整卡号,不关联银行卡库;null = 未填。与 Muse 资产的 card_number / card_last4 无关
subscription_statusstring账号自身套餐状态:none(默认)/ trialing / active / past_due / cancelled / expired(拼写与 Snowflake subscription_bindings 对齐)
subscription_planstring / null套餐名,自由文本 ≤128,如 pro
subscription_started_atstring / null订阅开始(UTC 存,API 出 +08:00)
subscription_expires_atstring / null订阅到期
subscription_updated_atstring / null最近一次套餐字段更新时间(只读,写套餐时自动刷新)
subscription_metaobject / null明文 JSON ≤16KB,放供应商原始字段;勿放密钥
browser_fingerprintobject / null注册时的浏览器指纹,任意 JSON 对象,≤64KB,明文保存(仅详情返回完整内容)
proxy_ipstring / null代理出口 IP(IPv4 / IPv6,IPv6 存小写)
proxy_geoobject / null代理出口地理位置,≤8KB(键见下)
proxy_countrystring / null只读,取自 proxy_geo.country_code(大写),用于筛选
proxy_indexstring / null代理池索引 / 标识,≤128;整数会转成字符串(如 17 → "17"),便于兼容 pool-a:17 这类写法
auth_dataobject / null注册时的认证会话(cookies、storage、tokens、headers),≤1.4MB(明文 JSON;加密后约 ≤1.87MB,受 D1 单值/单行 2MB 上限约束),AES-GCM 加密保存(DATA_ENCRYPTION_KEY),只在详情接口解密返回
has_browser_fingerprint / has_auth_databoolean只读,是否保存了指纹 / 认证信息
fingerprint_summaryobject / null只读,从指纹提取的 user_agent、platform、timezone、language
auth_updated_atstring / null只读,最近一次写入 auth_data 的时间(清除时为 null)
created_at / updated_atstring记录创建 / 最后修改时间

注册上下文字段

{
  "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": "…" }
  }
}

校验规则:

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 的调用方可以读取明文,请妥善保管。

与邮箱订阅的关系

账号套餐 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_datatrue / false
registered_from注册时间下界(含);纯日期为当天 00:00:00(北京时间)
registered_to注册时间上界(含);纯日期为当天 23:59:59(北京时间)
notes备注包含匹配,忽略大小写,≤500 字符(1.31.0 起)
has_bank_card_last4true = 已填银行卡尾号,false = 未填(1.31.0 起)
curl "$BASE/api/musecode-accounts?q=outlook&registered_from=2026-10-01&registered_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_labelstrue 时表头用中文列名;默认用字段名(便于程序处理)
其他与 GET /api/musecode-accounts 相同的筛选参数(q、subscription_status、notes、has_bank_card_last4…);POST 中数字 / 布尔值会转成字符串

可导出列(默认列加 ★):

列说明
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,不会消耗领取锁。

成功响应 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": [] }

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」)。

数据模型

字段类型说明
idinteger主键
emailstring必填;去首尾空格后转小写存储,大小写不敏感唯一(重复 → 409)
invite_codestring | null账号自己的邀请码(允许重复);≤128 字符,去首尾空格,不能含控制字符;空串 / null = 无
registered_atstring注册时间;创建时不传 = 当前时间
free_plan_used_percentnumber | nullUsage · Free plan「x% used」;0–100,可小数,null = 未知
free_plan_resets_atstring | nullUsage · Free plan「Weekly limit resets on …」每周重置时间;null = 未知
additional_tokens_used_percentnumber | nullUsage · Additional tokens「x% used」;0–100,可小数,null = 未知
additional_tokens_leftinteger | nullUsage · Additional tokens 剩余 tokens(「1B tokens left」= 1000000000);非负整数,null = 未知
additional_tokens_expires_atstring | nullUsage · Additional tokens 到期时间;null = Never expires(或未知)
tier_idstring | null套餐 ID ← subscription.tier.tierId(如 hatch_free);0032
tier_namestring | null套餐名称 ← tier.name(如 Muse Free);0032
tier_codestring | null套餐代码 ← tier.tierCode(如 HATCH_FREE);0032
tier_is_paidboolean | null是否付费套餐 ← tier.isPaid;0032
free_plan_statestring | nullFree plan 计量状态 ← usage.state(HAR 中为 METERED;大写存储);0032
free_plan_quota_statusstring | nullFree plan 额度状态 ← usage.quotaStatus(HAR 中为 SUFFICIENT;大写存储);0032
free_plan_labelstring | nullFree plan 显示文案 ← usageRowValueLabel(如 0% used);0032
free_plan_subtitlestring | nullFree plan 副标题 ← statusSubtitle(如 Weekly limit resets on Nov 3);0032
topup_balanceinteger | nullAdditional tokens 余额,muse.ai 原始单位 ← topupBalance(推断 1 单位 = 25 tokens);0032
topup_totalinteger | nullAdditional tokens 总额,原始单位 ← topupTotal;0032
additional_tokens_labelstring | nullAdditional tokens 显示文案 ← topupRowValueLabel(如 0% used (1B tokens left));0032
topup_eligibleboolean | null是否可充值 ← topupEligible;0032
usage_rawobject | null最近一次解析的 subscription 原始结构(去掉 managementActions / agreement,≤16KB);仅详情返回;0032
usage_updated_atstring | nullUsage 最近写入时间:写入任一 Usage 字段时自动更新为当前时间;也可显式传入(例如外部程序抓取 Usage 的时间)
notesstring | null备注,≤2000 字符
browser_profile_idstring | null指纹浏览器 profile / 环境 ID(明文);≤128 字符,整数会转字符串,不能含控制字符
has_browser_fingerprintboolean是否已保存浏览器指纹(只读)
fingerprint_summaryobject | null只读;写入 browser_fingerprint 时派生的明文摘要 {user_agent, platform, timezone, language},供列表展示
fingerprint_updated_atstring | null浏览器指纹最近写入时间(只读)
proxy_ipstring | null代理出口 IP(IPv4 / IPv6,IPv6 存小写,明文)
proxy_geoobject | null代理地理位置 JSON(≤8KB,明文),结构同 MuseCode:country_code(两位)、country、region、city、latitude、longitude、timezone、isp、asn 等
proxy_countrystring | null只读;由 proxy_geo.country_code 派生的两位大写国家代码
proxy_indexstring | null代理池索引 / 标识(≤128,整数转字符串)
has_auth_databoolean是否已保存认证信息(只读)
auth_updated_atstring | null认证信息最近写入时间(只读)
created_at / updated_atstring创建 / 更新时间

仅详情接口返回(解密后):

字段类型说明
browser_fingerprintobject | 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_dataobject | 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 加密保存。

输入规则:

表中不保存账号密码。

接口

GET /api/museai-accounts

按 ID 倒序、cursor 分页(limit 默认 50,最大 200)。响应 {items, has_more, next_cursor}。

参数说明
q(别名 email)邮箱模糊搜索,忽略大小写
invite_code邀请码精确匹配
has_invite_codetrue / false
free_plan_exhaustedtrue = free_plan_used_percent ≥ 100;false = < 100 或未知
has_additional_tokenstrue = additional_tokens_left > 0;false = 为 0 或未知
additional_tokens_never_expirestrue = additional_tokens_expires_at 为 null;false = 有到期时间
tier_id套餐 ID 精确匹配(如 hatch_free)
tier_is_paid / topup_eligibletrue / 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_datatrue / 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 / 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)或后台登录会话均可调用。

字段说明
free_plan_used_percentFree plan 已用百分比,0–100(可小数,可写 "12.5%")
free_plan_resets_at每周重置时间:日期(视为北京时间 00:00)、ISO 8601(无时区按北京时间)或 Unix 秒(> 1e12 视为毫秒)
additional_tokens_used_percentAdditional tokens 已用百分比,0–100
additional_tokens_left剩余 tokens:非负整数,或 "1B" / "500M" / "2.5K"(1B = 1000000000,可带千分位逗号)
additional_tokens_expires_attokens 到期时间,格式同 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_subtitleFree plan 状态与文案(0032)
topup_balance / topup_total / additional_tokens_label / topup_eligibleAdditional tokens 原始余额 / 总额 / 文案 / 是否可充值(0032)
usage_updated_at可选,抓取时间;不传则为当前时间
subscription可选,muse.ai 原始结构(见下)
muse_response可选,与 subscription 二选一:整个 muse.ai 响应(对象或 JSON 字符串),或 Server Action 的 RSC 原文(见下)

可选:直接传 muse.ai 原始响应(0032 起 POST / PATCH / PUT …/usage 通用)。 接受以下任一形式,服务端拆分字段:

  1. subscription 字段:设置页 Server Action 响应中的 subscription 对象,或整个 {"success":true,"subscription":{…}};
  2. muse_response 字段:同上(对象或 JSON 字符串),或 RSC 原文字符串,如 "0:{\"a\":\"$@1\",…}\n1:{\"success\":true,\"subscription\":{…}}"(取第一行含 subscription 的 JSON);
  3. 仅 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.isPaidtier_id / tier_name / tier_code / tier_is_paid
usage.state / usage.quotaStatusfree_plan_state / free_plan_quota_status
usage.percentUsedfree_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
topupEligibletopup_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
statusunsubmitted(未提交,默认)/ 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" }

POST /api/muse-assets/import(批量上传)

单次最多 500 条。请求体任选:

{ "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

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。

{
  "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 验证结果并绑定到 SnowflakeX-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}/subscriptionsBearer / 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-accountsKiro 账号列表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 与 CreditsBearer / Cookie
GET/api/musecode-accountsMuseCode 账号列表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-accountsMuseAI 账号列表(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-accountsSnowflake 账号列表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 同理)

  1. POST /api/emails/claim 传 {"service":"musecode"} 领取邮箱。
  2. 用返回的 password / refresh_token 完成目标站点注册(验证码可用 GET /api/emails/{id}/messages)。
  3. 成功:调用对应回写接口(MuseCode → POST /api/musecode-accounts;Snowflake → POST /api/snowflake-accounts;Kiro → POST /api/kiro-accounts/callback),带上 email_id + email_lock_token。
  4. 失败:POST /api/emails/{id}/release 释放锁。
  5. 其他服务可走通用 POST /api/emails/{id}/subscriptions。

Snowflake 绑卡

  1. (可选)POST /api/cards/claim 取卡(带 email、locked_by)。
  2. POST /api/snowflake-accounts/{id}/bind-session 拿 magic_url,交给人工打开。
  3. 或自行完成 Stripe 后调用 POST /api/snowflake-accounts/{id}/subscription;失败则 POST /api/cards/{id}/release(带 email)。
  4. 每张卡的取卡 / 回写记录可在 GET /api/cards/{id}/history 或后台「操作历史」查看。

附录