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

# /v1/responses

> 텍스트 생성, 다중 모드 입력 및 구조화된 출력을 위한 통합 OpenAI 호환 응답 엔드포인트입니다.

텍스트 생성, 구조화된 출력, 도구 호출 및 다중 모드 입력을 위한 통합 응답 개체를 만듭니다.

`chat.completions`와 비교할 때 이 엔드포인트는 텍스트, 이미지, 추론 제어 및 도구가 모두 하나의 응답 모델을 공유하므로 새로운 통합에 더 적합합니다. 지원되는 필드는 여전히 모델에 따라 다릅니다.

## 통합 지침

* `Authorization: Bearer {API_KEY}`로 인증
* 텍스트, JSON 출력, 도구 호출 및 향후 다중 모드 워크플로를 위한 하나의 표면을 원하는 경우 이 엔드포인트를 선호합니다.
* 전체 기록을 다시 전송하지 않고 대화를 계속하려면 `previous_response_id`를 사용하세요.
* 추론 모델 워크플로의 경우 서버 측 게이트웨이에서 `reasoning`, `max_output_tokens` 및 `tools`를 중앙 집중화합니다.
* 스트리밍 클라이언트는 하나의 최종 페이로드를 기다리는 대신 증분 이벤트를 소비해야 합니다.

## 요청 하이라이트

* `input`는 기본 입력 필드이며 텍스트 또는 다중 모드 콘텐츠 블록을 전달할 수 있습니다.
* `model`는 응답의 대상 모델을 선택합니다.
* `previous_response_id`는 대화 전반에 걸쳐 차례를 연결하는 주요 방법입니다.
* 구조화된 출력의 경우 명시적인 JSON 형식 요구 사항을 선언하고 서버 측 유효성을 검사합니다.
* 도구 사용의 경우 `tools`를 전달하고 도구 호출 출력을 명시적으로 처리합니다.

## 응답 하이라이트

* `output_text`에서 간단한 텍스트를 읽을 수 있는 경우가 많습니다.
* `output[]`에서 더 풍부한 결과를 읽어야 합니다.
* 도구 호출, 추론 추적 및 다중 모드 출력은 모두 동일한 응답 개체를 공유합니다.
* 사용량 및 상태 메타데이터는 텍스트만으로 추론하기보다는 응답 개체에서 읽어야 합니다.


## 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://maas.apigo.ai
security:
  - bearerAuth: []
paths:
  /v1/responses:
    post:
      summary: OpenAI responses
      description: >-
        Unified OpenAI-compatible responses endpoint for text generation,
        multimodal input, and structured outputs.
      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

````