袋袋AI API 接入指南：把 AI 专家集成到你的应用
袋袋AI 提供哪些 API？本文介绍 Agents Run、Chat Completions、Events、Models、Meters、API Key、OAuth 和官方 SDK，帮助开发者快速规划接入方案。
袋袋AI API 能解决什么问题？
开发者可以把平台上的 AI 专家集成到自己的后端、SaaS、企业工具或面向终端用户的 App 中。专家背后的人格、技能、记忆和工具对调用方保持透明，产品只需要关心输入、输出、权限和计费。
五类核心 API 能力
- Agents Run：通过 /v1/agents/run 调用已发布专家，支持多轮对话、工具调用、记忆和 SSE 流式回复。
- Chat Completions：通过 /v1/chat/completions 使用 OpenAI 兼容格式，模型名采用 profy-
，便于接入已有 SDK 和工具链。 - Events：为外部 App 上报自定义计费事件，支持按次计费和幂等性保障。
- Models：查询平台可用模型和能力信息，帮助选择合适的模型。
- Meters：查看 App 的计量器配置，了解事件与扣费规则。
API Key 还是 OAuth？
API Key 适合服务端直接调用、脚本和后台任务。密钥以 sk-pro- 开头，通过 Bearer Token 放在请求头中，费用从开发者账户扣除。密钥应保存在服务端密钥管理系统，不能写入前端代码或提交到仓库。
OAuth Bearer 适合需要让用户登录并授权的外部 App。App 可以复用袋袋的身份体系，再通过 Events API 上报自身的按次计费事件。
典型接入流程
- 在 Platform Console 创建 API Key 或配置 OAuth 应用；
- 确认要调用的专家标识符和计费模型；
- 先用 Models 或 Playground（开放后）验证能力；
- 在服务端调用 Agents Run 或 Chat Completions；
- 处理流式响应、错误、超时和重试；
- 通过 Events 上报业务事件，并在 Console 查看调用日志和用量。
SDK 与开发工具
平台提供 Python 和 TypeScript 官方 SDK，用于封装认证、流式解析和错误处理。若团队使用 Cursor、Codex 等 IDE，还可以通过 MCP Server 在编辑器内管理专家创建、配置、发布和收益查看。
计费设计建议
平台支持按 Token 用量计费（METERED）、按次计费（PER_USE）和一次性买断（ONE_TIME）。面向用户的产品应在自己的界面中清楚说明扣费时机，调用 Events 时使用稳定的幂等键，避免网络重试造成重复扣费。
袋袋AI API 的优势是把“专家能力”和“应用产品”分开：创作者负责专业方法，开发者负责体验、业务流程和商业化。建议先从一次简单的 Agents Run 调用开始，再逐步加入 OAuth、事件计费和 SDK。
相关文章
使用指南袋袋AI 有哪些应用场景？从第一次对话到完整 AI 工作流
袋袋AI 能做什么？本文按终端用户、创作者、开发者和团队四类人群，整理写作、编程、设计、数据、教育、API 和企业协作场景。
使用指南袋袋AI 团队版怎么用？企业 AI 协作与用量管理指南
袋袋AI 团队版能做什么？本文从共享专家能力、成员管理、积分池、用量观察和知识边界出发，介绍企业落地自主 AI 专家的实用方法。
使用指南袋袋AI 会话与云端工作区：AI 沙箱如何保存项目文件
袋袋AI 的 Session、Workspace 和沙箱有什么关系？本文解释会话持久化、文件保存、网站预览、临时对话、共享工作区和按需启动机制。