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

# GPT 全模型接口 - Responses 完整参数

> - GPT 系列文本模型的 OpenAI 兼容 Responses 接口，通过 `model` 选择具体模型（全部可选值见 `model` 参数的对照表）
- 全系为推理模型，通过 `reasoning.effort` 控制推理深度；推理 token 计入输出 token 计费
- Prompt 缓存自动生效：命中缓存的输入 token 按更低的缓存价计费
- 支持同步与流式（SSE）两种模式
- 服务端工具：`web_search`（联网搜索）、`code_interpreter`（代码执行）、`file_search`（文档检索）
- 同时支持普通 `function` 工具（客户端函数调用）
- 多轮对话可用 `previous_response_id` 串联
- **注意** 部分参数各模型支持范围不同，逐参数见下方说明

<Note>
  **BaseURL 说明**：默认 BaseURL 为 `https://direct.evolink.ai`，对文本模型支持更好，支持长连接；`https://api.evolink.ai` 是多模态主力地址，对文本模型作为备用地址使用。
</Note>

<Note>
  **服务端工具**（`web_search`、`code_interpreter`、`file_search`、`mcp`）在服务端执行，无需客户端回传结果，仅在本接口提供。Chat Completions 接口只支持普通 `function` 工具调用。
</Note>

<Note>
  **注意** 本接口仅支持同步与流式两种模式：不支持 `background: true` 的后台异步模式，也不提供按响应 ID 查询、取消、删除响应的端点。需要长时间生成时，请使用 `stream: true` 保持连接。

  `image_generation` 工具在本系列模型上不可用，图像生成请使用图像系列模型接口。
</Note>

<Note>
  **多轮对话**：用上一轮返回的 `id` 作为下一轮的 `previous_response_id` 即可续接上下文。响应有留存期限，过期后该 ID 不再有效，请求会按新会话处理；对上下文准确性有强要求的场景，建议自行维护完整的 `input` 历史。
</Note>


## OpenAPI

````yaml cn/api-manual/language-series/gpt/responses/responses-reference.json POST /v1/responses
openapi: 3.1.0
info:
  title: GPT 全模型接口 - Responses 完整参数
  description: 通过 OpenAI 兼容的 Responses 接口调用 GPT 系列文本模型的完整参数手册（含服务端工具）。
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: 生产环境（推荐）
  - url: https://api.evolink.ai
    description: 备用地址
security:
  - bearerAuth: []
tags:
  - name: Responses
    description: OpenAI Responses 接口与服务端工具
paths:
  /v1/responses:
    post:
      tags:
        - Responses
      summary: GPT Responses（全模型，完整参数）
      description: >-
        - GPT 系列文本模型的 OpenAI 兼容 Responses 接口，通过 `model` 选择具体模型（全部可选值见 `model`
        参数的对照表）

        - 全系为推理模型，通过 `reasoning.effort` 控制推理深度；推理 token 计入输出 token 计费

        - Prompt 缓存自动生效：命中缓存的输入 token 按更低的缓存价计费

        - 支持同步与流式（SSE）两种模式

        - 服务端工具：`web_search`（联网搜索）、`code_interpreter`（代码执行）、`file_search`（文档检索）

        - 同时支持普通 `function` 工具（客户端函数调用）

        - 多轮对话可用 `previous_response_id` 串联

        - **注意** 部分参数各模型支持范围不同，逐参数见下方说明
      operationId: gptResponsesReference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
      responses:
        '200':
          description: 响应生成成功（JSON 对象；`stream=true` 时为 SSE 事件流，以 `response.completed` 结束）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
        '400':
          description: 请求参数无效（含该模型不支持的参数，错误信息会指出具体参数名）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 400
                  message: >-
                    Invalid value: '__bogus__'. Supported values are: 'auto' and
                    'disabled'.
                  type: invalid_request_error
                  param: truncation
        '401':
          description: 未授权，Token 无效或已过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: 额度不足
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 402
                  message: Insufficient quota
                  type: insufficient_quota_error
                  fallback_suggestion: https://evolink.ai/dashboard/billing
        '429':
          description: 请求频率超限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  type: rate_limit_error
                  fallback_suggestion: retry after 60 seconds
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 500
                  message: Internal server error
                  type: internal_server_error
                  fallback_suggestion: try again later
        '503':
          description: 服务暂时不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 503
                  message: Service temporarily unavailable
                  type: service_unavailable_error
                  fallback_suggestion: retry after 30 seconds
components:
  schemas:
    ResponsesRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          description: |-
            要调用的模型：

            | 模型 ID | 上下文窗口 | 定位 |
            |---|---|---|
            | `gpt-5.6-sol` | 1,050,000 | GPT-5.6 家族，前沿推理 |
            | `gpt-5.6-terra` | 1,050,000 | GPT-5.6 家族，均衡生产 |
            | `gpt-5.6-luna` | 1,050,000 | GPT-5.6 家族，高吞吐与成本控制 |
            | `gpt-5.5` | 400,000 | 通用推理模型 |
            | `gpt-5.4` | 128,000 | 通用推理模型 |
            | `gpt-5.2` | 400,000 | 通用推理模型 |
            | `gpt-5.1` | 400,000 | 通用推理模型 |
          enum:
            - gpt-5.6-sol
            - gpt-5.6-terra
            - gpt-5.6-luna
            - gpt-5.5
            - gpt-5.4
            - gpt-5.2
            - gpt-5.1
          example: gpt-5.6-sol
        input:
          description: >-
            模型输入：纯字符串，或输入项数组。


            输入项的 `content` 支持 `input_text`（文本）、`input_image`（图像）两种块：


            ```json

            "input": [
              {
                "role": "user",
                "content": [
                  { "type": "input_text", "text": "这张图里有什么？" },
                  {
                    "type": "input_image",
                    "image_url": "https://example.com/photo.png",
                    "detail": "auto"
                  }
                ]
              }
            ]

            ```


            **图像**

            - `image_url` 传入图片的公网 URL

            - `image_url` 必须是字符串；写成 `{ "url": "..." }` 会返回 `400`

            - `detail` 与 `image_url` 同级（不是嵌套在里面），可选 `auto`（默认）/ `low` / `high` /
            `original`

            - 图片需能被正常下载，否则返回 `400`


            **工具结果**

            - 数组中也可回填上一轮的 `function_call_output` 等工具结果项


            **注意** 本接口的块类型与 Chat Completions 接口不同（Chat 用 `text` /
            `image_url`），两者不可混用，写错会返回 `400`。
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/InputItem'
          example: 搜索最近一周的 AI 新闻并用三句话总结。
        instructions:
          type: string
          description: >-
            系统级指令，等价于在 `input` 最前面插入一条系统消息。使用 `previous_response_id`
            续轮时，本参数不会从上一轮继承，需要每轮传入。
          example: 你是一个简洁的助手，回答不超过三句话。
        stream:
          type: boolean
          description: 是否流式返回（SSE 事件流，以 `response.completed` 结束）。默认 `false`。
          default: false
          example: false
        max_output_tokens:
          type: integer
          description: 生成的最大 token 数（含推理 token）。达到上限时 `status` 为 `incomplete`。
          example: 2048
        reasoning:
          type: object
          description: >-
            推理控制。


            **`effort`（推理深度）可选值随模型不同：**


            | 模型 | 可选值 |

            |---|---|

            | `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna` |
            `none`、`low`、`medium`、`high`、`xhigh`、`max` |

            | `gpt-5.5` / `gpt-5.4` / `gpt-5.2` |
            `none`、`low`、`medium`、`high`、`xhigh` |

            | `gpt-5.1` | `none`、`low`、`medium`、`high` |


            **`summary`（推理摘要）**：`auto` / `concise` / `detailed`，全系可用。开启后
            `output` 中会出现 `reasoning` 项。


            **`mode`（推理模式）**：`standard` / `pro`，仅 `gpt-5.6` 家族支持。


            **`context`（推理上下文范围）**：`auto` / `current_turn` / `all_turns`，仅
            `gpt-5.6` 家族支持。


            推理 token 按输出 token 计费，并计入
            `usage.output_tokens_details.reasoning_tokens`。
          properties:
            effort:
              type: string
              enum:
                - none
                - low
                - medium
                - high
                - xhigh
                - max
              example: medium
            summary:
              type: string
              enum:
                - auto
                - concise
                - detailed
              example: auto
            mode:
              type: string
              enum:
                - standard
                - pro
              example: standard
            context:
              type: string
              enum:
                - auto
                - current_turn
                - all_turns
              example: current_turn
        text:
          type: object
          description: >-
            输出文本控制：


            - `format`：`{"type": "text"}`（默认）、`{"type": "json_object"}`，或
            `{"type": "json_schema", "name": "...", "schema": {...}, "strict":
            true}` 输出结构化结果

            - `verbosity`：`low` / `medium` / `high`，控制回答详略
          properties:
            format:
              type: object
              description: 输出格式定义
            verbosity:
              type: string
              enum:
                - low
                - medium
                - high
              example: medium
        tools:
          type: array
          description: |-
            工具声明。服务端工具在服务端执行，无需客户端回传结果：

            | 工具类型 | 能力 |
            |---|---|
            | `web_search` | 联网搜索并浏览网页（别名 `web_search_preview`） |
            | `code_interpreter` | 在沙箱中运行代码，需带 `"container": {"type": "auto"}` |
            | `file_search` | 检索已创建的向量库，需带 `vector_store_ids` |
            | `mcp` | 连接远程 MCP 服务，需带 `server_label` 与 `server_url` |

            同时支持普通 `function` 工具（客户端函数调用）。

            **注意** `image_generation` 在本系列模型上不可用，请改用图像系列模型接口。
          items:
            $ref: '#/components/schemas/Tool'
          example:
            - type: web_search
        tool_choice:
          description: >-
            工具选择控制：`"auto"`（默认）/ `"none"` / `"required"`，或用对象指定某个工具，如 `{"type":
            "web_search"}`。
          oneOf:
            - type: string
              enum:
                - none
                - auto
                - required
            - type: object
        max_tool_calls:
          type: integer
          description: 本次响应中允许的工具调用总次数上限。
          example: 5
        parallel_tool_calls:
          type: boolean
          description: >-
            是否允许模型在一轮中并行调用多个工具。默认 `true`。


            **注意** 仅 `gpt-5.6` 家族与 `gpt-5.5` 支持设为 `false`；`gpt-5.4` / `gpt-5.2`
            / `gpt-5.1` 上该参数不生效，始终按 `true` 执行。
          default: true
          example: true
        previous_response_id:
          type: string
          description: >-
            上一轮响应的 `id`，用于串联多轮对话，无需重复上传历史消息。


            **注意** 需配合 `store: true`（默认值）使用。响应有留存期限，过期后该 ID
            不再有效；此时请求会按新会话处理，不会继承上下文。对上下文准确性有强要求的场景，建议自行维护完整的 `input` 历史。
          example: resp_0f5c2b2c20c39e8a006a7ef545443081979e478b10927984b5
        store:
          type: boolean
          description: >-
            是否在服务端留存本次响应，留存后才能被 `previous_response_id` 引用。默认 `true`。


            **注意** 仅 `gpt-5.6` 家族与 `gpt-5.5` 支持设为 `false`；`gpt-5.4` / `gpt-5.2`
            / `gpt-5.1` 上该参数不生效，始终按 `true` 执行。不希望留存的场景请选用支持关闭的模型。
          default: true
          example: true
        include:
          type: array
          description: |-
            要求在响应中额外返回的内容，可选值：

            - `reasoning.encrypted_content`
            - `message.output_text.logprobs`
            - `web_search_call.results`
            - `web_search_call.action.sources`
            - `file_search_call.results`
            - `code_interpreter_call.outputs`
            - `message.input_image.image_url`
            - `computer_call_output.output.image_url`
          items:
            type: string
          example:
            - reasoning.encrypted_content
        temperature:
          type: number
          description: >-
            采样温度，取值 0 ~ 2，值越低输出越确定。


            **注意** `gpt-5.4` / `gpt-5.2` / `gpt-5.1` 上取值 `0` 不生效（等同于不传，按默认值 `1`
            处理）；需要更确定的输出请使用 `0.01` 等大于 0 的值。
          minimum: 0
          maximum: 2
          example: 0.7
        top_p:
          type: number
          description: 核采样参数，取值 0 ~ 1。建议不要与 `temperature` 同时调整。
          minimum: 0
          maximum: 1
          example: 0.9
        top_logprobs:
          type: integer
          description: >-
            每个位置返回的候选 token 数量，取值 0 ~ 20，需配合 `include:
            ["message.output_text.logprobs"]` 使用。


            **注意** 仅 `gpt-5.6` 家族与 `gpt-5.5` 支持；其余模型不支持该参数。
          minimum: 0
          maximum: 20
          example: 2
        frequency_penalty:
          type: number
          description: |-
            频率惩罚，取值 -2 ~ 2，降低重复内容的概率。

            **注意** 仅 `gpt-5.6` 家族支持；其余模型不支持该参数。
          minimum: -2
          maximum: 2
          example: 0.5
        presence_penalty:
          type: number
          description: |-
            存在惩罚，取值 -2 ~ 2，鼓励模型讨论新话题。

            **注意** 仅 `gpt-5.6` 家族支持；其余模型不支持该参数。
          minimum: -2
          maximum: 2
          example: 0.5
        truncation:
          type: string
          description: 上下文超出窗口时的处理方式：`disabled`（默认，直接报错）或 `auto`（自动截断中间内容）。
          enum:
            - auto
            - disabled
          default: disabled
          example: auto
        context_management:
          type: array
          description: >-
            长会话自动压缩配置，例如 `[{"type": "compaction", "compact_threshold":
            100000}]`：上下文超过阈值时自动压缩历史。


            **注意** 仅 `gpt-5.6` 家族支持；其余模型不支持该参数。
          items:
            type: object
        prompt_cache_key:
          type: string
          description: 缓存分组键。为同一类前缀相同的请求传入相同的值，可提升 Prompt 缓存命中率。
          example: app-agent-v1
        prompt_cache_retention:
          type: string
          description: Prompt 缓存保留策略：`in_memory`（默认）或 `24h`（延长缓存留存时间）。
          enum:
            - in_memory
            - 24h
          example: in_memory
        prompt:
          type: object
          description: >-
            引用已创建的 Prompt 模板，形如 `{"id": "pmpt_xxx", "version": "1", "variables":
            {...}}`。
          properties:
            id:
              type: string
            version:
              type: string
            variables:
              type: object
        metadata:
          type: object
          description: 自定义键值对，随响应原样返回，便于业务侧标记。键与值均为字符串。
          example:
            trace_id: abc-123
        safety_identifier:
          type: string
          description: |-
            终端用户的稳定标识，用于滥用行为追踪。

            **注意** 仅 `gpt-5.6` 家族支持；其余模型不支持该参数。
          example: user-1024
        user:
          type: string
          description: 终端用户标识，用于区分调用来源。
          example: user-1024
    ResponsesResponse:
      type: object
      properties:
        id:
          type: string
          description: 响应的唯一标识，可作为下一轮的 `previous_response_id`
          example: resp_0f5c2b2c20c39e8a006a7ef545443081979e478b10927984b5
        object:
          type: string
          enum:
            - response
          description: 响应类型
          example: response
        status:
          type: string
          description: >-
            响应状态：`completed` 正常结束，`incomplete` 因达到 `max_output_tokens`
            等原因未写完，`failed` 生成失败
          enum:
            - completed
            - incomplete
            - failed
          example: completed
        model:
          type: string
          description: 实际使用的模型名称
          example: gpt-5.6-sol
        created_at:
          type: integer
          description: 创建时间戳
          example: 1786705221
        output:
          type: array
          description: >-
            按生成顺序排列的输出项：`reasoning` 项（推理摘要 / 加密推理内容）、工具调用项（如
            `web_search_call`、`code_interpreter_call`），以及最后含 `output_text` 内容的
            `message` 项。
          items:
            $ref: '#/components/schemas/OutputItem'
        incomplete_details:
          type: object
          description: '`status` 为 `incomplete` 时说明原因'
        usage:
          $ref: '#/components/schemas/Usage'
        metadata:
          type: object
          description: 请求中传入的自定义键值对，原样返回
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP 状态错误码
            message:
              type: string
              description: 错误描述
            type:
              type: string
              description: 错误类型
            param:
              type: string
              description: 相关参数名
            fallback_suggestion:
              type: string
              description: 出错时的处理建议
    InputItem:
      type: object
      description: |-
        输入项：消息项（`role` + `content`），或上一轮的工具结果项（如 `function_call_output`）

        回填工具结果时的写法：

        ```json
        {
          "type": "function_call_output",
          "call_id": "call_abc123",
          "output": "{\"temp_c\": 21}"
        }
        ```
      properties:
        role:
          type: string
          description: 消息角色
          enum:
            - system
            - developer
            - user
            - assistant
          example: user
        content:
          description: 输入内容：字符串，或内容块数组（`input_text` / `input_image` 混合）
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/InputContentBlock'
        type:
          type: string
          description: 输入项类型。普通消息项可省略；回填工具结果时填 `function_call_output`。
          enum:
            - function_call_output
          example: function_call_output
        call_id:
          type: string
          description: >-
            对应上一轮 `function_call` 输出项的 `call_id`（注意不是它的 `id`）。仅
            `function_call_output` 项需要。
          example: call_abc123
        output:
          type: string
          description: 工具执行结果，字符串形式（JSON 结果需自行序列化成字符串）。仅 `function_call_output` 项需要。
          example: '{"temp_c": 21}'
    Tool:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: 工具类型
          enum:
            - web_search
            - web_search_preview
            - code_interpreter
            - file_search
            - mcp
            - function
          example: web_search
    OutputItem:
      type: object
      properties:
        id:
          type: string
          description: 输出项标识
        type:
          type: string
          description: 输出项类型
          enum:
            - reasoning
            - message
            - web_search_call
            - code_interpreter_call
            - file_search_call
            - mcp_call
            - function_call
          example: web_search_call
        status:
          type: string
          description: 输出项状态
          example: completed
        content:
          type: array
          description: 消息内容片段（`output_text`），出现在 `message` 项上
          items:
            type: object
        encrypted_content:
          type: string
          description: >-
            加密的推理内容，出现在 `reasoning` 项上，需在请求中声明 `include:
            ["reasoning.encrypted_content"]`
    Usage:
      type: object
      description: Token 用量统计。Prompt 缓存自动生效，命中缓存的输入 token 按更低的缓存价计费。
      properties:
        input_tokens:
          type: integer
          description: 输入 token 数
          example: 18
        output_tokens:
          type: integer
          description: 输出 token 数（含推理 token）
          example: 42
        total_tokens:
          type: integer
          description: 总 token 数
          example: 60
        input_tokens_details:
          type: object
          description: 输入 token 明细
          properties:
            cached_tokens:
              type: integer
              description: 命中缓存的 token 数
              example: 0
            cache_write_tokens:
              type: integer
              description: 写入缓存的 token 数
              example: 0
        output_tokens_details:
          type: object
          description: 输出 token 明细
          properties:
            reasoning_tokens:
              type: integer
              description: 推理 token 数
              example: 16
    InputContentBlock:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: |-
            内容类型

            - `input_text`：文本块
            - `input_image`：图片输入
          enum:
            - input_text
            - input_image
          example: input_image
        text:
          type: string
          description: 当 `type=input_text` 时的文本内容
          example: 这张图里有什么？
        image_url:
          type: string
          description: >-
            图片的公网 URL（当 `type=input_image` 时）。必须是字符串；写成 `{ "url": "..." }` 会返回
            `400`。图片需能被正常下载，否则同样返回 `400`。
          example: https://example.com/photo.png
        detail:
          type: string
          description: |-
            图片解析精度，与 `image_url` 同级（不是嵌套在里面）

            - `low`：低精度，消耗 token 更少
            - `high`：高精度，识别更细
            - `original`：按原图尺寸解析
            - `auto`（默认）：由模型自动决定
          enum:
            - auto
            - low
            - high
            - original
          default: auto
          example: auto
      description: 多模态内容块，通过 `type` 声明类型，仅填写与该类型匹配的字段。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        ##所有接口均需 Bearer Token 认证##

        **获取 API Key：**

        访问 [API Key 管理页面](https://evolink.ai/dashboard/keys) 获取你的 API Key

        **添加到请求头：**
        ```
        Authorization: Bearer YOUR_API_KEY
        ```

````