批量导入邮箱
每行一个,可混合:
Outlook / Hotmail:email----password----client_id----refresh_token
iCloud:email----https://取件链接(分隔符 3 个以上 -,链接必须 https,链接中的邮箱需与本行一致;支持 icloud.mida.vip 的 /messages/邮箱?token= 和分享页 ?email=&auth_code= 等)
ACCOUNT OPERATIONS
每行一个,可混合:
Outlook / Hotmail:email----password----client_id----refresh_token
iCloud:email----https://取件链接(分隔符 3 个以上 -,链接必须 https,链接中的邮箱需与本行一致;支持 icloud.mida.vip 的 /messages/邮箱?token= 和分享页 ?email=&auth_code= 等)
粘贴单个账号 JSON;无需邮箱 ID 或锁令牌。若邮箱库存中存在同名且未订阅 snowflake 的邮箱,会关联并记录 snowflake 订阅。密码、TOTP Seed、Snowsight 认证信息和浏览器指纹会加密保存。
支持 JSON 数组、单个 JSON 对象或每行一个 JSON 对象;未使用的字段会自动忽略。
支持 JSON 数组、单个对象或每行一个 JSON 对象;必填 email 与 browser_fingerprint;可选 pats(JSON 数组,每条 {name, token, created_at?})、bank_card_last4、verification_url、套餐字段;单次最多 500 个
推荐每行一张卡:卡号 有效期 CVV 邮编,列之间用空格或 Tab 分隔(多个空格算一个;从表格复制时按 Tab 对齐列,空单元格保留位置,邮编可留空)。卡号不能带空格。有效期 MMYY(如 1028 = 2028 年 10 月),CVV 3–4 位,邮编为 5 位美国邮编,可省略(其余地址留空,绑卡时再补)。仍兼容旧的 JSON 数组格式(有效期 MM/YY,可带多条 billing_profiles,地址字段均可为空)。
通常由外部程序调用 POST /api/muse-assets 或 /api/muse-assets/import 上传;这里也可手动粘贴。每行 email api_key access_token [生成时间] [关联银行卡号],Tab 或空格分隔(与导出的 TSV 互通,首行表头 email… 自动跳过);也支持 JSON 数组。生成时间为北京时间,如 2026-10-23 12:00:00,留空为导入时间。同一 email + api_key 已存在时跳过。
REST API · V1
Base URL: · 全部接口已合并为一份在线中文文档
线上地址:/docs/(完整 URL:https://snow.51proxy.org/docs)。旧路径 /api-docs 会跳转至此。仓库源文件 docs/API.md 与 public/docs/ 同步;OpenAPI 版本见 openapi.json。
覆盖认证、统计、邮箱(领取/订阅/读信)、银行卡、Snowflake、托管绑卡、Kiro、MuseCode(含注册上下文)、Muse 资产,共 57 条路径。以下各节为常用摘要,细节以统一文档为准。
自动化调用均需发送生产 API Token。管理界面使用登录后签发的 HttpOnly Cookie。
Authorization: Bearer <API_TOKEN> Content-Type: application/json
领取接口返回的 lock_token 必须妥善保管;邮箱锁默认 15 分钟后失效;银行卡领取锁不会过期(1.29.0 起),同一锁定人同时只能持有一张,必须回写或 release 处理完。任务失败时应调用 release 主动释放。
查询邮箱列表。参数:q(按邮箱地址搜索,别名 email:去首尾空格、忽略大小写、包含匹配,% _ 按字面匹配,可与其他筛选及翻页叠加)、service、subscribed=true|false、claimable=true|false、suffix、provider=outlook|icloud、id_min / id_max(闭区间,正整数)、limit、cursor、order=asc|desc、sort=id。service=claude 返回已订阅 claude 的邮箱,加 subscribed=false 返回未订阅 claude 的邮箱;只传 subscribed=false 返回未订阅任何服务的邮箱。claimable=true 返回此刻用相同 service 调用 claim 能领到的邮箱(不传 service 时为旧版无 service 领取的口径),不能与 subscribed 同时使用。每条记录包含 subscriptions(已订阅服务)和 locks(未过期的领取锁,* 为旧版整邮箱锁),不返回密码和刷新令牌。排序默认 order=asc(ID 升序,最早导入在前;2026-10-19 前默认为降序),order=desc 为 ID 降序(最新在前);cursor 在升序时取 id > cursor、降序时取 id < cursor,翻页请保持相同的 order;sort 目前只支持 id。无效值返回 400。响应带 order 字段。
GET /api/emails?service=claude&claimable=true&suffix=outlook.com&limit=50 GET /api/emails?limit=50&cursor=50 # 默认升序:id > 50 GET /api/emails?order=desc&limit=50&cursor=100 # 降序:id < 100 GET /api/emails?q=alice&provider=icloud # 地址包含 alice 的 iCloud 邮箱
查询单个邮箱的地址、provider、client_id、subscriptions 和 locks,不返回密码、刷新令牌和 iCloud 取件链接。
按完整邮箱地址精确查询单个邮箱(忽略大小写、去首尾空格,地址需 URL 编码),返回结构同 GET /api/emails/{id};不存在返回 404。
GET /api/emails/by-address/alice.smith%40outlook.com
使用加密保存的 Microsoft OAuth 凭据优先通过 XOAUTH2/IMAP 读取最近邮件,同时返回收件箱和垃圾邮件箱;Graph Mail.Read 作为兼容回退。provider=icloud 的邮箱改为服务端请求加密保存的 https 取件链接(20 秒超时、不跟随重定向),响应结构相同,只有收件箱,邮件额外带 verification_code;可选 refresh=false 允许上游返回缓存。不会返回访问令牌、刷新令牌或取件链接。
取件方式详情:Outlook 返回 OAuth 说明与解密后的 client_id、refresh_token、密码;iCloud 返回解密后的取件链接。支持后台登录会话与 API Token,响应 no-store。
创建免登录的公开取件链接(expires_in 1h / 24h / 7d / never,默认 24h;sender_allowlist 默认 Meta 系;window_minutes 默认 15;可选 notes;不设使用次数上限,只受有效期、撤销与限频控制)。GET 列出链接、取到的验证码个数与访问记录,DELETE /api/emails/{id}/pickup-links/{linkId} 撤销。
公开接口(无需登录,供 /pickup/{token} 页面调用):只返回白名单发件人在时间窗口内的最新验证码、发件人、主题、到达时间;限频并统一返回「链接无效或已失效」。
通过 message_id 读取单封邮件的完整 HTML 正文。响应使用严格 CSP,供后台沙箱 iframe 展示富文本、图片及链接按钮。
批量导入邮箱,每行一个,可混合:Outlook email----password----client_id----refresh_token;iCloud email----https://取件链接(3 个以上连字符,链接必须 https 且邮箱一致,加密保存;支持 /messages/<邮箱>?token=、/api/messages?alias_email=&token=、/latest?email=&auth_code=、/mail-api/<授权码>/<邮箱>)。响应 imported / skipped(库中已存在)/ invalid / imported_by_provider / errors。
{
"data": "a@example.com----password----client_id----refresh_token\nalias@icloud.com----https://mail.example.com/latest?email=alias@icloud.com&auth_code=YOUR_AUTH_CODE"
}按服务原子锁定并返回一个邮箱。邮箱不再有“已使用”状态:一个邮箱可订阅多个不同服务,但同一服务只能订阅一次。传 service 时只返回未订阅该服务、且当前没有被该服务领取的邮箱,同一邮箱可同时被不同服务领取。可再传 suffix 精确选择邮箱后缀;可选 id_min / id_max(闭区间,正整数)限制候选 ID,按 id ASC 取范围内最小可用邮箱;范围内无可用时返回原有 404。可选 provider=outlook|icloud 只领取该类型;响应带 provider 与 fetch_url(iCloud 取件链接,outlook 为 null)。
兼容:不传 service 时按旧逻辑只返回未订阅任何服务且未被领取的邮箱,并锁住整个邮箱,回写接口决定记录的服务。
请求:{ "service": "claude", "suffix": "outlook.com", "id_min": 100, "id_max": 200 }
响应:
{
"id": 1,
"email": "a@example.com",
"password": "...",
"client_id": "...",
"refresh_token": "...",
"service": "claude",
"lock_token": "uuid",
"locked_at": "2026-09-23T18:00:00+08:00",
"subscriptions": [{ "service": "snowflake", "account_ref": "snowflake_accounts:9", "created_at": "..." }]
}注册失败时释放本次领取的锁(只释放该服务的锁,不影响其他服务)。
请求:{ "lock_token": "领取时返回的令牌" }
响应:{ "released": true, "email_id": 1, "service": "claude" } // 不带 service 领取的锁 service 为 null记录邮箱订阅了某个服务。外部注册程序(claude、openai 等没有专用回写接口的服务)传 lock_token 回写,会校验该服务的领取锁并消耗;不传 lock_token 为管理员手动登记。同一邮箱同一服务重复登记返回 409。POST /api/emails/{id}/mark-used 为已废弃别名,同样必须传 service。
{
"service": "claude",
"lock_token": "领取时返回的令牌(可选)",
"account_ref": "外部账号或订单号(可选)",
"notes": "备注(可选)"
}管理员删除订阅记录,删除后该邮箱可再次被领取用于该服务。迁移时无法识别服务的旧“已使用”邮箱记为 legacy,对所有服务都不可领取,删除 legacy 记录即可释放。
status:available 可用 / locked 已锁定 / used 已使用。已锁定再用 lock_kind 区分:claim 领取或托管选卡的锁(有 lock_token);manual 管理员手动锁定。1.29.0 起两种锁都不会过期(lock_expires_at 恒为 null),需 release / 回写 / 解锁处理。已删除为软删除标记 deleted_at,与 status 独立。典型流程:导入 → claim → 绑卡成功回写 /api/snowflake-accounts/{id}/subscription(卡变为已使用)/ 失败 release(失败次数 +1)。完整状态图、字段表与错误码见统一文档第 6 节。
查询银行卡列表(仅已授权管理员,返回完整卡号、CVC、账单地址、失败次数、绑定信息、备注 notes(无则 null)、lock_kind、lock_expires_at、锁定人 locked_by)。参数:sort=recent|status(默认 recent)、status=available|locked|used、notes(备注包含)、locked_by(锁定人包含)、deleted=exclude|include|only(默认不含已删除)、limit、cursor。
单卡详情,字段同列表项。已删除的卡返回 404,加 ?include_deleted=true 可查看(带 deleted_at)。
添加单张银行卡。有效期可用 expiry_month + expiry_year 或 expiry(MMYY / MM/YY);notes、billing_profiles 可选,地址可为空(省略时补一条空地址)。与未删除的卡重复返回 409 并附 existing_id;与已删除的卡重复则按导入同一规则恢复,返回 200:{ id, created: false, restored: true, status, notes, billing_profiles_created }。
{
"card_number": "4242424242424242",
"expiry": "12/30",
"cvc": "123",
"notes": "批次 A",
"billing_profiles": [{ "first_name": "Jane", "postal_code": "90001", "country": "US" }]
}批量导入银行卡。推荐文本格式:data 每行 卡号 有效期 MMYY CVV 邮编(空格或 Tab 分隔:有 Tab 时按 Tab 对齐列位置、空单元格保留,否则按连续空白分列;卡号不能带空格,卡号 / 有效期 / CVV 为空时报出对应列)(邮编 5 位美国邮编,可省略),可选 notes 写到本批每张卡;逐行校验,results 逐行返回 created / updated / 失败原因(只含行号与尾号)。重复卡会更新有效期与 CVC、追加新账单地址,状态和失败次数不变;已删除的卡会恢复为未删除(used 仍为 used、available 不变;未绑定的 locked 清锁改为 available;失败次数保留),行内带 deleted: true、restored: true、restored_status,计数 cards_restored。仍兼容 JSON 格式(账单地址字段均可为空):
{ "data": "4242424242424242\t1028\t123\t90001\n4000056655665556\t0329\t456", "notes": "批次 A" }{
"data": [{
"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",
"status": "available"
}]
}]
}原子锁定并返回一张可用银行卡的完整资料、lock_token、lock_expires_at(恒为 null,锁不过期)、status: "locked"、lock_kind: "claim"、locked_by、notes。选卡优先失败次数少的,次数相同优先更早 last_bind_failure_at(NULL 当最旧),再按 ID 升序。请求体必填 email(当前使用该卡的账号邮箱,1.28.0 起,不兼容变更;缺少或格式无效返回 400);可选筛选 notes(备注包含)与 max_bind_failure_count(失败次数上限);API token 调用必填 locked_by 锁定人(≤100 字,1.29.0 起,缺少返回 400;后台登录可不填,缺省记 admin,admin 同样一人一卡)。一人一卡:同一锁定人(trim 后不区分大小写)已持有一张领取锁定的卡时再取卡返回 409「请先处理完上一张锁定的卡」并带 locked_card_id(不含卡号);处理完(release / 改为已使用 / 解锁)后可再取。锁定人在释放 / 解锁 / 改为可用 / 变为已使用时清空。
{ "email": "user@example.com", "notes": "批次 A", "max_bind_failure_count": 2, "locked_by": "worker-01" }绑卡失败时释放领取锁,并原子递增该卡的绑卡失败次数;返回 id、status、bind_failure_count。令牌失效返回 409。email 必填。
{ "lock_token": "领取时返回的令牌", "email": "user@example.com" }管理员强制释放银行卡锁定(临时锁或手动锁)并清除未完成绑卡会话中的选卡状态,不增加失败次数,清空锁定人;返回 previous_lock_kind、previous_locked_by。API token 调用须带 {"email": "user@example.com"},后台登录可省略。
银行卡操作历史(只读):取卡、回写完成 / 失败、改状态、释放锁定(「锁超时释放」仅为 1.29.0 之前的历史记录),每条含时间、账号 email、操作、结果、备注、来源,最新在前;支持 limit(≤200)与 cursor。已存在卡上被拒绝的调用(409)记为「被拒绝」;参数校验失败(400)不记录;Snowflake 账号接口(含订阅回写)不写记录。记录不含卡号与 CVC,永久保存(删卡不清理)。后台银行卡列表每行「操作历史」按钮可查看。
修改银行卡状态:available 可用 / locked 已锁定(手动锁定不会自动释放)/ used 已使用。失败次数保留;已绑定 Snowflake 账号的卡不能改为可用(409)。可选 increment_bind_failure: true:在同一次更新里把失败次数 +1 并更新最近失败时间,响应的 failure_recorded 表示是否已 +1;状态与当前相同时可用来只做 +1。非布尔值返回 400,409 / 404 时不会 +1。改为 locked 时 API token 调用必填 locked_by(锁定人,≤100 字,1.29.0 起;后台登录未传为 admin;手动锁不受一人一卡限制;其他状态传了返回 400);改为 available 或 used 时清空锁定人。API token 调用须带 email(后台登录可省略),每次调用写入该卡的操作历史。
{ "status": "locked", "increment_bind_failure": true, "locked_by": "alice", "email": "user@example.com" }修改银行卡备注(≤500 字符,null 或空串清空)。
{ "notes": "批次 A" }批量软删除银行卡(写入 deleted_at,数据保留)。已删除的卡不再出现在默认列表、领取、绑卡选卡和统计中(统计单独计入 cards_deleted);锁定中的卡会被跳过。单次最多 500 个 ID。
请求:{ "ids": [12, 13, 14] }
响应:{ "requested": 3, "deleted": 1, "deleted_ids": [12], "skipped_locked_ids": [13], "already_deleted_ids": [], "not_found_ids": [14] }为指定银行卡单独导入一个或多个账单地址。重复地址会更新资料及状态;status 支持 available 或 unavailable。
{
"data": [{
"first_name": "Jane", "last_name": "Doe", "address": "1 Main St",
"country": "US", "state_province": "CA", "city": "Los Angeles",
"postal_code": "90001", "status": "available"
}]
}切换账单地址状态。不可用地址仍显示在管理列表,但不会用于领取银行卡或绑卡选择。卡已删除返回 404。
{ "status": "unavailable" }查询 Snowflake 账号列表,支持 limit 参数。has_mfa 表示账号是否配置 MFA,接口不会返回 totp_seed。响应中的 account_identity 从主机名提取。
注册成功后回写 Snowflake 账号,并原子地记录邮箱的 snowflake 订阅(邮箱锁须由 service: "snowflake" 或不带 service 的领取获得)。重复提交相同结果会返回 idempotent: true。
{
"email_id": 1,
"email_lock_token": "邮箱锁令牌",
"username": "user_name",
"password": "snowflake-password",
"account_name": "ORG-ACCOUNT",
"host": "example.snowflakecomputing.com",
"region": "us-east-1",
"registration_metadata": {
"schema_version": 1,
"browser": {
"engine": "camoufox",
"version": "152.0.4-beta.31",
"fingerprint_id": "954f8caa99c3021f",
"fingerprint": {}
},
"network": {
"exit_ip": "38.92.27.28",
"proxy": "http://127.0.0.1:7890"
},
"captured_at": "2026-09-29T12:00:00Z"
},
"totp_seed": "JBSWY3DPEHPK3PXP",
"snowsight_auth": {
"apps_api_origin": "https://apps-api.c1.us-east-1.aws.app.snowflake.com",
"cookie_header": "S8_SESSION=...; user-...=...; S8_SESSION_USER__...=...; csrf-...=...",
"csrf_token": "...",
"snowflake_context": "USER::https://ACCOUNT.us-east-1.snowflakecomputing.com",
"numeracy_user_id": "123456789",
"numeracy_client_version": "main-..."
},
"notes": "可选备注"
}读取加密保存的版本化注册元数据,包括浏览器指纹、当时出口 IP、代理和采集时间。列表接口只返回 has_registration_metadata,不会批量返回详细特征。
直接导入一个 Snowflake 账号,无需邮箱 ID 或锁令牌。若邮箱库存存在同名且未订阅 snowflake 的邮箱,将在同一事务中关联账号并记录 snowflake 订阅。请求体可直接传账号对象,也可以传 { "data": "JSON 字符串" };敏感字段加密保存。
按 PyOTP 默认参数生成当前 6 位 MFA 验证码,返回 remaining_seconds、expires_at 和 server_time。账号未配置 MFA 时返回 404。
{
"code": "123456",
"remaining_seconds": 18,
"expires_at": "2026-09-26T20:00:30+08:00",
"server_time": "2026-09-26T20:00:12+08:00"
}单独刷新已过期的 Snowsight Cookie 和认证上下文。请求体包含与注册回写相同的 snowsight_auth 对象。
使用保存的会话或账号用户名/密码自动获取并保存 Snowsight 认证信息。请求体为 {};保存会话过期时自动尝试重新 OAuth 登录。
未标记账号实时调用 Snowflake 查询是否已绑卡,首次查到已绑卡后永久写入标记;已标记账号直接返回缓存结果。
通过 status=bound|unbound 筛选并导出全部已绑卡或未绑卡账号;默认导出已绑卡。每行格式为 ACCOUNT-IDENTITY 用户名 密码 totp-seed,未配置 TOTP 时第四个字段为空。
绑卡和订阅成功后进行第二次回写,并原子地将银行卡标记为已使用。相同账号与银行卡的重试是幂等的。
{
"card_id": 1,
"card_lock_token": "银行卡锁令牌",
"email": "user@example.com",
"billing_profile_id": 2,
"subscription_status": "active",
"subscription_plan": "Business Critical",
"external_subscription_id": "sub_123",
"notes": "可选备注"
}优先复用注册时保存的 Snowsight 会话直接获取 SetupIntent;旧账号没有保存认证信息时才尝试 OAuth 登录。返回 5–15 分钟有效的人工绑卡链接。
{ "ttl_seconds": 600 }
响应:
{
"bind_session_id": "uuid",
"magic_url": "https://snow.51proxy.org/bind?...",
"expires_in": 600
}查询 Kiro 账号列表,支持 limit、cursor 分页参数。已授权响应包含解密后的邮箱、密码、AccessToken、RefreshToken、mfaSecret 以及可选 UserId。
写入单个 Kiro 账号。邮箱不可重复;三个凭据字段可省略、传 null 或空字符串,非空值使用 AES-GCM 加密保存。
{
"email": "user@example.com",
"password": "kiro-password",
"AccessToken": "access-token",
"RefreshToken": "refresh-token",
"mfaSecret": "mfa-secret",
"UserId": "可选"
}批量导入 Kiro 账号。支持 JSON 数组、单个对象或每行一个 JSON 对象;只读取账号所需字段,其他字段自动忽略。重复邮箱会跳过,单条格式错误不影响其他有效账号。
外部注册程序在 Kiro 注册成功后回写账号。三个凭据字段均可为空;接口校验领取邮箱时得到的锁令牌,原子保存账号并记录邮箱的 kiro 订阅(邮箱锁须由 service: "kiro" 或不带 service 的领取获得);同一邮箱重复回写幂等。
{
"email_id": 1,
"email_lock_token": "领取邮箱时返回的令牌",
"password": "kiro-password",
"AccessToken": "access-token",
"RefreshToken": "refresh-token",
"mfaSecret": "mfa-secret",
"UserId": "可选"
}使用账号保存的 AccessToken、RefreshToken 和可选 UserId 访问 Kiro;若 UserId 为空则为初始 Cookie 生成随机值。按 Kiro Web Portal 的 CBOR 协议刷新 Plan、Credits 已用/总额及额度重置时间。
查询 MuseCode 账号列表,按 ID 倒序,limit(默认 50,最大 200)+ cursor 游标分页。筛选:q(邮箱模糊搜索,大小写不敏感)、meta_user_id(精确)、proxy_index(精确)、bank_card_last4(银行卡尾号,4 位数字精确匹配)、proxy_country(两位国家代码,取自 proxy_geo.country_code)、proxy_ip(精确)、has_auth_data=true|false、subscription_status、subscription_plan、subscription_expires_from / subscription_expires_to、registered_from / registered_to(注册时间区间,ISO 8601;纯日期按北京时间,registered_to 为纯日期时包含当天)、notes(备注包含,1.31.0 起)、has_bank_card_last4=true|false(1.31.0 起)。响应含 bank_card_last4(银行卡尾号,4 位数字或 null)与账号套餐字段 subscription_status(默认 none)等;与邮箱 email_subscriptions 无关。列表不返回完整指纹和认证信息,只返回 fingerprint_summary、has_browser_fingerprint、has_auth_data、auth_updated_at。
响应:
{
"items": [{ "id": 1, "email": "user@example.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" }],
"has_more": false,
"next_cursor": null
}导出 MuseCode 账号 CSV(1.31.0 起):筛选参数与列表相同;传 ids(≤1000)只导出勾选的账号;columns 选择导出列(逗号分隔或数组,未知 / 敏感列 400),省略用默认列;header_labels=true 表头用中文。UTF-8 带 BOM、首行表头、按 ID 升序,单次最多 10000 条;以 = + - @ 开头的单元格前加 ' 防公式注入。文件名 musecode-accounts-YYYYMMDD-HHMMSS.csv(北京时间)。auth_data 与完整浏览器指纹不可导出;只读,不写调用日志。
{ "ids": [1, 2, 3], "columns": ["id", "email", "subscription_status", "bank_card_last4"], "header_labels": false }查询单个账号(不存在返回 404)。在列表字段基础上额外返回完整 browser_fingerprint 和解密后的 auth_data(没有则为 null;无法解密返回 500)。这是唯一返回认证信息明文的接口,请妥善保管响应。
browser_fingerprint:任意 JSON 对象(≤64KB),推荐键 user_agent、platform、language、timezone、screen、webgl、canvas_hash、fonts;明文保存。proxy_ip:IPv4/IPv6。proxy_geo:JSON 对象(≤8KB),推荐键 country_code(两位,自动转大写并写入可筛选的 proxy_country)、country、region、city、latitude、longitude、timezone、isp、asn。proxy_index:代理池索引,字符串(整数会转成字符串,≤128)。auth_data:JSON 对象(≤1.34MB),使用 AES-GCM 加密保存,推荐结构 cookies[](name、value 必填,domain、path、expires、httpOnly、secure、sameSite 可选)、localStorage、sessionStorage、tokens、headers;写入时更新 auth_updated_at。PATCH 传 null 清除对应字段;未传的字段保持不变。调用方 JSON 原样保存和返回,内部的时间字段不做时区转换。
{
"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": "…", "domain": ".musecode.example", "path": "/", "httpOnly": true, "secure": true }],
"localStorage": {}, "sessionStorage": {},
"tokens": { "access_token": "…", "refresh_token": "…" },
"headers": {}
}
}新增账号。邮箱(存小写)与非空 meta_user_id 均唯一,重复返回 409。registered_at 可省略(当前时间),不带时区时按北京时间解释。邮箱在库存中时自动关联 email_id 并记录 musecode 订阅;该邮箱已订阅 musecode 时返回 409。可选 bank_card_last4(银行卡尾号:恰好 4 位数字字符串,只存尾号不存卡号;null / 空字符串为不填;格式错误 400)。
{ "email": "user@example.com", "meta_user_id": "1234567890", "registered_at": "2026-10-19T12:00:00+08:00", "notes": "可选", "bank_card_last4": "4242" }
外部注册程序回写(邮箱锁须由 service: "musecode" 或不带 service 的领取获得,成功后锁被消耗;同一邮箱重试幂等):
{ "email_id": 12, "email_lock_token": "领取返回的 lock_token", "meta_user_id": "1234567890",
"browser_fingerprint": { … }, "proxy_ip": "203.0.113.7", "proxy_geo": { … }, "proxy_index": "pool-a:17", "auth_data": { … } }
响应(201)不含 auth_data 明文,只有 has_auth_data / auth_updated_at。部分更新 email、meta_user_id(传 null 或空字符串清除)、registered_at、notes、bank_card_last4(null 或空字符串清除)以及注册上下文字段(见下)。修改邮箱会把 musecode 订阅从旧库存邮箱移到新邮箱,新邮箱已订阅 musecode 时返回 409。
单独更新银行卡尾号:只改 bank_card_last4,其他字段忽略、不受影响。请求体必须含 bank_card_last4 键:4 位数字字符串设置,null 或空字符串清空;缺少或格式错误 400,账号不存在 404。后台列表「银行卡尾号」列点击即调用此接口。按邮箱定位用 PUT /api/musecode-accounts/by-email/{email}/bank-card-last4(路径需 URL 编码)。
{ "bank_card_last4": "4242" }
{ "bank_card_last4": null }轻量回写 MuseCode 账号自身套餐状态(≠ 邮箱 email_subscriptions)。字段均可选,至少传一个:subscription_status(none|trialing|active|past_due|cancelled|expired,与 Snowflake 拼写对齐)、subscription_plan、subscription_started_at、subscription_expires_at、subscription_meta(JSON 对象 ≤16KB)。更新时自动写 subscription_updated_at。
{ "subscription_status": "active", "subscription_plan": "pro", "subscription_expires_at": "2026-12-31T23:59:59+08:00" }同上,按邮箱定位(路径需 URL 编码)。外部程序只知邮箱时使用。
删除账号。默认保留邮箱的 musecode 订阅记录(该邮箱不会再被 musecode 领取);加 ?release_subscription=true 同时删除订阅,使邮箱可再次用于 musecode。
响应:{ "id": 1, "deleted": true, "subscription_released": false }批量导入,格式同 Kiro 导入(JSON 数组、单个对象或 NDJSON,可包在 {"data": ...} 中),单次最多 500 条,每条可带可选 bank_card_last4。已存在的邮箱 / meta_user_id 跳过;库存中已订阅 musecode 的邮箱在 errors 中列出。
响应:{ "imported": 2, "skipped": 1, "errors": ["第 3 条:email 无效"] }email(必填,存小写,大小写不敏感唯一,重复 409)、invite_code(账号自己的邀请码,≤128,允许重复)、registered_at(不传 = 当前时间)。Usage 对应 MuseAI 后台 Usage 面板,均可空(null = 未知):free_plan_used_percent(Free plan「x% used」,0–100,可小数)、free_plan_resets_at(「Weekly limit resets on …」)、additional_tokens_used_percent(0–100)、additional_tokens_left(剩余 tokens,非负整数,可传 "1B" / "500M" / "2.5K",1B = 1000000000)、additional_tokens_expires_at(null = Never expires)。时间字段按北京时间解析,仅日期 = 当日 00:00。写入任一 Usage 字段时自动更新 usage_updated_at(也可显式传入)。不保存密码 / 令牌 / 会话,不关联邮箱库存。上传成功后记录 sku_uploaded_at(入库时间,+08:00,null=未入库)与派生 sku_status(warehoused/not_warehoused)。需迁移 0030(OpenAPI 1.32.0)、0037(OpenAPI 1.42.0)。
列表,按 ID 倒序,limit(默认 50,最大 200)+ cursor。筛选:q(邮箱包含)、invite_code(精确)、has_invite_code、free_plan_exhausted(已用 ≥100%)、has_additional_tokens(剩余 >0)、additional_tokens_never_expires、tier_is_paid、topup_eligible(均为 true/false)、tier_id、free_plan_state / free_plan_quota_status(精确,不区分大小写)、sku_status(warehoused=已入库、not_warehoused=未入库)、registered_from / registered_to(北京时间)、notes(备注包含)。
新增账号,返回 201 与 created:true。
{
"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": "可选"
}也可传 subscription / muse_response(muse.ai 原始响应),服务端拆分出套餐、Free plan 与 Additional tokens 字段。
详情(含 usage_raw)/ 部分更新(传值替换、传 null 清除、不传不变;email、registered_at 不可清除)/ 直接删除(物理删除)。
同上,按邮箱定位(路径需 URL 编码,大小写不敏感)。外部程序回写 Usage 时使用,例如 PATCH …/by-email/user%40example.com {"free_plan_used_percent":12.5,"additional_tokens_left":"950M"}。
用量回写(API token 或登录会话):只更新传入的 Usage 字段,自动刷新 usage_updated_at;时间可传日期 / ISO / Unix 秒,additional_tokens_expires_at:null = Never expires。可直接提交 muse.ai 设置页 Server Action 的原始响应:整个 {"success":true,"subscription":{…}}、subscription / muse_response 字段,或 Content-Type: text/x-component 的 RSC 原文;服务端写入 tier_*、free_plan_state / free_plan_quota_status / 文案、topup_balance / topup_total(原始单位,1 单位 ≈ 25 tokens)/ topup_eligible 及旧字段(文案「0% used (1B tokens left)」优先)。账号不存在 404。
批量上传 MuseAI 账号到 SKU 仓库 sku.51proxy.org:请求体 {ids: number[]},上限 500、自动去重。按 email(小写)反查 emails 库存,查不到进 skipped(原因“邮箱不在库存中,无法创建取件链接”);为每个命中邮箱确保永久取件链接(expires_at IS NULL AND window_minutes=15 AND revoked_at IS NULL 的最新一条复用,否则新建 expires_in=never / window_minutes=15;邮箱缺少取件凭证进 skipped)。服务端每次登录 SKU(POST /api/auth/login,凭据来自 Worker secret SKU_API_ACCOUNT / SKU_API_PASSWORD,未配置 503 且不新建链接)再调 POST /api/admin/products/import(需 201)。响应 partial-success:{requested, submitted, imported, sku_imported, uploaded_ids, skipped:[{id,email,reason}], not_found_ids, pickup_links:[{id,email,url,email_id,link_id,reused}], sku_error?, warning?, sku_status_failed_ids?};imported 取 SKU 返回的总数,与提交数不一致时 warning 说明且 uploaded_ids=[];成功且 SKU 总数对上后写 sku_uploaded_at,uploaded_ids 既是“本次提交且 SKU 计数确认的 id”也是“本次新标记已入库的 id”,写入失败时 200 + warning(含“本地状态未写入”与 ids)+ sku_status_failed_ids;重复上传不拦截、刷新入库时间(SKU 去重行为待确认)。verificationUrl 为刚确保的永久取件链接;认证正文与浏览器指纹只传布尔标记,绝不外发。
查询 ChatGPT 账号列表,按 ID 倒序,limit(默认 50,最大 200)+ cursor 游标分页。筛选:q(邮箱模糊搜索,大小写不敏感)、browser_profile_id(精确)、has_browser_fingerprint=true|false、has_auth_data=true|false、proxy_index(精确)、proxy_country(两位国家代码,取自 proxy_geo.country_code)、proxy_ip(精确)、bank_card_last4(银行卡尾号,4 位数字精确匹配)、has_bank_card_last4=true|false、subscription_status、subscription_plan、registered_from / registered_to(注册时间区间,ISO 8601;纯日期按北京时间,registered_to 为纯日期时包含当天)、notes(备注包含)。响应含 bank_card_last4(银行卡尾号,4 位数字或 null)与账号套餐字段 subscription_status(默认 none)等;与邮箱 email_subscriptions 无关。列表不返回完整指纹和认证信息,只返回 fingerprint_summary、has_browser_fingerprint、has_auth_data、auth_updated_at。
响应:
{
"items": [{ "id": 1, "email": "user@example.com", "email_id": 12, "browser_profile_id": "profile-123",
"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" }],
"has_more": false,
"next_cursor": null
}导出 ChatGPT 账号 CSV:筛选参数与列表相同;传 ids 只导出勾选的账号;columns 选择导出列(逗号分隔或数组,白名单外 / 未知 / 敏感列 400),省略用默认列;header_labels=true 表头用中文。禁止导出 auth_data、auth_data_enc、browser_fingerprint。UTF-8 带 BOM、CRLF 换行、首行表头、按 ID 升序,单次最多 10000 条;以 = + - @ 开头的单元格前加 ' 防公式注入。文件名 chatgpt-accounts-YYYYMMDD-HHMMSS.csv(北京时间)。只读,不写调用日志。
{ "ids": [1, 2, 3], "columns": ["id", "email", "subscription_status", "bank_card_last4"], "header_labels": false }查询单个账号(不存在返回 404)。在列表字段基础上额外返回完整 browser_fingerprint 和解密后的 auth_data(没有则为 null;无法解密返回 500)。这是唯一返回认证信息明文的接口,请妥善保管响应。
新增账号。邮箱存小写、大小写不敏感唯一,重复返回 409。registered_at 可省略(当前时间),不带时区时按北京时间解释。邮箱在库存中时自动关联 email_id 并记录 chatgpt 订阅;该邮箱已订阅 chatgpt 时返回 409。可选 bank_card_last4(银行卡尾号:恰好 4 位数字字符串,只存尾号不存卡号;null / 空字符串为不填;格式错误 400)。带锁的外部注册回写幂等:同一 email_id 重试返回已有账号,不新建。
{
"email": "user@example.com",
"browser_profile_id": "profile-123",
"registered_at": "2026-10-19T12:00:00+08:00",
"notes": "可选",
"bank_card_last4": "4242"
}部分更新 email、browser_profile_id(传 null 或空字符串清除)、registered_at、notes、bank_card_last4(null 或空字符串清除)以及注册上下文字段。修改邮箱会把 chatgpt 订阅从旧库存邮箱移到新邮箱,新邮箱已订阅 chatgpt 时返回 409。
轻量回写 ChatGPT 账号自身套餐状态(≠ 邮箱 email_subscriptions)。字段均可选,至少传一个:subscription_status(none|trialing|active|past_due|cancelled|expired)、subscription_plan、subscription_started_at、subscription_expires_at、subscription_meta(JSON 对象 ≤16KB)。更新时自动写 subscription_updated_at。
{ "subscription_status": "active", "subscription_plan": "Plus", "subscription_expires_at": "2026-12-31T23:59:59+08:00" }同上,按邮箱定位(路径需 URL 编码)。外部程序只知邮箱时使用。
单独更新银行卡尾号:只改 bank_card_last4,其他字段忽略、不受影响。请求体必须含 bank_card_last4 键:4 位数字字符串设置,null 或空字符串清空;缺少或格式错误 400,账号不存在 404。后台列表「银行卡尾号」列点击即调用此接口。按邮箱定位用 PUT /api/chatgpt-accounts/by-email/{email}/bank-card-last4(路径需 URL 编码)。
{ "bank_card_last4": "4242" }删除账号。默认保留邮箱的 chatgpt 订阅记录(该邮箱不会再被 chatgpt 领取);加 ?release_subscription=true 同时删除订阅,使邮箱可再次用于 chatgpt。
响应:{ "id": 1, "deleted": true, "subscription_released": false }批量导入,格式同 Kiro 导入(JSON 数组、单个对象或 NDJSON,可包在 {"data": ...} 中),单次最多 500 条,每条可带可选 bank_card_last4。已存在的邮箱跳过;库存中已订阅 chatgpt 的邮箱在 errors 中列出。
响应:{ "imported": 2, "skipped": 1, "errors": ["第 3 条:email 无效"] }同 /{id} 接口,按邮箱定位(路径需 URL 编码,大小写不敏感):详情(含完整指纹与解密后的认证信息)/ 部分更新 / 删除(默认保留 chatgpt 订阅,?release_subscription=true 释放)。外部程序只知邮箱时使用。
每条记录:email(存小写)、api_key、access_token(两者 AES-GCM 加密保存,不能含空白/控制字符)、generated_at(生成时间,北京时间,不传为写入时间)、created_by(≤100,可空;不传时 API Token 调用记 null、后台会话记 admin)、status(unsubmitted 未提交 / submitted 已提交,默认未提交,也接受中文)、notes(≤500)。去重:未删除记录中 email + api_key 唯一,同一 email 可有多个不同 api_key。
列表,默认 ID 升序,limit(默认 50,最大 200)+ cursor,order=asc|desc。筛选:status、q / email(包含匹配)、created_by、notes(包含、忽略大小写)、card_last4(卡号后 4 位 / none / any)、deleted=exclude|include|only。返回明文 api_key / access_token / card_number 及 total。
上传一条,新建返回 201;未删除记录中同 email(不分大小写)+ api_key 已存在时更新该记录的 access_token(显式带了 generated_at / notes 时一并更新;created_by、status 不变),返回 200 + updated: true。
{ "email": "user@example.com", "api_key": "sk-example", "access_token": "example-token", "generated_at": "2026-10-23 12:00:00", "created_by": "uploader-1", "card_number": "4242424242424242" }批量上传(≤500 条):JSON 数组,或 { "data": 数组或文本, "created_by", "status", "notes" }(本批默认值,行内字段优先)。文本每行 email api_key access_token [generated_at] [card_number],Tab 或空白分隔(最后一列为 12–19 位纯数字时识别为卡号)。已存在的记录更新 access_token(action: "updated"),新记录 action: "created";同批内重复以最后一行为准,较早的行 action: "duplicate"(带 superseded_by);响应含 created / updated / duplicates / failed 计数与逐行 results。
查看 / 部分更新 status、notes、created_by、card_number(null 或空字符串清除)、generated_at、email、api_key、access_token。改状态时更新 status_updated_at。
批量改状态(ids ≤1000)。
{ "ids": [1, 2, 3], "status": "submitted" }批量软删除(ids ≤1000),删除后不出现在列表、导出和统计中,同 email + api_key 可重新上传。
Muse 资产写操作调用日志(create / import / update / batch_status / batch_delete / export)。摘要已脱敏,不含 api_key / access_token;列表与详情不记。可按 action、caller_type、ok 筛选。
导出 TSV(text/tab-separated-values,UTF-8):每行 email\tapi_key\taccess_token,按 ID 升序,默认无表头(header=true 加表头)。传 ids 导出选中记录,否则按 status / email / created_by / notes 筛选导出全部。导出不改变状态。
POST /api/muse-assets/export
{ "ids": [1, 2, 3] }
GET /api/muse-assets/export?status=unsubmitted返回邮箱、银行卡、Snowflake、Kiro、MuseCode 账号及 Muse 资产库存统计(musecode_total、musecode_linked 为已关联库存邮箱的数量;muse_assets_total / muse_assets_unsubmitted / muse_assets_submitted)。email_services 按服务列出 subscribed(已订阅)、locked(领取中)、available(当前可按该服务领取);可加 ?service=xxx 额外统计一个尚无记录的服务。emails_available 为不带 service 领取时可用的数量。
管理界面登录并签发 8 小时 HttpOnly Cookie。
{ "password": "管理员密码" }退出管理界面并清除 Cookie。
检查当前管理会话状态。
POST /api/emails/claim 并传 service(如 snowflake)领取邮箱。POST /api/cards/claim。refresh_token 自行读取,或调用 GET /api/emails/{id}/messages)。POST /api/snowflake-accounts 保存账号并消耗锁定资源;其他服务调用 POST /api/emails/{id}/subscriptions。release 接口。