OpenRouter Responses API Beta（/api/v1/responses）支持字符串和结构化消息数组两种输入格式，兼容 streaming 实时输出。与传统 Chat API 不同，它基于 items-based 响应格式，返回包含 output 数组的对象。该 API 处于 Beta 阶段，是无状态的——多轮对话需要在每次请求中携带完整历史。本页提供从简单调用到多轮对话的完整示例。

Beta API：该 API 处于 beta 阶段，可能存在破坏性变更。

Responses API Beta 同时支持简单字符串输入和结构化消息数组。

简单字符串输入

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: 'What is the meaning of life?',
    max_output_tokens: 9000,
  }),
});

const result = await response.json();

结构化消息数组输入

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: [
      {
        type: 'message',
        role: 'user',
        content: [{ type: 'input_text', text: 'Tell me a joke about programming' }],
      },
    ],
    max_output_tokens: 9000,
  }),
});

响应格式

{
  "id": "resp_1234567890",
  "object": "response",
  "created_at": 1234567890,
  "model": "openai/o4-mini",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The meaning of life...",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 45,
    "total_tokens": 57
  },
  "status": "completed"
}

Streaming 响应

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: 'Write a short story about AI',
    stream: true,
    max_output_tokens: 9000,
  }),
});

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  for (const line of chunk.split('\n')) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6);
      if (data === '[DONE]') return;
      try {
        const parsed = JSON.parse(data);
        console.log(parsed);
      } catch (e) {
        // Skip invalid JSON
      }
    }
  }
}

常用参数

参数	类型	说明
model	string	必填。 使用的模型（如 openai/o4-mini）
input	string 或 array	必填。 文本字符串或消息数组
stream	boolean	开启 streaming（默认 false）
max_output_tokens	integer	最大生成 token 数
temperature	number	采样温度（0-2）
top_p	number	Nucleus sampling 参数（0-1）

多轮对话

Responses API Beta 是无状态的——每次请求必须包含完整对话历史：

// 第二轮请求——携带前一轮对话历史
const secondResponse = 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: [
      {
        type: 'message',
        role: 'user',
        content: [{ type: 'input_text', text: 'What is the capital of France?' }],
      },
      {
        type: 'message',
        role: 'assistant',
        id: 'msg_abc123',       // 必填
        status: 'completed',   // 必填
        content: [
          {
            type: 'output_text',
            text: 'The capital of France is Paris.',
            annotations: []
          }
        ]
      },
      {
        type: 'message',
        role: 'user',
        content: [{ type: 'input_text', text: 'What is the population of that city?' }],
      },
    ],
    max_output_tokens: 9000,
  }),
});

在对话历史中包含 assistant role 消息时，id 和 status 字段为必填项。

常见问题

Q: Responses API 和 Chat Completions API 有什么区别？

A: Responses API 基于 items-based 模型，响应格式不同（output 数组而非 choices），同时支持 reasoning、web search 等扩展能力。Chat Completions API 是传统的 messages/choices 格式，目前更成熟稳定。

Q: 每次多轮对话都要传完整历史，性能会有问题吗？

A: 这是无状态 API 的设计取舍。好处是服务端无需维护状态，可靠性更高；坏处是随对话轮次增加，每次请求的 token 消耗也会增加。如果使用 Agent SDK 的 StateAccessor，可以在本地管理状态，只在必要时传递历史。

Q: Beta 阶段有哪些注意事项？

A: Beta API 可能发生破坏性变更，不建议在生产环境中直接依赖，或需要做好版本兼容处理。关注 OpenRouter 官方更新日志以了解变更情况。