拉新领取码 · /api/tenant-claims

生成一次性领取码，挂上你的模板和额度，贴到小红书引流。买家点链接自动开账户、拿模板提示词和图包。

完整玩法见《用领取码在小红书拉新》。

只认租户 Key

组织级 sk-studio-。成员账户 Key 打这个接口一律 403。

填入你的 API Key本站所有示例里的 $MUSEAV_API_KEY 会就地换成它

只存在你自己浏览器的 localStorage 里，不会发给任何人——本站是纯静态页面，没有后端可发。 共用电脑上看完记得点「清除」。

POST /api/tenant-claims · 发一张领取码

curl -X POST https://manager.museav.top/api/tenant-claims \
  -H "X-API-Key: $MUSEAV_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "template_ids": ["uuid-a", "uuid-b"],
    "credits": 10,
    "note": "2026 七夕活动"
  }'

入参

字段	必填	说明
template_ids	✅	模板 id 数组，至少 1 个。所有 id 必须属于本租户或平台共享模板（visibility=shared && tenant_id IS NULL），否则 400。
credits	✅	正整数。从租户积分 api_tenants.credits_balance 原子扣减，不够 → 409。
note		备注，存到 xhs_claims.note，方便运营对账
tutorial_pdf_url		教程 PDF 的 R2 URL（领取页 done 步骤可下载）
tutorial_pdf_title		PDF 标题，默认「AI 出图核心技巧（教程 PDF）」

返回

{
  "ok": true,
  "code": "xhs-1e59c6bf",
  "claim_url": "https://museav.top/claim/xhs-1e59c6bf",
  "reply_text": "感谢购买！点击下方链接领取你的全部资源…",
  "product_copy": "AI 出图资源包（由 好易美 提供）：神颜提示词、窗边生活感…\n✅ 购买即得：…",
  "product_images": ["https://img.webkubor.online/…/sample-output.jpg"],
  "credits": 10,
  "templates": [{"slug": "…", "zh_name": "神颜提示词"}],
  "tutorial_pdf": null,
  "credits_balance_after": 990
}

reply_text / product_copy / product_images 就是直接贴小红书用的物料。product_copy 自动带「由 < 租户名 > 提供」前缀。

领取码自动把所选模板设为 gated=true（保护稀缺性 —— 见产品原理），并在 xhs_claims.tenant_id 记下你的租户 id。

错误码

HTTP	场景
400	template_ids 为空 / 含不可用模板 / credits 不是正整数 / JSON 不合法
401	缺 X-API-Key 或 key 无效
403	用的是成员账户 Key，不是租户 Key
409	租户积分不足（响应里 error 字段说明）
500	落库或扣减异常（极少；落库失败会自动回滚积分）

查询 / 作废

• 查询本租户发的码：目前走通用视图，在管理后台 /xhs 的「来源」列筛选租户名即可看到（view=xhs-claims 已在 response 里 join 租户名）。
• 作废码：调 /api/admin {action:'xhs-claim-disable', code:'xhs-xxx'}（需超管 Key；普通租户目前没有自助作废接口 —— 有需要告诉我加上）。

买家体验

不管你发的是平台码还是租户码，买家打开 https://museav.top/claim/<code> 看到的都是同一套独立全屏落地页（不嵌在 museav 系统里）。核销后开的是 museav 平台账户，不是租户账户。

买家后续在 /templates 的「我的领取」tab 看到自己领过的模板（模板被门控后只有 claim 持有人能看完整），闭环。

相关接口

• GET /api/xhs-claims?code=<code> — 公开，领取页预览福利清单
• POST /api/xhs-claims {code, nickname, email} — 公开，买家核销（开户+发额度+下发货）
• GET /api/balance — 查自己租户还剩多少积分

上手示例

完整的小红书 SOP + 命令行 + 物料准备见 → 《用领取码在小红书拉新》