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

# 创建响应

> 使用 Responses 结构发起模型调用。

`POST /v1/responses`

提供 `model` 和 `input`。文本输入可直接使用字符串；输入项数组、多模态和工具格式需符合目标模型支持的 Responses 协议。

## 读取结果

先检查 `status`，仅在 `completed` 时按完整结果处理。对于文本，遍历 `output` 中的消息项，再遍历 `content` 中的 `output_text` 项读取 `text`；输出还可能含推理、工具调用和其他项。SDK 的 `output_text` 是便捷属性，不是原始 JSON 必有字段。

流式请求使用具名 SSE 事件，不能套用 Chat Completions 的 `choices[].delta` 解析器。详情见[流式输出](/zh/guides/streaming)。

## 状态和渠道限制

`previous_response_id`、`store`、内置工具、后台任务和响应检索依赖渠道、模型及部署配置。普通转发与任务插件的能力可能不同，不能把它们视为全局保证。此页只描述同步与流式创建，不承诺后台模式、任意响应 ID 检索或跨渠道会话续接。

无需服务端状态时，将所需上下文放入 `input`；依赖先前响应时，先和管理员确认保存与路由行为。`store: false` 也不能替代部署方的数据保留说明。

[HTTP 示例](/zh/guides/http) · [Python](/zh/guides/python) · [TypeScript](/zh/guides/typescript) · [错误处理](/zh/guides/errors)

## 应用示例与扩展输出

* [多轮对话](/zh/guides/conversations)：显式重放完整历史，不依赖已保存的响应 ID。
* [函数工具](/zh/guides/tool-calling)：通过 `call_id` 关联 `function_call_output`。
* [结构化输出](/zh/guides/structured-output)：使用 `text.format` 并校验业务字段。
* [图片理解](/zh/guides/vision)：发送 `input_text` 和 `input_image`。

`include` 可请求模型支持的附加输出，例如 `reasoning.encrypted_content`。需要重放推理状态时，保留完整输出项和渠道返回的 `phase`、`encrypted_content` 等字段。原生 Responses 转发与其他协议转换的保留能力可能不同，必须通过目标渠道验证。响应参数表展示的可选字段不代表所有转换路径都会返回它们。

文本内容中可能出现 `type: refusal`；即使整体状态为 `completed`，也要检查消息状态、拒答及空输出，不能仅凭 `output_text` 判断成功。

[接口支持范围](/zh/guides/api-coverage) · [生产接入](/zh/guides/production) · [接入排障](/zh/guides/troubleshooting)

[上下文压缩](/zh/guides/compaction) · [后台任务与查询](/zh/guides/background-responses)

[Read in English](/en/api-reference/responses)

## 缓存、推理与上下文控制

原生请求 DTO 包含 `prompt_cache_key`、`prompt_cache_retention`、`prompt_cache_options`、`reasoning`、`truncation` 和 `context_management`。字段存在仅说明项目能表达它，不保证每个模型、插件或转换路径都支持。

当前 Responses 转 Chat 会拒绝 `previous_response_id`、`conversation`、`prompt` 和 `context_management`；`prompt_cache_options`、`truncation` 也没有对应映射。需要这些语义时确认使用支持它们的原生链路。`reasoning` 中的 effort、summary、mode、context 均应按目标模型确认，不能套用 Chat 的嵌套预算结构。

`usage.input_tokens_details.cached_tokens` 与 `output_tokens_details.reasoning_tokens` 是可选统计。无状态续聊保留完整输出项；`include: ["reasoning.encrypted_content"]` 不能弥补不支持密文的渠道。手动压缩仍使用独立的 `/v1/responses/compact`。

新增字段核对版本：`30a6d88a4`。

[提示词缓存](/zh/guides/prompt-caching) · [推理模型](/zh/guides/reasoning-models) · [上下文管理](/zh/guides/context-management)

## 文件输入与内置搜索

原生 `input` 消息可携带 `input_file` 内容项：`filename` 和 Data URL `file_data` 与 `type` 同层。`file_id` 需要目标上游已经存在且可访问的文件；本网关未实现通用 `/v1/files` 管理。

原生 `tools` 可携带上游支持的搜索工具，配合 `tool_choice`。它们不保证跨协议保留或适用于所有渠道。完成搜索项为 `web_search_call`；引用位于消息 `content[].annotations` 中的 `url_citation`，索引属于该原始文本块。`status: completed` 本身不保证执行了搜索或存在引用。

[PDF 示例](/zh/guides/file-inputs) · [搜索示例](/zh/guides/web-search) · [参数过滤](/zh/guides/data-controls)

## 工具策略与 JSON 模式

`tool_choice` 可请求 auto、required、none 或指定函数，`parallel_tool_calls: false` 请求单轮最多一个函数调用。字段形状、strict 转换限制与完整示例见 [工具控制](/zh/guides/tool-controls)。

JSON 模式只请求 JSON，不提供业务 Schema 保证；两个协议的字段形状和可运行示例见 [JSON 模式](/zh/guides/json-mode)。


## OpenAPI

````yaml openapi/relay.json POST /v1/responses
openapi: 3.0.3
info:
  title: API — Core inference API
  version: 0.5.0
  description: >-
    面向接入的精选规范，不是全部管理或供应商接口。 / Curated integration specification, not the entire
    management or provider API.
  license:
    name: AGPL-3.0-or-later
servers:
  - url: https://gateway.example.com
    description: >-
      Example only; replace with your gateway origin and optional path prefix,
      without /v1.
security:
  - BearerAuth: []
paths:
  /v1/responses:
    post:
      summary: 创建响应 / Create response
      description: >-
        仅记录常用接入字段；可选参数和行为取决于模型、渠道与部署配置。 / Documents common integration fields;
        optional parameters and behavior depend on the model, channel, and
        deployment.
      operationId: createResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
            example:
              model: YOUR_MODEL_ID
              input: Say hello in one short sentence.
      responses:
        '200':
          description: >-
            成功响应；stream=true 时返回 SSE，仍需检查终止事件。 / Successful response;
            stream=true returns SSE; still check terminal events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
              example:
                id: resp_example
                object: response
                created_at: 1700000000
                model: YOUR_MODEL_ID
                status: completed
                output:
                  - id: msg_example
                    type: message
                    role: assistant
                    status: completed
                    content:
                      - type: output_text
                        text: Hello!
                        annotations: []
                error: null
                incomplete_details: null
                usage:
                  input_tokens: 12
                  output_tokens: 3
                  total_tokens: 15
            text/event-stream:
              schema:
                type: string
              example: >+
                event: response.output_text.delta

                data: {"type":"response.output_text.delta","delta":"Hello!"}


                event: response.completed

                data:
                {"type":"response.completed","response":{"status":"completed"}}

        '400':
          description: 请求参数错误 / Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 身份校验失败 / Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 访问被拒绝 / Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 接口或资源不存在 / Endpoint or resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 请求被限流或受配额限制 / Rate or quota restriction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 网关或上游错误 / Gateway or upstream error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 服务暂不可用 / Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: 其他网关或上游错误；格式可能不同 / Other gateway or upstream error; shape may vary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ResponsesRequest:
      type: object
      properties:
        model:
          type: string
          description: >-
            模型列表返回的原始 ID；需要支持当前接口 / Exact ID from the model list; must support
            this endpoint
          example: YOUR_MODEL_ID
        input:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                additionalProperties: true
          description: >-
            文本或输入项数组；内容块和工具项需模型支持 / Text or input items; content blocks and tool
            items require model support；原生 input_file 可携带 filename 和 Data URL
            file_data，需上游支持 / Native input_file may carry filename and Data URL
            file_data; upstream support required
        instructions:
          type: string
        stream:
          type: boolean
          description: >-
            是否返回 SSE 事件；取决于模型和渠道支持 / Return SSE events when supported by the
            model and channel
          default: false
        max_output_tokens:
          type: integer
          description: >-
            生成上限；模型可能要求更小的值，并限制与其他字段组合 / Output limit; models may impose a
            smaller limit or parameter restrictions
          minimum: 0
          maximum: 1073741823
        temperature:
          type: number
          description: >-
            采样温度；范围、默认值和是否可用由模型决定 / Sampling temperature; range, default, and
            support depend on the model
        top_p:
          type: number
          description: >-
            核采样；范围、默认值和是否可用由模型决定 / Nucleus sampling; range, default, and support
            depend on the model
        previous_response_id:
          type: string
          description: >-
            关联先前响应；依赖渠道的状态保存及路由能力 / Reference a previous response; requires
            compatible state retention and routing
        store:
          type: boolean
          description: >-
            默认允许；DisableStore 删除字段而非强制 false，不是保留策略保证 / Allowed by default;
            DisableStore removes rather than forces false; not a retention
            guarantee
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            工具定义；不同于 Chat Completions 工具结构 / Tool definitions; differ from Chat
            Completions tool objects；内置 web_search_preview / web_search
            需原生上游支持，不保证跨协议语义 / Built-in web_search_preview or web_search needs
            native upstream support; cross-protocol semantics not guaranteed
        tool_choice:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >-
            auto / required / none 或指定函数；Chat 为嵌套 function.name，Responses 为同层
            name，需模型支持 / auto / required / none or a selected function; nested
            function.name in Chat, sibling name in Responses; requires model
            support
        reasoning:
          type: object
          description: >-
            Responses 推理配置；可用字段和值由模型和转换路径决定 / Responses reasoning configuration;
            supported fields and values depend on model and conversion
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
          properties:
            effort:
              type: string
              example: medium
            summary:
              type: string
              description: >-
                请求公开推理摘要，不是内部完整思维过程 / Requests a public summary, not a full
                internal reasoning trace
            mode:
              description: >-
                条件支持的原生扩展；不保证跨协议保留 / Conditional native extension; not
                guaranteed across protocols
            context:
              description: >-
                条件支持的上下文策略；值依模型而定 / Conditional reasoning context policy;
                model-dependent values
          additionalProperties: true
        text:
          type: object
          additionalProperties: true
          description: >-
            输出文本及格式选项；需模型支持 / Text output and format options; require model
            support
          properties:
            format:
              type: object
              properties:
                type:
                  type: string
                  example: json_object
              additionalProperties: true
              description: >-
                json_object 或 json_schema 等模型支持格式，不是 Chat 的 response_format /
                Model-supported format such as json_object or json_schema; not
                Chat response_format
        include:
          type: array
          items:
            type: string
          description: >-
            请求附加输出，如 reasoning.encrypted_content；依赖模型和渠道支持 / Request extra
            output such as reasoning.encrypted_content; requires model and
            channel support
          example:
            - reasoning.encrypted_content
        background:
          type: boolean
          description: >-
            后台执行依赖渠道；插件必须声明 background，检索仅适用于宿主任务响应 / Background execution
            depends on the channel; plugins must declare background; retrieval
            covers only host task responses
        prompt_cache_key:
          type: string
          description: >-
            缓存分组提示；不保证命中、亲和或权限隔离 / Cache grouping hint; no guarantee of hits,
            affinity, or authorization isolation
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
        prompt_cache_retention:
          type: string
          description: >-
            缓存保留提示，值依赖上游模型；跨协议转换不保证保留 / Retention hint with model-dependent
            values; not guaranteed across conversion
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
        prompt_cache_options:
          type: object
          description: >-
            支持该字段的原生上游专用；Responses 转 Chat 当前不映射 / For supporting native
            upstreams; currently not mapped from Responses to Chat
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
          additionalProperties: true
        truncation:
          type: string
          description: >-
            上游截断策略，例如 disabled / auto；原生模型需支持，转 Chat 不映射 / Upstream truncation
            policy such as disabled / auto; native support required, not mapped
            to Chat
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
        context_management:
          type: array
          description: >-
            原生上下文管理条目；依赖模型，Responses 转 Chat 会拒绝该字段 / Native context-management
            entries; model dependent; Responses-to-Chat conversion rejects this
            field
          x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
          items:
            type: object
            additionalProperties: true
        service_tier:
          type: string
          description: >-
            默认过滤，需渠道允许和上游支持 / Filtered by default; requires channel permission
            and upstream support
        safety_identifier:
          type: string
          description: 默认过滤，需渠道允许 / Filtered by default; requires channel permission
        parallel_tool_calls:
          type: boolean
          description: >-
            显式 false 请求单轮最多一个函数调用；模型/渠道条件支持，不调度应用并发 / Explicit false requests at
            most one function call per turn; model/channel dependent, not
            application concurrency control
      required:
        - model
        - input
      x-source-files:
        - relaykit/dto/openai_request.go
        - relay/channel/openai/adaptor.go
        - relaykit/relayconvert/reasoning/intent.go
        - relaykit/relayconvert/internal/oai_responses/to_oai_chat_req.go
        - relaykit/relayconvert/internal/oai_chat/to_oai_responses_req.go
        - relay/channel/openai/relay-openai.go
        - relay/common/relay_info.go
    ResponsesResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: response
        created_at:
          type: number
        model:
          type: string
        status:
          type: string
          description: >-
            必须检查完成状态，例如 completed、failed、incomplete / Check completion status,
            for example completed, failed, or incomplete
        output:
          type: array
          items:
            $ref: '#/components/schemas/OutputItem'
        error:
          type: object
          nullable: true
          additionalProperties: true
        incomplete_details:
          type: object
          nullable: true
          additionalProperties: true
        usage:
          type: object
          properties:
            input_tokens:
              type: integer
            output_tokens:
              type: integer
            total_tokens:
              type: integer
            input_tokens_details:
              type: object
              nullable: true
              properties:
                cached_tokens:
                  type: integer
                  description: >-
                    报告的缓存读取 token；缺失不等于零，不代表最终账单 / Reported cache-read tokens;
                    absence is not zero and this is not an invoice
                  x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
                  minimum: 0
                cache_write_tokens:
                  type: integer
                  description: >-
                    支持渠道报告的缓存写入 token；不要跨协议机械相加 / Cache-write tokens reported by
                    supporting channels; do not mechanically sum across
                    protocols
                  x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
                  minimum: 0
              additionalProperties: true
            output_tokens_details:
              type: object
              nullable: true
              properties:
                reasoning_tokens:
                  type: integer
                  description: >-
                    报告的推理 token；可能缺失，不等同于可见文本长度 / Reported reasoning tokens; may
                    be absent, not visible text length
                  x-source-revision: 30a6d88a4fa41009755d0f157d1656ced297803d
                  minimum: 0
              additionalProperties: true
          nullable: true
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            param:
              type: string
              nullable: true
            code:
              nullable: true
              description: 错误标识；类型随上游变化 / Error identifier; type varies by upstream
    OutputItem:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          example: message
        role:
          type: string
          example: assistant
        status:
          type: string
        content:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                example: output_text
              text:
                type: string
              annotations:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: url_citation
                    url:
                      type: string
                    title:
                      type: string
                    start_index:
                      type: integer
                    end_index:
                      type: integer
                  additionalProperties: true
                description: >-
                  引用偏移属于该原始文本块；不要合并后复用索引 / Citation offsets belong to this
                  original text block; do not reuse after merging
              refusal:
                type: string
                description: type 为 refusal 时的拒答文本 / Refusal text when type is refusal
        call_id:
          type: string
          description: >-
            function_call 的结果关联 ID，不等同于输出项 id / Correlates function_call
            results; distinct from the output item id
        name:
          type: string
          description: function_call 的函数名称 / Function name for a function_call
        arguments:
          type: string
          description: >-
            函数参数的 JSON 字符串；执行前校验 / JSON-encoded function arguments; validate
            before execution
        summary:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              text:
                type: string
          description: 推理摘要项；可能为空 / Reasoning summary items; may be empty
        encrypted_content:
          type: string
          description: >-
            支持的渠道返回的不透明推理状态；原样保留，不解码 / Opaque reasoning state returned by
            supporting channels; preserve without decoding
        phase:
          type: string
          description: >-
            支持的模型返回的消息阶段；重放时保留 / Message phase returned by supporting models;
            preserve when replaying
      description: >-
        也可能是工具调用、推理或其他输出项；不要假定第一项就是文本 / May also be a tool, reasoning, or other
        output item; do not assume the first item is text；原生搜索项可为
        web_search_call，检查其 status / Native search items may use
        web_search_call; check their status
      x-source-files:
        - relaykit/dto/openai_request.go
        - relay/channel/openai/relay-openai.go
        - relay/common/relay_info.go
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 模型调用 API Key，不是控制台登录凭据 / Model API key, not console login credentials

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.