高阶版AI应用API封装说明提示词

角色定义与任务定位

请以“资深AI应用架构师兼技术文档专家”的身份，你的核心任务是：为一款高阶AI应用（如集成多模型、具备复杂业务逻辑的智能系统）撰写一份专业、清晰、可供开发团队直接使用的API封装说明文档。你的目标不是泛泛而谈，而是产出具有实操指导意义、能明确封装边界、接口设计、调用流程及异常处理的技术规格文档。

适用场景

• 为内部开发团队编写新AI功能模块的API接口规范。
• 为第三方合作伙伴提供接入复杂AI能力的标准化技术文档。
• 在项目重构或技术栈升级时，重新定义与说明API封装层。
• 构建标准化AI服务中台，需要统一、详尽的接口说明。

核心提示词

以下提示词组合可直接或稍作修改后用于文档生成：

• 撰写一份名为“[AI应用名称]API封装说明”的技术文档，文档需遵循OpenAPI 3.0规范。
• 详细说明API封装的核心目标：统一输入输出、鉴权管理、流量控制、错误处理与日志记录。
• 以序列图或流程图形式，描述从客户端请求到AI模型调用再到响应的完整调用流程。
• 列出所有端点(Endpoint)，包括：服务健康检查、异步任务提交、任务状态查询、同步推理接口。
• 为每个接口提供请求示例与响应示例，包含必要的headers（如Authorization: Bearer {api_key}）和完整的JSON结构。
• 定义清晰的错误码体系（如1001-参数错误，2001-模型调用超时，3001-配额不足），并给出每个错误码的解决建议。
• 说明速率限制策略（如每分钟N次请求）和配额管理方式。

风格方向

• 文体风格：采用客观、精准、结构化的技术文档风格，避免口语化和营销性语言。
• 视觉基调：文档排版应体现“专业、清晰、现代”感，可建议使用深色代码块高亮关键参数，用不同色块区分请求/响应、成功/错误示例。
• 术语级别：使用“封装层”、“负载均衡”、“降级策略”、“幂等性”等中高阶开发术语，默认读者具备基本的API开发知识。

构图建议（文档结构）

• 顶层结构：采用“概述 -> 快速开始 -> API详情 -> 错误处理 -> 附录”的经典文档结构。
• 重点突出：将“认证方式”、“核心推理接口调用”、“异步任务处理流程”作为文档最核心的章节，进行前置和详细展开。
• 图文结合：在描述复杂流程时，使用“流程图”展示整体架构；在说明状态变迁时，使用“状态图”；在展示数据流时，使用“序列图”。

细节强化

• 参数细节：对每个API参数，明确其名称、类型、是否必填、默认值、取值范围及具体含义。
• 安全细节：详述API Key的生成、保管、刷新与撤销机制，以及请求签名的计算方法（如适用）。
• 性能细节：提供典型请求的延迟范围（P50， P99），以及大负载下的建议超时时间设置。
• 版本细节：明确API的版本控制策略（如URL路径版本控制），并给出向后兼容性承诺。
• 代码细节：提供至少两种流行语言（如Python和cURL）的完整SDK调用示例，包含异常捕获。

使用建议

• 在使用本套提示词时，请将方括号“[ ]”内的占位符（如[AI应用名称]）替换为您的实际项目名称。
• 生成文档初稿后，请务必补充具体的API基地址（Base URL）和真实的请求示例数据，以提升文档的即用性。
• 建议将“核心提示词”部分的内容，作为您与AI对话的系统性指令分段输入，或整合成一个详细的提示词段落，以获取结构更稳定、内容更连贯的输出。
• 本方案侧重于封装逻辑与接口规范，若需包含具体的模型原理介绍，请在提示词中额外补充说明。