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

# /v1/responses

> Unified OpenAI-compatible responses endpoint for text generation, multimodal input, and structured outputs.

用于创建统一的模型响应对象，适合文本生成、结构化输出、工具调用以及多模态输入。

这个接口比 `chat.completions` 更适合做新接入，因为它把文本、图像、工具和推理控制放进了同一套请求模型。不同模型支持的字段会有差异，尤其是推理能力、工具能力和多模态输入范围。

## 接入说明

* 鉴权方式使用 `Authorization: Bearer {API_KEY}`
* 如果你要统一文本输出、结构化 JSON、工具调用和后续多模态扩展，优先使用这个接口
* 多轮对话可以通过 `previous_response_id` 串联上下文
* 推理模型场景下，建议把 `reasoning`、`max_output_tokens` 和 `tools` 这类控制项收敛到服务端统一下发
* 流式接入时同样需要按事件流逐段消费，而不是等待整包 JSON

## 请求重点

* `input` 是最常见的输入字段，可以承载文本或多模态内容块
* `model` 用于指定本次调用的模型 ID
* 如果要连续对话，可以结合 `previous_response_id` 复用上下文，而不是每次重传全部历史
* 如果要做结构化输出，优先显式声明 JSON 格式相关配置，再在服务端做结果校验
* 如果要启用工具调用，需要一并传入 `tools`，并处理模型返回的工具调用结果

## 返回重点

* 简单文本结果通常可以从 `output_text` 读取
* 更完整的结构化结果需要查看 `output[]` 中的各类内容块
* 工具调用、推理片段和多模态输出也会落在统一响应对象里，客户端不要只假设返回纯文本
* 计费用量与输出状态可以从响应对象的元信息和 `usage` 字段中读取


## OpenAPI

````yaml POST /v1/responses
openapi: 3.1.0
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api-vip.apigo.ai
security:
  - bearerAuth: []
paths:
  /v1/responses:
    post:
      summary: OpenAI responses
      description: 统一的兼容 OpenAI 的响应接口，支持文本生成、多模态输入和结构化输出。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAIResponsesRequest'
      responses:
        '200':
          description: Successful responses payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIResponsesResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OpenAIResponsesRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          example: gpt-4.1
        input:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
        instructions:
          type: string
        max_output_tokens:
          type: integer
    OpenAIResponsesResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: response
        status:
          type: string
        output_text:
          type: string
        output:
          type: array
          items:
            type: object
        usage:
          type: object
          properties:
            input_tokens:
              type: integer
            output_tokens:
              type: integer
            total_tokens:
              type: integer
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````