OpenRouter API 生产检查清单

验证 API 兼容性和端点

使用标准的 OpenAI 兼容端点以实现可靠的集成。

主要端点是 POST /v1/chat/completions. 这处理聊天历史生成的文本。次要端点， GET /v1/models, 列出可用模型。对于纯文本任务，您不需要嵌入或图像生成端点。许多开发人员认为他们需要复杂的路由层。OpenRouter 通过暴露单个入口点简化了这一点。您发送带有模型 ID 和系统提示的 JSON 负载。服务返回包含内容和用法数据的结构化 JSON。此设计符合官方 OpenAI SDK 的预期。您可以交换模型而无需更改客户端代码。只需在配置中更新模型 ID。确保您的客户端支持最新的 JSON 模式。旧版本可能会拒绝新参数。在部署到生产环境之前测试您的连接。验证响应格式是否与您的解析器匹配。

配置认证和密钥

生成后立即将 API 密钥安全存储在环境变量中。

通过提供商仪表板生成密钥。将其存储在安全位置，切勿将其硬编码到您的源代码仓库中。通过 Authorization: Bearer <key> 。每个密钥都绑定到特定账户。如果您怀疑泄露，可以轮换密钥。一些提供商允许每个账户拥有多个密钥。这允许您分离开发和生产流量。按密钥监控使用情况以检测异常。定期撤销未使用的密钥。为临时脚本使用短生命周期密钥。这减少了泄露的影响范围。确保您的 SDK 版本支持 bearer token 认证。较旧的库可能需要不同的 header 格式。检查您特定 SDK 的文档。验证密钥是否有足够的余额。过期的密钥返回 401 错误。余额为零的密钥返回 402 错误。在您的逻辑中区分这两种状态。

处理流式传输和 Token 使用情况

启用流式传输以实现低延迟和实时用户反馈。

设置 stream: true 在请求负载中。服务器发送一系列服务器发送事件（SSE）。每个事件包含部分文本数据块。你必须组装这些数据块以形成完整响应。最后一个数据块通常包含 token 使用统计。这允许你实时跟踪成本。如果没有流式传输，你需要等待整个响应。这会显著增加感知延迟。流式传输对于聊天界面至关重要。它创建了一种感觉响应灵敏的打字效果。流式传输期间的错误处理要小心。如果连接断开，你将丢失当前数据块。重连逻辑应保留对话状态。一些 SDK 自动处理流式传输。其他则需要手动事件监听器。选择适合你架构的方法。确保你的解析器处理不完整的 JSON 数据块。不要假设每个事件都是一个完整的对象。缓冲数据直到你拥有有效的结构。

监控速率限制和并发性

跟踪您的每分钟请求数，以避免服务中断。

OpenRouter 对每个 API 密钥实施严格的速率限制。超过这些限制将触发 429 Too Many Requests 错误。您必须在重试逻辑中实现指数退避。并发请求也会计入您的限制。请检查响应头以获取剩余配额。一些提供商直接暴露这些头信息。其他提供商则需要您从错误中推断限制。高并发可能会耗尽您的连接池。确保您的客户端高效管理连接。使用连接池以减少开销。在高峰负载期间监控队列深度。如果您达到限制，请在重试前等待。随机化等待时间以避免“惊群效应”。记录所有速率限制事件以便调试。这有助于识别使用模式。根据这些日志调整您的并发设置。不要假设单个密钥可以处理无限流量。如有必要，请在多个密钥之间分配负载。这需要仔细的状态管理。确保每个密钥在需要时保持其自己的上下文。

管理加密计费与充值

使用预付费信用额度支付 token 使用量，无需月费。

使用加密货币充值。支持的网络包括 TRC20 上的 USDT 和 Base 上的 USDC。最低充值金额为 $20。大额充值可享受赠送额度。充值 $50 获得 5% 额外赠送，充值 $100 获得 10% 赠送，充值 $200 获得 15% 赠送。额度永不过期。这非常适合长期项目。您仅为实际使用的 Token 付费。错误和拒绝请求不收费。这有助于保护您的预算免受意外成本影响。新账户可获得 $0.50 用于测试。标准购买不退款。重复扣款可通过支持团队纠正。确保您的钱包支持所需网络。发送前验证合约地址。使用错误的网络可能导致资金丢失。定期查看余额。余额不足可能会意外中断服务。如果可能，请自动化充值。这可确保关键任务的持续可用性。

测试内容过滤器和拒绝机制

验证模型对无护栏提示词的行为是否符合预期。

无审查模型可能仍会应用硬性限制。请检查特定内容类型的限制。使用已知的触发短语进行测试。确保模型做出适当的响应。一些提供商出于法律原因保留过滤器。在依赖模型处理敏感数据之前，请验证这些限制。在您的领域测试边缘情况。发送通常会触发拒绝的提示。观察响应格式。它是返回拒绝原因，还是静默生成内容？将这些行为记录在您的集成测试中。这可以防止生产环境中的意外情况。如果模型的行为发生变化，请更新您的测试。通知团队任何重大变化。一致性对于用户信任至关重要。确保您的应用程序优雅地处理拒绝。不要假设每个响应都是有效的。验证输出结构。检查幻觉或格式错误。这确保了可靠的用户体验。

为免费请求实施错误处理

优雅地处理错误以保持流畅的用户体验。

网络错误、超时和服务器错误可能会发生。实现带有指数退避的重试逻辑。区分临时错误和永久错误。429 错误是临时的。等待并重试。400 错误是永久的。检查您的输入数据。500 错误是服务器端的。谨慎重试。记录所有错误以进行调试。包括请求负载和响应正文。这有助于快速重现问题。不要向用户暴露原始错误。将它们格式化为对用户友好的消息。小心处理流式传输错误。断开事件流连接。清理资源。确保您的应用程序不会泄漏内存。彻底测试错误场景。模拟网络中断。模拟服务器超时。验证您的恢复逻辑是否有效。这确保了在不利条件下的可靠性。

使用 JSON 模式和工具调用进行扩展

使用结构化输出以实现可靠的数据提取和函数执行。

通过设置启用 JSON 模式 response_format: {type: "json_object"}. 这强制模型输出有效的 JSON。用于解析数据或生成配置。工具调用允许模型执行函数。在请求负载中定义您的工具。模型决定何时调用它们。将结果传回模型。它可以根据输出生成最终响应。这为复杂任务创建了一个循环。确保您的工具定义清晰。模糊的工具会导致错误的调用。在解析之前验证 JSON 输出。这防止了代码中的运行时错误。将工具调用用于数据提取任务。它显著提高了准确性。使用各种输入格式进行测试。确保模型处理边缘情况。为您的团队记录可用工具。这确保了项目间的使用一致性。

审查隐私和数据使用政策

理解提供商如何存储和使用您的数据。

查看隐私政策以了解数据保留详情。一些提供商使用您的数据进行训练。另一些则保持数据私密。如果这一点对您很重要，请确保您的数据未被用于模型改进。验证加密标准。数据应在传输中和静态时加密。检查是否存储日志。日志可能包含您的提示词。确保这些日志是安全的。查看服务条款中的责任条款。了解生成内容的归属权。一些提供商声称对您的输出拥有权利。确保这符合您的需求。如果您不再使用该服务，请删除账户。验证您的数据是否已移除。如有疑虑，请联系支持团队。记录您的隐私设置以备审计。这有助于符合内部政策。