> ## Documentation Index
> Fetch the complete documentation index at: https://doc.geekapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/responses — OpenAI Responses API 调用

> OpenAI 新一代 Agentic 接口，支持函数调用、内置联网搜索、服务端多轮上下文与推理力度控制，Responses Only 模型专用。

`POST https://geekapis.com/v1/responses` 是 OpenAI 推出的新一代 Agentic 接口，相比传统 Chat Completions 提供了更强大的能力：内置工具（联网搜索）、自定义函数调用、服务端自动维护多轮上下文（`previous_response_id`）以及精细化推理力度控制（`reasoning.effort`）。

<Warning>
  **Responses Only 模型**

  以下模型**仅支持 Responses API**，不支持 Chat Completions 接口，调用时请使用本端点：

  * `gpt-5-pro-official`
  * `gpt-5.3-codex-official`

  完整模型列表及支持的接口类型请参阅[模型一览](https://geekapis.com/pricing)。
</Warning>

## 鉴权

<ParamField header="Authorization" type="string" required>
  Bearer Token 认证。在请求头中添加：

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```

  前往 [API Key 管理页面](https://geekapis.com/keys) 获取您的 API Key。
</ParamField>

## 请求参数

<ParamField body="model" type="string" required>
  模型名称。

  示例：`"gpt-5-pro-official"`、`"gpt-5.3-codex-official"`、`"gpt-5.2-official"`
</ParamField>

<ParamField body="input" type="string | object[]" required>
  用户输入，支持两种格式：

  * **字符串**：简单的单轮文本输入
  * **消息数组**：多轮对话格式

  <Expandable title="消息数组格式">
    <ParamField body="role" type="string" required>
      消息角色：`user`、`assistant` 或 `developer`。
    </ParamField>

    <ParamField body="content" type="string | object[]" required>
      消息内容，支持纯文本字符串或包含图片的内容块数组。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="instructions" type="string">
  系统指令，指导模型行为，等同于 Chat Completions 中的 `system` 消息。
</ParamField>

<ParamField body="stream" default="false" type="boolean">
  是否启用流式输出（Server-Sent Events）。
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  生成内容的最大 token 数量。
</ParamField>

<ParamField body="temperature" default="1" type="number">
  采样温度，控制输出随机性。范围：`0` \~ `2`。
</ParamField>

<ParamField body="top_p" default="1" type="number">
  核采样概率阈值。范围：`0` \~ `1`。建议不要同时修改 `temperature` 和 `top_p`。
</ParamField>

<ParamField body="previous_response_id" type="string">
  上一次响应的 `id`，用于服务端自动拼接多轮对话上下文。使用此字段后无需客户端自行传递完整历史消息。
</ParamField>

<ParamField body="reasoning" type="object">
  推理配置，控制模型的思考深度。

  <Expandable title="reasoning 字段">
    <ParamField body="effort" type="string">
      推理力度，可选值：`high`、`medium`、`low`、`none`。

      值越高，模型思考越深入，消耗的 reasoning tokens 越多，响应时间也更长。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tools" type="object[]">
  可用工具列表，模型可在响应中调用这些工具。

  <Expandable title="tools[n] 字段">
    <ParamField body="type" type="string" required>
      工具类型：

      * `function`：自定义函数调用
      * `web_search_preview`：内置联网搜索
    </ParamField>

    <ParamField body="name" type="string">
      函数名称，`type` 为 `function` 时必填。
    </ParamField>

    <ParamField body="description" type="string">
      函数描述，帮助模型理解何时调用此函数。
    </ParamField>

    <ParamField body="parameters" type="object">
      函数参数的 JSON Schema 定义，`type` 为 `function` 时使用。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" default="auto" type="string">
  工具选择策略：

  * `auto`：由模型自行决定是否调用工具
  * `none`：禁止调用任何工具
  * `required`：强制调用至少一个工具
</ParamField>

## 响应字段

<ResponseField name="id" type="string">
  响应的唯一标识符，可直接用作下次请求的 `previous_response_id` 以延续对话。
</ResponseField>

<ResponseField name="object" type="string">
  固定为 `response`。
</ResponseField>

<ResponseField name="status" type="string">
  响应状态：`completed`（已完成）/ `failed`（失败）/ `in_progress`（处理中）。
</ResponseField>

<ResponseField name="model" type="string">
  实际使用的模型名称。
</ResponseField>

<ResponseField name="output" type="object[]">
  输出项列表，可能包含以下一种或多种类型：

  <Expandable title="output[n] 字段">
    <ResponseField name="type" type="string">
      输出类型：

      * `message`：文本回复
      * `function_call`：函数调用请求
      * `reasoning`：推理过程（`reasoning.effort` 非 `none` 时出现）
      * `web_search_call`：联网搜索调用记录
    </ResponseField>

    <ResponseField name="role" type="string">
      消息角色，`type` 为 `message` 时为 `assistant`。
    </ResponseField>

    <ResponseField name="content" type="object[]">
      内容块列表，`type` 为 `message` 时包含。

      * `content[].type`：`output_text`
      * `content[].text`：生成的文本内容
    </ResponseField>

    <ResponseField name="name" type="string">
      函数名称，`type` 为 `function_call` 时包含。
    </ResponseField>

    <ResponseField name="arguments" type="string">
      函数调用参数（JSON 字符串），`type` 为 `function_call` 时包含。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  token 消耗统计。

  <Expandable title="usage 字段">
    <ResponseField name="input_tokens" type="integer">
      输入 token 数。
    </ResponseField>

    <ResponseField name="output_tokens" type="integer">
      输出 token 数（包含推理 token）。
    </ResponseField>

    <ResponseField name="output_tokens_details" type="object">
      输出 token 详情，包含 `reasoning_tokens`（推理消耗的 token 数）。
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      总 token 数。
    </ResponseField>
  </Expandable>
</ResponseField>

## 代码示例

<CodeGroup>
  ```bash cURL（基础请求） theme={null}
  curl --request POST \
    --url https://geekapis.com/v1/responses \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gpt-5.3-codex-official",
      "instructions": "你是一个专业的代码助手",
      "input": "用 Python 写一个快速排序"
    }'
  ```

  ```bash cURL（联网搜索） theme={null}
  curl --request POST \
    --url https://geekapis.com/v1/responses \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gpt-5.3-codex-official",
      "input": "今天有什么重要的 AI 新闻？",
      "tools": [
        { "type": "web_search_preview" }
      ]
    }'
  ```

  ```bash cURL（多轮对话） theme={null}
  # 第二轮对话：传入上一轮的响应 ID
  curl --request POST \
    --url https://geekapis.com/v1/responses \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gpt-5.3-codex-official",
      "input": "能帮我优化一下这段代码的性能吗？",
      "previous_response_id": "resp_abc123"
    }'
  ```

  ```python Python (openai SDK) theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="YOUR_API_KEY",
      base_url="https://geekapis.com/v1"
  )

  response = client.responses.create(
      model="gpt-5.3-codex-official",
      instructions="你是一个专业的代码助手",
      input="用 Python 写一个快速排序"
  )

  # 获取文本输出
  for item in response.output:
      if item.type == "message":
          print(item.content[0].text)
  ```

  ```javascript JavaScript (openai SDK) theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "YOUR_API_KEY",
    baseURL: "https://geekapis.com/v1"
  });

  const response = await client.responses.create({
    model: "gpt-5.3-codex-official",
    instructions: "你是一个专业的代码助手",
    input: "用 Python 写一个快速排序"
  });

  for (const item of response.output) {
    if (item.type === "message") {
      console.log(item.content[0].text);
    }
  }
  ```
</CodeGroup>

## 响应示例

````json 200 - 文本响应 theme={null}
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.3-codex-official",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "```python\ndef quicksort(arr):\n    if len(arr) <= 1:\n        return arr\n    pivot = arr[len(arr) // 2]\n    left = [x for x in arr if x < pivot]\n    middle = [x for x in arr if x == pivot]\n    right = [x for x in arr if x > pivot]\n    return quicksort(left) + middle + quicksort(right)\n```"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 80,
    "total_tokens": 105
  }
}
````

```json 200 - 函数调用响应 theme={null}
{
  "id": "resp_def456",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.3-codex-official",
  "output": [
    {
      "type": "function_call",
      "name": "get_weather",
      "arguments": "{\"city\": \"北京\", \"unit\": \"celsius\"}"
    }
  ],
  "usage": {
    "input_tokens": 40,
    "output_tokens": 15,
    "total_tokens": 55
  }
}
```

## 错误码

| HTTP 状态码 | 说明                | 解决方案                                |
| -------- | ----------------- | ----------------------------------- |
| `400`    | 请求参数错误（如模型不支持该接口） | 确认所用模型支持 Responses API，检查参数格式       |
| `401`    | 身份验证失败            | 检查 `Authorization` 头中的 API Key 是否有效 |
| `429`    | 请求频率超限            | 降低并发请求数或实现退避重试策略                    |