OpenRouter Responses API Beta（/api/v1/responses）是 OpenAI Responses API 的兼容替代，支持推理（reasoning）、工具调用（tool calling）和网页搜索（web search）等高级能力。注意：该 API 处于 Beta 阶段，可能有破坏性变更；且完全无状态——每次请求都要带完整的对话历史，服务端不保存任何会话状态。

OpenRouter Responses API Beta

Beta 阶段：该 API 仍在迭代中，可能有破坏性变更，在生产环境使用时需谨慎。

完全无状态：服务端不保存对话状态。每次请求都必须包含完整的对话历史。

OpenRouter Responses API 是 OpenAI Responses API 的无状态兼容实现，通过统一接口接入多个 AI 模型，提供推理、工具调用、网页搜索等高级功能。

基础请求

Base URL：https://openrouter.ai/api/v1/responses

认证：所有请求需要 Bearer Token：

const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_OPENROUTER_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/o4-mini',
    input: 'Hello, world!',
  }),
});

核心功能

基础用法

简单文本输入和响应处理的基础示例。

推理（Reasoning）

访问支持推理能力的模型，可配置推理强度（effort）和加密推理链。

工具调用（Tool Calling）

集成函数调用能力，支持并行执行多个工具。

网页搜索（Web Search）

启用实时网页搜索，响应包含引用注解（citation annotations）。

与 Chat Completions API 的区别

特性	Chat Completions	Responses API
状态	无状态	无状态
会话管理	手动携带历史	手动携带历史
推理支持	部分模型支持	原生支持
网页搜索	通过 plugins	原生 Server Tools
稳定性	正式版	Beta（可能有变更）

错误处理

API 返回结构化错误：

{
  "error": {
    "code": "invalid_prompt",
    "message": "Missing required parameter: 'model'."
  },
  "metadata": null
}

详细错误处理见 错误处理文档。

速率限制

适用 OpenRouter 标准速率限制，详见 API 限制。

---

常见问题

Q: Responses API 和 Chat Completions API 我该用哪个？

A: 如果你需要推理能力（如 o4-mini、Claude 的扩展思考）或网页搜索，推荐 Responses API。常规对话场景用 Chat Completions API 更稳定，因为它已是正式版。

Q: 无状态意味着什么？有什么影响？

A: 服务端不记录任何会话状态。多轮对话时，你必须在每次请求中携带完整的历史消息——和 Chat Completions API 一样，只是 Responses API 的对话格式有所不同。

Q: Beta API 会有哪些破坏性变更？

A: 字段名、响应格式、错误码等都可能变更。上生产环境前建议订阅 OpenRouter 的更新通知，并做好降级到 Chat Completions API 的预案。