什么是 AI API？
AI API 是一种有文档说明的方式，使软件能够向另一项服务请求 AI 能力。应用程序会发送结构化请求——通常是提示词、图像、音频文件或文档——以及凭据和模型或操作名称。该服务会返回结构化结果或结果流。随后，应用程序可以显示答案、对工单进行分类、转录语音、创建图像或继续工作流。
API 是接口，而不是模型本身。模型执行推理；API 定义客户端如何请求这项工作、接收答案以及处理错误。一些提供商托管自己的模型。另一些则提供通往多个模型的网关。开发者也可以在自托管 API 后运行开放模型。正确的选择取决于任务、数据边界、使用模式以及团队运营基础设施的能力。
如果你刚接触这个术语，可以从以下心智模型开始：
你的应用 → 已认证的请求 → AI API 端点 → 模型或工具 → 结构化响应 → 你的应用。
有关 API 作为软件组件之间契约的一般定义，请参阅 AWS 的 API 说明。AI 特有的部分是处理请求的模型或工具。
AI API 能做什么？
| 能力 | 典型输入 | 典型输出 | 使用示例 |
|---|---|---|---|
| 文本生成 | 提示词或对话消息 | 文本或结构化数据 | 起草一份供人工审核的支持回复 |
| 嵌入 | 文本或其他受支持内容 | 数值向量 | 查找语义相似的文档 |
| 图像生成或编辑 | 提示词和可选图像 | 图像资源 | 创建产品概念图 |
| 语音和音频 | 音频或文本 | 转录文本或合成音频 | 转录一次会议 |
| 视觉和文档分析 | 图像、文档或混合输入 | 描述或提取的字段 | 读取并验证一张发票 |
| 工具或数据访问 | 查询和工具参数 | 搜索结果或操作结果 | 为智能体检索实时事实信息 |
这些是 API 类别，并不保证每个模型都支持每项操作。纯文本模型不会自动接受图像，而工具端点也不同于生成式模型端点。在承诺为产品提供某项功能之前，请查看提供商当前的模型目录、端点文档、文件限制和响应架构。
AI API 请求如何工作
一个有用的请求包含四个部分：目标 URL、身份验证、操作和输入负载。目标地址标识服务和端点。凭据标识账户或项目。操作和模型决定请求执行什么工作。负载提供提示词或媒体，以及任何受支持的设置。
生产环境应用应从其服务器发起调用，以便 API 密钥能够保持保密。服务器会验证用户输入、设置合理的超时时间、发送请求并检查响应。它应区分身份验证错误与速率限制、模型不可用、无效负载或提供商故障。用户界面应接收对应用安全的结果，而不是原始凭据或未经筛选的提供商错误。
如果操作以流式方式传输令牌或媒体，客户端会随时间接收片段。流式传输可以改善感知响应速度，但应用仍需处理断开连接和不完整输出。对于结构化数据，在写入数据库或触发其他操作之前，应验证返回的数据形状。模型流畅的回答并不能证明所请求的事实是正确的。
Flatkey 文档 介绍了其当前兼容 OpenAI 的路由器和支持的工作流。统一路由器让团队可以在更改模型 ID 时保持熟悉的客户端形式，但你仍应测试特定模型的行为和端点支持。OpenAI API 平台和Claude API 文档是直接提供商接口的示例，它们各自拥有自己的请求契约。
AI API 与 AI 应用、SDK、网关和自托管模型的区别
这些术语有所重叠，但解决的问题不同：
- AI 应用：面向用户的产品，例如聊天界面或写作工具。它可能会在内部调用 API。
- AI API：接受请求并返回结果的编程契约。
- SDK：帮助代码调用 API 的库。SDK 很方便，但底层端点和账户规则仍然很重要。
- API 网关或模型路由器：在流量到达一个或多个模型提供商之前，可应用共享身份验证、路由、配额、记录和策略的一层。
- 自托管推理服务器：为运行在你可控制的计算资源上的模型权重公开 API 的软件。可用性、扩展、修补和成本均由你负责。
网关不能替代对合适模型的选择。自托管服务器并不一定比 API 更便宜。托管 API 也不一定适合所有数据或延迟要求。绘制完整的请求路径，并确定每个组件负责哪些职责。
可安全测试的首次集成
从一项范围明确的任务开始，例如将内部支持工单分类到一组固定类别中。定义可接受的输入、预期的输出架构，以及需要由人工审核的内容。然后：
- 选择支持该任务的提供商和模型。阅读当前的端点和模型文档，而不是复制旧示例。
- 创建具有范围限制的密钥。将其存储在服务器端密钥存储中或受保护的环境变量中。不要将其放入浏览器代码、移动端二进制文件、截图或公共代码库中。
- 发出一次测试请求。使用提供商文档中的 SDK 或 HTTP 示例，以及非敏感的示例输入。记录请求 ID 和响应结构。
- 验证输出和失败情况。测试格式错误的输入、缺少凭据、配额不足、响应缓慢以及故意不受支持的操作。
- 添加预算和监控。按功能或客户跟踪调用次数、令牌或单位、错误、延迟和支出。在向不受控流量开放该功能之前设置限制。
- 进行小规模评估。将响应与具有已知可接受结果的示例进行比较。除了延迟和成本外，还要评估质量。
这个流程有意保持精简。“hello world”响应证明了访问可用，但并不能证明该 API 对生产工作流而言是安全或经济的。
定价和限制通常如何运作
不同 AI API 的计费单位并不相同。文本模型通常会分别对输入和输出令牌定价；有些还会区分缓存输入。图像、视频、音频和数据工具可能按生成的资产、时长、大小、调用次数或其他单位计费。免费额度和限制可能会变化，因此应使用提供商的当前定价，而不是引用旧博客文章中的数字。
要进行现实的成本估算，请计算：
每月成本 ≈ 符合条件的请求数 × 每个请求的平均计费单位 × 当前单位价格。
然后加上重试、超出预期长度的输出、工具调用以及高使用量情景。记录被接受的有用结果，而不只是尝试请求的数量。即使每令牌费率很低，一个经常重试或产生不可用答案的工作流也可能成本高昂。
速率限制与价格是分开的。一个密钥可能受每分钟请求数、每分钟令牌数、并发量、账户层级或模型可用性限制。应用程序应遵守提供商文档中的限制和重试指引，在适当时进行退避，并避免在故障期间放大流量。不要假设预付更多额度会自动提高所有限制。
Flatkey 的当前网站描述了：在受支持的模型和工具之间使用一个密钥、共享余额和请求级使用记录。这些是其路由器的运营功能；在估算工作负载前，请确认实时模型目录和定价页面中具体的模型和单位。
安全、隐私和可靠性问题
AI API 会将数据发送到服务边界之外。在集成之前，识别哪些字段可能包含个人信息、受监管信息或机密信息。阅读提供商当前的数据保留和处理条款，选择所需的区域或部署选项，并决定应用程序记录哪些日志。如果需要对输入进行脱敏，请在将其发送给模型之前完成，并验证脱敏是否足以满足该用例的要求。
将生成的输出视为不可信数据。如果模型建议进行数据库更改、付款或向客户发送消息，请在模型之外实施权限控制以及人工或确定性检查。对于检索或工具使用，请验证来源和操作参数。API 密钥应只拥有工作流所需的最小访问权限，并且在暴露后应进行轮换。
为确保可靠性，请记录延迟、错误率、请求 ID 和所用模型版本。明确当提供商返回速率限制、超时或可用性发生变化时该如何处理。备用方案可能有所帮助，但它可能改变输出质量和格式；在将客户流量路由到它之前进行测试。如果该功能很重要，请创建一个可在模型或提示词变更后运行的评估集。
何时使用直接 API、路由器或自有 GPU
当某一家提供商的模型和账户控制满足要求，并且应用程序可以接受这种依赖关系时，使用提供商直接 API。当需要跨多个受支持提供商使用共享接口或统一运营时，使用路由器；请验证所需的每项模型功能都能通过该层正常工作。当模型权重、持续利用率、数据本地性或控制需求足以证明硬件和运维负担合理时，考虑自托管。
这一决策是可以衡量的。先从任务成功率、可接受的延迟、预计每月有效使用量、数据要求以及团队支持事故的能力开始。使用相同的提示词和评估标准比较各个候选方案。如果正在权衡专用 GPU 容量与 API 调用，Flatkey GPU 云与模型 API 指南展示了应对哪些利用率和成本假设进行压力测试。
常见问题
AI API 与 ChatGPT 相同吗？
不相同。ChatGPT 是一个应用。AI API 是应用可以调用的编程接口。不同提供商和自托管系统会提供不同的 API 和模型。
使用 AI API 是否需要训练模型？
通常不需要。许多托管 API 提供可直接使用的模型。您仍然需要设计提示词、验证结果、监控使用情况，并决定该模型是否满足您的任务要求。微调或训练是另一项独立的决策。
一个 API 密钥可以访问所有 AI 模型吗？
没有任何通用密钥可以覆盖所有提供商和模型。路由器可以为其支持的模型和工具提供一个密钥，但这取决于其目录、账户政策和上游可用性。在建立依赖关系之前，请检查当前支持的模型列表。
发布前应测试什么？
测试具有代表性示例上的结果质量、输入和输出限制、结构化响应行为、流式传输（如使用）、错误处理、速率限制、隐私控制、负载下的延迟，以及每个被接受结果的成本。在运营日志中保留模型 ID 和请求 ID，但避免不必要地记录敏感输入。
