> ## 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` と比較して、このエンドポイントは、テキスト、画像、推論コントロール、ツールがすべて 1 つの応答モデルを共有しているため、新しい統合に適しています。サポートされるフィールドはモデルによって異なります。

## 統合ガイダンス

* `Authorization: Bearer {API_KEY}`で認証する
* テキスト、JSON 出力、ツール呼び出し、および将来のマルチモーダル ワークフローに 1 つのサーフェスが必要な場合は、このエンドポイントを優先します。
* `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

````