> ## 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.

# Create response

> Create a model response using the Responses format.

`POST /v1/responses`

Provide `model` and `input`. Use a string for text input. Input-item arrays, multimodal content, and tools must follow the Responses protocol supported by the target model.

## Read the result

Check `status` first and treat only `completed` as a complete result. For text, traverse message items in `output`, then read `text` from `output_text` entries in `content`. Output can also contain reasoning, tools, and other items. The SDK's `output_text` is a convenience property, not a required raw JSON field.

Streaming uses named SSE events; a Chat Completions `choices[].delta` parser cannot parse it. See [streaming](/en/guides/streaming.md).

## State and channel limits

`previous_response_id`, `store`, built-in tools, background tasks, and retrieval depend on the channel, model, and deployment. Ordinary relay and task plugins can have different capabilities; these are not global guarantees. This page covers synchronous and streaming creation, without promising background mode, retrieval of arbitrary response IDs, or cross-channel conversation continuation.

For stateless use, send the required context in `input`. Before using previous response IDs, confirm storage and routing behavior with your administrator. `store: false` is not a substitute for the deployment's data-retention policy.

[HTTP examples](/en/guides/http.md) · [Python](/en/guides/python.md) · [TypeScript](/en/guides/typescript.md) · [Error handling](/en/guides/errors.md)

## Application examples and extended output

* [Conversations](/en/guides/conversations.md): replay complete history without depending on stored response IDs.
* [Function tools](/en/guides/tool-calling.md): correlate `function_call_output` using `call_id`.
* [Structured output](/en/guides/structured-output.md): use `text.format` and validate business fields.
* [Vision](/en/guides/vision.md): send `input_text` and `input_image`.

`include` requests additional output supported by the model, such as `reasoning.encrypted_content`. When replaying reasoning state, preserve full output items, including any `phase` and `encrypted_content` fields returned by the channel. Native Responses forwarding and conversion from other protocols may preserve different fields; verify the target channel. Optional fields in the response reference are not a promise that every conversion path returns them.

Message content can contain `type: refusal`. Even with overall status `completed`, check message status, refusals, and empty output rather than relying on `output_text` alone.

[API coverage](/en/guides/api-coverage.md) · [Production integration](/en/guides/production.md) · [Troubleshooting](/en/guides/troubleshooting.md)

[Compaction](/en/guides/compaction.md) · [Background tasks and retrieval](/en/guides/background-responses.md)

[简体中文](/zh/api-reference/responses.md)

## Cache, reasoning, and context controls

The native request DTO includes `prompt_cache_key`, `prompt_cache_retention`, `prompt_cache_options`, `reasoning`, `truncation`, and `context_management`. Being represented does not guarantee support in every model, plugin, or conversion path.

Current Responses-to-Chat conversion rejects `previous_response_id`, `conversation`, `prompt`, and `context_management`; it also lacks mappings for `prompt_cache_options` and `truncation`. Confirm a supporting native path when these semantics are required. Verify reasoning effort, summary, mode, and context against the target model; do not reuse Chat's nested budget structure.

`usage.input_tokens_details.cached_tokens` and `output_tokens_details.reasoning_tokens` are optional statistics. Preserve complete output items for stateless continuation. `include: ["reasoning.encrypted_content"]` cannot make an unsupported channel return encrypted state. Manual compaction still uses the separate `/v1/responses/compact` endpoint.

Added fields verified against revision `30a6d88a4`.

[Prompt caching](/en/guides/prompt-caching.md) · [Reasoning](/en/guides/reasoning-models.md) · [Context management](/en/guides/context-management.md)

## File input and built-in search

Native `input` messages can contain `input_file` content items with sibling `filename` and Data URL `file_data`. A `file_id` requires an existing accessible file in the target upstream; this gateway does not implement general `/v1/files` management.

Native `tools` can contain upstream-supported search tools alongside `tool_choice`. These are not guaranteed across protocol conversions or all channels. Search items use `web_search_call`; message `content[].annotations` carries `url_citation` offsets belonging to that original text block. Overall `status: completed` alone does not establish search execution or citations.

[PDF example](/en/guides/file-inputs.md) · [Search example](/en/guides/web-search.md) · [Parameter filtering](/en/guides/data-controls.md)

## Tool policies and JSON mode

`tool_choice` can request auto, required, none, or a selected function. `parallel_tool_calls: false` requests at most one function call per turn. See [tool controls](/en/guides/tool-controls.md) for protocol shapes, strict conversion limits, and a complete example.

JSON mode requests JSON without a business Schema guarantee. See [JSON mode](/en/guides/json-mode.md) for both protocol shapes and runnable examples.


## 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.