如何在 ventic.ai 中生成 API 密钥？

API 密钥是让您的系统连接 ventic.ai 的最简单方式。它允许您的店铺、PIM、ERP 或中间件将产品与内容发送到指定项目，并在之后为搜索与代理体验检索数据。在 ventic.ai 中，API 访问按项目范围限定，即每个密钥属于一个项目且只能访问该项目的资源。

平台上 API 密钥所在位置

API 密钥在项目设置内管理。密钥区域不仅是“一次性创建”的界面，而是可进行以下操作的控制面板：为不同集成生成密钥、限制权限、监控用量、在需要时即时暂停访问、控制是否启用公开 ACP Feed。这样设计是因为代理型商务集成很少“一次搞定”，通常会有多个数据源与服务，需要清晰的归属与可追溯性。

如何生成 API 密钥

流程简单：打开要连接的项目 → 进入 项目设置 → 打开 API 密钥 部分 → 创建新密钥并为其设置清晰名称与描述（如“店铺 Feed 同步”“PIM 连接器”“内部 BI 只读”）→ 选择权限级别并创建。创建后，原始密钥会显示一次，此时应将其安全存入密钥管理器或部署环境变量。若之后丢失，ventic.ai 不会再次“显示”该密钥，您需要新建一个。

如何长期管理 API 密钥

良好做法是把 API 密钥视为集成的运营身份：一个系统一个密钥，而非一把钥匙开所有门。在 ventic.ai 中可通过以下三种方式管理：激活与暂停：暂停密钥会立即阻断该集成的访问，在怀疑滥用、异常流量或维护期间暂停集成时，这是最快、最安全的应对；之后可重新激活且不丢失密钥记录与用量历史。编辑名称与描述：当有多把密钥时，清晰命名很重要，便于识别归属与用途、便于审计。监控用量：平台会记录用量指标（如调用频率、最后使用时间），有助于发现闲置密钥、确认新集成正常，或发现异常峰值。

权限：如何授予合适访问级别

创建密钥时可选择权限级别，目的是将只读安全用例与可修改数据的集成分开。实用模型：只读密钥用于分析、报表或仅需查询产品与知识的外部服务；读写密钥用于会创建、更新或删除产品、Feed 与文档的目录同步服务。推荐默认使用只读，仅在集成确实需要写权限时再授予，并尽量按系统拆分以缩小影响范围。

应了解的 API 端点

所有程序化访问均经 ventic.ai API 网关：公共 API 基础地址：api.ventic.ai；Swagger UI：api.ventic.ai/docs；OpenAPI 规范：api.ventic.ai/openapi.json。这些是团队实现集成时会用到的规范端点，也是确认平台当前能力的最佳方式。

公开 ACP Feed：启用不使用 API 密钥的公开端点

API 密钥保护需认证的 API；ventic.ai 还支持通过公开 ACP Feed 端点发布产品。这是有意设计：ACP 等协议围绕“平台可从 URL 抓取商家目录并内部索引”的思路构建。因该 Feed 天然公开，其与 API 密钥分开管理。在项目设置中可：启用或关闭公开 ACP Feed、复制 Feed URL、在不再希望通过该机制暴露目录时快速关闭。区别在于：API 密钥用于受控、需认证的集成（您的系统与合作伙伴）；公开 ACP Feed用于基于协议的目录发布，消费者不应需要您的私密凭据。

简明运维模型

若希望配置清晰且安全，可采用：为目录同步流水线创建一把 读写 密钥；为内部分析或第三方查询创建一把 只读 密钥；仅当分发策略明确包含外部代理平台对 ACP 的抓取时启用 公开 ACP Feed；在归属变更、服务下线或用量异常时 暂停并轮换 密钥。这样访问可预期，ventic.ai 可作为您代理型商务策略背后的产品智能层平稳运营。