注册 API

注册 API

XSI 内置邮箱自助注册。注册通过激活链接完成:用户提交邮箱,收到邮件后打开链接确认,账号随即创建,API Key 显示在确认页面并通过欢迎邮件发送。

  • 总开关:环境变量 SIGN_ENABLE(默认 true)。关闭时所有 /x-sign 请求返回 403 {"success": false, "message": "Self-registration is currently disabled"}。
  • 依赖邮件服务:激活邮件通过 Redis 队列交给独立的邮件服务投递,开放注册前请先完成邮件配置。
  • 新账号的归属取决于部署模式,见账号归属。

流程

POST /x-sign  ──▶  激活邮件(链接 10 分钟内有效)
                         │
                         ▼
GET /x-sign/activate?token=...  ──▶  确认页面
                         │  (用户点击确认)
                         ▼
POST /x-sign/activate  ──▶  创建账号,页面显示 API Key,并发送欢迎邮件

打开链接(GET)只显示确认页面,不会创建账号,以免邮件安全扫描器预取链接造成误激活。

发送激活邮件

curl -X POST "$XSI_BASE_URL/x-sign" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "referral_code": "pk-Xvs..."}'
字段必填说明
email是邮箱,自动转为小写
referral_code否推荐人的公开标识(pk-Xvs...,见 GET /dashboard/status 的 public_key)。XAI_REFERRAL_REWARD_RATE 为 0 时忽略

成功响应:

{"success": true, "message": "Verification code sent successfully", "data": {"email": "[email protected]"}}

所有响应都是 {"success", "message", "data"} 结构。业务错误返回 400,message 为原因:

message原因
Invalid email address邮箱格式不正确
Email domain is not allowed for self-registration不满足注册域名策略
Email already registered邮箱已注册
invalid referral code推荐码不存在或推荐人已停用
Please wait before requesting another verification code同一邮箱 2 分钟内重复请求
Too many verification codes requested from this IP today同一 IP 当日超过 10 次
Failed to send verification email邮件入队失败

激活

激活邮件中的链接为 https://<XAI_API>/x-sign/activate?token=<48 位令牌>。

  • GET /x-sign/activate?token=...:返回 HTML 确认页面。
  • POST /x-sign/activate(表单字段 token):创建账号并返回 HTML 成功页,页面显示新账号的 API Key,并提供进入控制台的按钮(多租户部署指向 XAI_ADMIN,单租户指向 XAI_MANAGE)。
  • 令牌无效或过期时显示 Invalid or expired activation link。

创建的账号:

属性值
账号名随机系统名(单租户 u_ 前缀,多租户 o_ 前缀)
显示名由邮箱前缀生成
API Key新生成的 51 位 sk-Xvs Key,另生成公开标识 pk-Xvs...
注册赠金XAI_CREDIT(代码默认单租户 2、多租户 120;部署模板为 0),有效期 1 个月
子账号名额1

账号归属

部署模式新账号
单租户(SINGLE_TENANT=true,默认)成为 root 租户下的普通账号,继承 root 的 Level、Gear、Role、价格与限速
多租户(SINGLE_TENANT=false)成为一个新的租户所有者,拥有独立的 Key 池、配置与价格,登录配置管理控制台后录入自己的上游 Key

注册域名策略

由 root 通过 /x-config 的 SIGNUP_ALLOW_DOMAINS 与 SIGNUP_DENY_DOMAINS 设置,对所有注册生效,语法见《租户配置 API》。

反滥用保护

SAFE_ENABLE(默认 true)开启时生效。除“不同邮箱数”只在 POST /x-sign 中检查(超限返回 400)外,其余限制由 POST /x-sign 与 POST /x-sign/activate 共享:

限制默认值
每分钟 / 每小时 / 每天请求数3 / 10 / 20
每 IP 每天不同邮箱数5
全站每日注册请求10000
渐进延迟同一小时内请求越多,服务端等待越久(最长 15 秒)
自动封禁可疑行为累计达到阈值后封禁 3 小时

被频率或全站配额拒绝时返回 429,正文为 {"success": false, "message": "..."}。识别出的客户端 IP 仍是受信代理地址时,按 IP 的限制不生效。客户端 IP 的识别依赖 TRUSTED_PROXY_CIDRS,请确保反向代理正确传递真实 IP,见《反向代理》。

相关文档