每个请求都用 API 密钥认证。以 Bearer 令牌发送：
Authorization: Bearer gsk_live_xxx
如果您的技术栈不便使用 Bearer 令牌，也可以使用请求头 x-api-key: gsk_live_xxx。没有密钥的请求都会收到带 title: invalid_key 的 401。
密钥格式
gsk_live_<id>_<secret> 或 gsk_test_<id>_<secret>。gsk_live 密钥执行真实工作并计费。gsk_test 密钥在沙盒中运行：工具是模拟的，不收取任何费用，也不能用它修改房源、线索等真实数据。密钥类型在创建时选择。
密钥内容只在创建时显示一次。GREM 只保存其哈希值，因此丢失的密钥无法恢复：请创建新密钥并撤销旧密钥。
管理密钥
在后台 API → 密钥 中：
- 创建带标签的密钥。高级设置中可以选择权限范围和以天为单位的有效期。不做选择时密钥拥有全部权限范围。
- 轮换：签发新的密钥内容；旧的继续有效 24 小时，以便您在集成中替换。
- 撤销：密钥立即永久失效。
密钥状态显示在列表中：active 可用；suspended 管理员暂停了 API 访问（可恢复，密钥不会被销毁）；revoked 已撤销。设置了有效期的密钥过期后不再被接受（401）。
机构密钥
机构所有者或经理可以以机构名义签发密钥：把密钥列表切换到机构范围。这样的密钥：
密钥可以绑定到某个经纪人，此时它以该经纪人的身份和权限工作。
权限范围
每个密钥带有一组权限范围。缺少所需权限范围的调用返回带 title: forbidden_scope 的 403。每个操作所需的权限范围写在 /openapi.json 的操作描述中（字段 x-required-scope）。
| 权限范围 | 允许 |
|---|---|
ping | 检查密钥（没有它 GET /ping 也能用） |
tools:valuation | 快速估价和完整估价报告 |
tools:rent | 租金估算 |
tools:review | 审核他人的估价报告 |
tools:contentgen | 房源内容包 |
tools:text | 房源文案 |
tools:video | 照片生成视频、音乐和结束语列表 |
tools:avatar | 数字人视频和数字人列表 |
tools:photo | 照片优化 |
tools:floorplan | 户型图清理 |
tools:sitegen | 房源落地页 |
tools:pdf | PDF 演示文稿 |
tools:flyer | 经纪人个人传单 |
tools:draft | 从文件或网站生成房源草稿 |
tools:chat | AI 助手对话 |
tools:artifacts | 下载生成的文件 |
objects:write | 创建、编辑和删除您的房源 |
leads:read | 读取线索和 Swipe Match 线索 |
leads:write | 创建和编辑线索、Swipe Match 事件 |
media:write | 上传图片 |
webhooks | 管理事件订阅 |
不需要任何权限范围即可调用 GET /ping、GET /me、GET /dictionaries、GET /objects、GET /voices、GET /tools/status 和 GET /works。
这是哪个密钥
curl https://developers.grem.capital/api/v1/me \
-H "Authorization: Bearer gsk_live_xxx"
GET /me 返回密钥的 ID 和前缀、所属对象（subjectType：user 或 agency，subjectId，经纪人密钥还有 agencyMemberId）、已授予的权限范围、适用于这把密钥的限制（每分钟 rateLimit.rpm 和每天 rateLimit.rpd）以及有效期。密钥内容永远不会返回。免费。
安全
不要把密钥放进浏览器代码、移动应用、公开仓库或 URL。持有密钥的任何人都在花您账户的钱。如果密钥泄露，请立即撤销。
- 将密钥保存在服务器端环境变量或密钥管理器中。
- 每个集成使用单独的密钥，只授予所需的权限范围：撤销一个不会影响其他。
- 定期轮换密钥。
- 只接受 HTTPS 请求。