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

Creates a unified response object for text generation, structured output, tool calls, and multimodal input.

Compared with `chat.completions`, this endpoint is a better fit for new integrations because text, images, reasoning controls, and tools all share one response model. Supported fields still vary by model.

## Integration guidance

* Authenticate with `Authorization: Bearer {API_KEY}`
* Prefer this endpoint when you want one surface for text, JSON output, tool calls, and future multimodal workflows
* Use `previous_response_id` to continue a conversation without resending the full history
* For reasoning-model workflows, centralize `reasoning`, `max_output_tokens`, and `tools` in your server-side gateway
* Streaming clients should consume incremental events instead of waiting for one final payload

## Request highlights

* `input` is the primary input field and can carry text or multimodal content blocks
* `model` selects the target model for the response
* `previous_response_id` is the main way to chain turns across a conversation
* For structured output, declare explicit JSON formatting requirements and validate server-side
* For tool use, pass `tools` and handle tool call outputs explicitly

## Response highlights

* Simple text can often be read from `output_text`
* Richer results should be read from `output[]`
* Tool calls, reasoning traces, and multimodal outputs all share the same response object
* Usage and status metadata should be read from the response object rather than inferred from text alone


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

````