OpenAI 多模态 Responses | API 文档

OpenAI 兼容的 Responses API。该接口使用 OpenAI 官方风格的 input 入参，支持文本、公网图片 URL、PDF 文件输入、工具调用、推理配置和流式输出参数。

text

POST https://api.requestbeam.com/openai/responses

验证

所有接口都需要使用 Bearer Token 进行认证。

http

Authorization: Bearer YOUR_API_KEY

如果请求直接返回认证错误，请优先检查：

API Key 是否正确
Key 是否适用于当前 API Base URL
请求头是否拼写正确
代理层是否改写了请求头

Body

modelstring必填默认: gpt-5.4

当前支持 Responses 的 active 模型：

gpt-5.4
gpt-5.5
gpt-5.6-sol
gpt-5.6-terra
gpt-6-astra

当前 API Key 的实际可见范围见模型目录。

inputstring | object[]

输入内容。未提供非空 previous_response_id 时必填。同时缺少这两个字段，或 input 类型不合法时，会在预扣前返回 400。

支持两种写法：

字符串：等价于一条 user 文本输入。
输入项数组：用于多轮上下文、多模态输入和工具调用结果。

输入数组中的每个对象可包含以下字段：

typestring

输入项类型。

常用值：

message：一条消息输入。
function_call_output：函数工具调用的结果。

rolestring

当 type=message 时的角色。

常用值：

developer
system
user
assistant

contentstring | object[]

消息内容。

多模态请求建议使用内容块数组。内容块支持以下字段：

typestring

内容块类型。

当前支持：

input_text
input_image
input_file

textstring

当 type=input_text 时的文本内容。

image_urlstring

当 type=input_image 时的公网图片地址。

当前仅支持公开可访问的 http:// 或 https:// 图片 URL，不支持 data:image/...;base64,... Data URL。

detailstring默认: auto

当 type=input_image 时的图片解析细节。

常用值：

auto
low
high

file_datastring

当 type=input_file 时的文件内容 Data URL。PDF 可使用 data:application/pdf;base64,...。

filenamestring

当 type=input_file 时的文件名。

instructionsstring

系统或开发者指令，会插入到模型上下文中。

max_output_tokensinteger

可选的最大输出 token 数量，使用正整数。省略时使用所选模型的上游默认额度。不同模型的额度可能同时包含推理 token 和最终正文；较小额度可能导致回答截断，或在生成正文前耗尽。提高额度可能增加费用。

streamboolean默认: false

是否使用流式输出。

false：一次性返回完整响应。
true：返回 OpenAI Responses 风格的 SSE 事件。

temperaturenumber默认: 1.0

控制输出随机性，范围通常为 0 到 2。

top_pnumber默认: 1.0

核采样参数，范围通常为 0 到 1。

textobject

文本输出配置。

text.formatobject

文本格式配置，例如 { "type": "text" }、JSON schema 等。

text.verbositystring

文本详细程度配置。常见值包括 low、medium、high；具体可用范围取决于所选模型。

toolsobject[]

工具定义。

常见工具包括函数调用、文件搜索、网络搜索等。具体可用工具取决于所选模型和当前可用能力。

tool_choicestring | object

工具选择策略。

parallel_tool_callsboolean

是否允许并行工具调用。

reasoningobject

推理相关配置。

includestring[]

返回中需要额外包含的字段列表。

例如需要返回输入图片 URL 时，可设置 message.input_image.image_url。

prompt_cache_keystring

Prompt cache key，用于帮助复用提示词缓存。

prompt_cache_retentionstring

Prompt cache 保留策略。具体支持值取决于所选模型和当前可用能力。

safety_identifierstring

用于安全风控的最终用户稳定标识。

storeboolean

是否保存响应状态。具体行为取决于所选模型和当前可用能力。

模型参数差异

原生 OpenAI 兼容 Responses 转发会在上游请求中保留 top_p，参数校验和采样行为取决于所选模型与上游。2026-09-26 的验证中，gpt-5.5、gpt-5.6-sol 和 gpt-5.6-terra 接受了 top_p: 0.9。接受与透传都不证明采样效果，也不保证其他值、模型或后续请求同样支持。切换模型时建议从最小请求开始。
本页的 Responses 支持范围只适用于常规 /openai/responses 接口。它不代表同一模型同时支持 /openai/responses/compact、WebSocket 或有状态 previous_response_id。
上述五个 GPT 模型目前没有已验证的 Compact 通道。没有明确启用的通道时，Compact 会在预扣前拒绝；常规 Responses 和 Responses WebSocket 可正常使用。

请求体示例

以下示例均提供 input。只有提供有效 previous_response_id，且所选通道支持有状态续写时，续写请求才可以省略 input；传入响应 ID 不会让不支持的通道获得该能力。工具结果仍可作为输入数组项传入，包括 function_call_output。

纯文本

json

{
  "model": "gpt-5.4",
  "input": "你好，请用一句话介绍你自己。"
}

Codex CLI 风格参数

json

{
  "model": "gpt-5.5",
  "input": "Reply with READY only.",
  "reasoning": {
    "effort": "xhigh"
  },
  "store": false,
  "text": {
    "verbosity": "low"
  },
  "stream": true
}

图片理解

json

{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "这张图片里有什么？请用中文回答。"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/cat.png",
          "detail": "high"
        }
      ]
    }
  ]
}

文件输入

使用 file_data + filename 可以直接提交 PDF 内容。file_data 需要是完整 Data URL。

json

{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "请总结这个 PDF 的重点。"
        },
        {
          "type": "input_file",
          "file_data": "data:application/pdf;base64,JVBERi0xLjQKJc...",
          "filename": "report.pdf"
        }
      ]
    }
  ]
}

图片 + 文件混合输入

json

{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "请结合图片和附件，给出三条结论。"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/chart.png",
          "detail": "high"
        },
        {
          "type": "input_file",
          "file_data": "data:application/pdf;base64,JVBERi0xLjQKJc...",
          "filename": "notes.pdf"
        }
      ]
    }
  ]
}

流式输出

json

{
  "model": "gpt-5.4",
  "stream": true,
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "请分步骤解释这张图。"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/diagram.png"
        }
      ]
    }
  ]
}

Response

非流式响应保持 OpenAI Responses 风格。实际字段可能随所选模型能力变化。

idstring

响应的唯一标识符。

objectstring

响应对象类型，通常为 response。

created_atinteger

创建时间戳。

modelstring

实际使用的模型名称。

outputobject[]

输出项列表。

常见输出项包括：

message
function_call
工具调用相关输出

usageobject

Token 使用统计。

常见字段包括 input_tokens、output_tokens、total_tokens。

成功响应示例

json

{
  "id": "resp_123",
  "object": "response",
  "created_at": 1766534400,
  "model": "gpt-5.4",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "text": "图片中是一只猫，附件是一份关于宠物护理的说明文档。"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 128,
    "output_tokens": 42,
    "total_tokens": 170
  }
}

流式响应

当 stream=true 时，接口返回 SSE 事件流。

text

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"图片中"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"是一只猫"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_123"}}

客户端应持续读取事件，直到收到 response.completed 或连接结束。

失败响应

完整错误码、协议差异和排查步骤见错误码与错误处理。

平台生成的 HTTP 错误使用以下平铺字段，不包裹在 error 对象内。部分上游错误可能保留原有结构；已经开始的 SSE 流内错误不适用此 HTTP 响应示例。

json

{
  "code": 40000,
  "message": "Insufficient credit. Required: 30000, Available: 20000",
  "type": "api_error"
}

字段说明：

code：数字错误码。错误码由平台统一枚举管理。
message：错误说明。
type：OpenAI 兼容错误类型，通常为 api_error。

注意事项

Responses 接口使用 input，不是 messages。如果你的客户端只能发送 messages，请使用 /openai/v1/chat/completions。
图片输入使用 input_image，image_url 仅支持公网可访问的 http:// 或 https:// 图片地址，不支持 Base64 Data URL。
文件输入使用 input_file。PDF 文件建议使用 file_data + filename 写法，file_data 为完整的 data:application/pdf;base64,...。
audio 输入/输出、图片生成工具、文件搜索等高级能力取决于所选模型和当前可用能力，不保证所有模型可用。
本页列出的字段构成当前公开 Responses 请求合同；未列出的字段不应默认视为可用。
当前公开推荐路径是 /openai/responses。
/v1/responses 遵循相同的公开请求与响应合同。
/compat/v1/responses 遵循相同的公开请求与响应合同。
/openai/v1/responses 遵循相同的公开请求与响应合同。