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

# Kimi API(모든 모델) - Responses 전체 참조

> reasoning.effort로 추론 강도, prompt_cache_options로 캐시를 설정합니다. 검색은 web_search_call 출력 항목으로 반환됩니다. 스트리밍에서는 response.completed / response.incomplete / response.failed를 처리하세요. 출력 한도에 도달하면 incomplete가 됩니다. 멀티턴 요청에는 추론, 도구 호출 및 결과를 포함한 전체 output 기록을 전달하세요.

> [!NOTE]
>
> **BaseURL**: 기본 BaseURL은 `https://direct.evolink.ai`이며 텍스트 모델과 장시간 연결을 더 잘 지원합니다. `https://api.evolink.ai`는 멀티모달 서비스의 기본 엔드포인트이자 텍스트 모델의 대체 주소입니다.


## OpenAPI

````yaml ko/api-manual/language-series/kimi/responses/responses-reference.json POST /v1/responses
openapi: 3.1.0
info:
  title: Kimi API(모든 모델) - Responses 전체 참조
  version: 1.0.0
  description: >-
    OpenAI Responses 프로토콜로 Kimi 텍스트 모델을 호출합니다. `model`로 `kimi-k3.1-pro`,
    `kimi-k3.1-pro-highspeed`, `kimi-k3`를 선택합니다. 모두 컨텍스트 창은 1,048,576 tokens이며
    여러 턴의 대화, 스트리밍, 도구 호출, 웹 검색, 구조화된 출력, 이미지 입력을 지원합니다.


    세 모델 모두 추론이 항상 활성화되며 `reasoning.effort`로 강도를 조절합니다. 구조화된 출력과 캐시 쓰기 TTL은 모델에
    따라 다릅니다. `model` 필드 설명을 확인하세요. 여러 턴의 대화에서는 추론과 도구 호출 기록을 모두 보존하세요.
servers:
  - url: https://direct.evolink.ai
    description: 프로덕션(권장)
  - url: https://api.evolink.ai
    description: 대체 URL
security:
  - bearerAuth: []
paths:
  /v1/responses:
    post:
      tags:
        - Responses
      summary: Kimi Responses API(모든 모델)
      description: >-
        reasoning.effort로 추론 강도, prompt_cache_options로 캐시를 설정합니다. 검색은
        web_search_call 출력 항목으로 반환됩니다. 스트리밍에서는 response.completed /
        response.incomplete / response.failed를 처리하세요. 출력 한도에 도달하면 incomplete가
        됩니다. 멀티턴 요청에는 추론, 도구 호출 및 결과를 포함한 전체 output 기록을 전달하세요.
      operationId: createResponseKimi
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
            examples:
              simple:
                summary: Pro 최소 요청
                value:
                  model: kimi-k3.1-pro
                  input: Reply with OK.
                  reasoning:
                    effort: low
                  max_output_tokens: 1024
              highspeed:
                summary: Highspeed 최소 요청
                value:
                  model: kimi-k3.1-pro-highspeed
                  input: Reply with OK.
                  reasoning:
                    effort: low
                  max_output_tokens: 1024
              k3:
                summary: Kimi K3 최소 요청
                value:
                  model: kimi-k3
                  input: Reply with OK.
                  max_output_tokens: 1024
              streaming:
                summary: Responses SSE 스트리밍
                value:
                  model: kimi-k3.1-pro
                  input: Reply with OK.
                  reasoning:
                    effort: low
                  max_output_tokens: 1024
                  stream: true
              multimodal:
                summary: 이미지 입력
                value:
                  model: kimi-k3.1-pro
                  input:
                    - role: user
                      content:
                        - type: input_image
                          image_url: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...
                        - type: input_text
                          text: 이 이미지를 설명해 주세요.
                  reasoning:
                    effort: low
                  max_output_tokens: 1024
              function_calling:
                summary: Function Call
                value:
                  model: kimi-k3.1-pro
                  input: 오늘 베이징 날씨를 확인해 주세요.
                  reasoning:
                    effort: low
                  max_output_tokens: 1024
                  tools:
                    - type: function
                      name: get_weather
                      description: 지정한 도시의 날씨 조회
                      parameters:
                        type: object
                        properties:
                          city:
                            type: string
                            description: 도시 이름
                        required:
                          - city
              web_search:
                summary: 서버 측 웹 검색
                value:
                  model: kimi-k3.1-pro
                  input: Use web search to find the official Kimi homepage URL.
                  reasoning:
                    effort: low
                  max_output_tokens: 1024
                  tools:
                    - type: web_search
              structured_output:
                summary: 엄격한 JSON Schema(K3.1 시리즈만 지원)
                value:
                  model: kimi-k3.1-pro
                  input: Return a JSON object with result equal to OK.
                  reasoning:
                    effort: low
                  max_output_tokens: 1024
                  text:
                    format:
                      type: json_schema
                      name: result
                      strict: true
                      schema:
                        type: object
                        properties:
                          result:
                            type: string
                        required:
                          - result
                        additionalProperties: false
              cache_1h:
                summary: 1h 캐시 자동 쓰기(K3.1 시리즈만 지원)
                value:
                  model: kimi-k3.1-pro
                  input: Reply with OK.
                  reasoning:
                    effort: low
                  max_output_tokens: 1024
                  prompt_cache_options:
                    mode: implicit
                    ttl: 1h
      responses:
        '200':
          description: 응답 생성 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ResponsesStreamEvent'
        '400':
          description: '잘못된 요청: 유효하지 않은 매개변수'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: '인증 실패: API 키가 유효하지 않거나 누락됨'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 이 리소스에 대한 접근 권한이 없습니다
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 요청 한도 초과 또는 할당량 부족
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 서버 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    ResponsesRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
          enum:
            - kimi-k3.1-pro
            - kimi-k3.1-pro-highspeed
            - kimi-k3
          default: kimi-k3.1-pro
          description: >-
            호출할 모델:


            | 모델 ID | 특성 | 추론 강도 |

            |---|---|---|

            | `kimi-k3.1-pro` | 최신 세대 모델(권장) | `low` / `high` / `max`, 기본값 `max`
            |

            | `kimi-k3.1-pro-highspeed` | Pro와 동일한 매개변수, 더 빠른 생성 |
            `kimi-k3.1-pro`와 동일 |

            | `kimi-k3` | 이전 세대 모델 | `max`만 지원 |


            세 모델 모두 컨텍스트 창은 1,048,576 tokens이며 추론이 항상 활성화됩니다.


            구조화된 출력(`text.format`)과 캐시 쓰기 TTL(`prompt_cache_options`)은 K3.1 시리즈만
            지원하며 `kimi-k3`는 지원하지 않습니다.
        input:
          description: >-
            이번 요청의 입력입니다. 문자열은 user 메시지 하나와 같습니다. 배열은 유형이 있는 항목을 순서대로 담으며 대화 기록,
            도구 호출 및 결과를 포함할 수 있습니다.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputItem'
        instructions:
          type: string
          description: 다른 지시보다 먼저 적용되는 최상위 시스템 지시입니다.
        stream:
          type: boolean
          default: false
          description: true이면 SSE 이벤트 스트림으로 응답합니다.
        max_output_tokens:
          type: integer
          description: >-
            추론과 최종 답변을 포함한 최대 생성 토큰 수입니다. 기본값은 131072, 최대값은 1048576이며 남은 컨텍스트의
            제한도 받습니다.
          minimum: 1
          maximum: 1048576
          default: 131072
        reasoning:
          type: object
          description: 추론 관련 설정입니다.
          properties:
            effort:
              type: string
              enum:
                - low
                - high
                - max
                - medium
                - xhigh
                - minimal
                - none
              default: max
              description: >-
                추론 강도. 추론은 항상 활성화됩니다.


                - `kimi-k3.1-pro` / `kimi-k3.1-pro-highspeed`: `low` / `high` /
                `max`를 권장하며 기본값은 `max`입니다. 범용 클라이언트 호환을 위해 `medium`은 `high`,
                `xhigh`는 `max`, `minimal` / `none`은 `low`로 처리합니다. `none`도 추론을 끄지
                않습니다.

                - `kimi-k3`: `max`만 지원합니다(기본값).


                강도를 높이면 일반적으로 추론 토큰과 지연 시간이 증가합니다. 추론 토큰은 출력에 포함됩니다.
        text:
          type: object
          description: 출력 텍스트 설정입니다.
          properties:
            format:
              type: object
              required:
                - type
                - schema
              description: >-
                JSON Schema로 출력 구조를 제한합니다. `kimi-k3.1-pro` /
                `kimi-k3.1-pro-highspeed`만 지원하며 `kimi-k3`는 지원하지 않습니다.
                `kimi-k3`에서 구조화된 출력이 필요하면 Chat Completions API의
                `response_format`을 사용하세요.
              properties:
                type:
                  type: string
                  enum:
                    - json_schema
                name:
                  type: string
                  description: 스키마 이름으로 기본값은 `output`입니다.
                schema:
                  type: object
                  description: 출력 구조를 정의하는 JSON Schema입니다.
                strict:
                  type: boolean
                  description: 스키마를 엄격히 적용할지 여부입니다.
        tools:
          type: array
          description: 모델이 호출할 수 있는 도구입니다.
          items:
            $ref: '#/components/schemas/ResponsesTool'
        tool_choice:
          $ref: '#/components/schemas/ResponsesToolChoice'
        include:
          type: array
          items:
            type: string
            enum:
              - web_search_call.results
              - web_search_call.action.sources
          description: >-
            추가로 반환할 필드이며 `web_search` 도구에만 적용됩니다.
            `web_search_call.action.sources`는 검색된 웹 출처를,
            `web_search_call.results`는 이미지 검색 결과를 반환합니다.
        prompt_cache_options:
          type: object
          description: >-
            컨텍스트 캐시 쓰기 옵션. `kimi-k3.1-pro` / `kimi-k3.1-pro-highspeed`만 지원하며
            `kimi-k3`는 이 매개변수를 지원하지 않습니다. 생략하면 기본적으로 5m 캐시에 자동으로 기록합니다. 쓰기와 읽기는
            별도로 과금됩니다.
          properties:
            mode:
              type: string
              enum:
                - implicit
              default: implicit
            ttl:
              type: string
              enum:
                - 5m
                - 1h
              default: 5m
              description: 캐시 유효 기간은 5m 또는 1h이며 기본값은 5m입니다.
        temperature:
          type: number
          default: 1
          description: >-
            샘플링 온도. 모델에서 `1`로 고정하므로 전달할 필요가 없습니다. `kimi-k3.1-pro` /
            `kimi-k3.1-pro-highspeed`는 이 필드를 자동으로 무시하며 `kimi-k3`는 지원하지 않는 값에 대해
            오류를 반환합니다.
        top_p:
          type: number
          default: 0.95
          description: >-
            핵 샘플링 임계값. 모델에서 `0.95`로 고정하므로 전달할 필요가 없습니다. `kimi-k3.1-pro` /
            `kimi-k3.1-pro-highspeed`는 이 필드를 자동으로 무시하며 `kimi-k3`는 지원하지 않는 값에 대해
            오류를 반환합니다.
    ResponsesResponse:
      type: object
      description: 모델 응답 하나입니다.
      properties:
        id:
          type: string
          description: 응답의 고유 식별자입니다.
          example: resp_68f0c1c2d3e4f5a6b7c8d9e0
        object:
          type: string
          enum:
            - response
        created_at:
          type: integer
          description: 응답 생성 시점의 Unix 타임스탬프입니다.
        completed_at:
          type:
            - integer
            - 'null'
          description: >-
            응답 종료 시점의 Unix 타임스탬프입니다. `status`가 `completed` 또는 `incomplete`이면
            제공되며 `in_progress` 또는 `failed`이면 `null`입니다.
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
            - failed
          description: 응답 상태입니다. 스트리밍 초기 스냅샷의 상태는 `in_progress`입니다.
        model:
          type: string
          description: 이번 응답을 생성한 모델입니다.
        output:
          type: array
          description: 출력 항목 배열로 web_search_call(있는 경우), reasoning, message, 도구 호출 순서입니다.
          items:
            $ref: '#/components/schemas/ResponsesOutputItem'
        usage:
          oneOf:
            - $ref: '#/components/schemas/ResponsesUsage'
            - type: 'null'
        incomplete_details:
          type:
            - object
            - 'null'
          description: '`status`가 `incomplete`일 때 제공되는 이유입니다.'
          properties:
            reason:
              type: string
              enum:
                - max_output_tokens
                - content_filter
        error:
          type:
            - object
            - 'null'
          description: '`status`가 `failed`일 때 제공되는 오류 정보입니다.'
          properties:
            code:
              type: string
            message:
              type: string
        instructions:
          type:
            - string
            - 'null'
        reasoning:
          type:
            - object
            - 'null'
        text:
          type:
            - object
            - 'null'
        tools:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ResponsesTool'
        tool_choice:
          oneOf:
            - $ref: '#/components/schemas/ResponsesToolChoice'
            - type: 'null'
        max_output_tokens:
          type:
            - integer
            - 'null'
        temperature:
          type:
            - number
            - 'null'
        top_p:
          type:
            - number
            - 'null'
        parallel_tool_calls:
          type: boolean
        service_tier:
          type:
            - string
            - 'null'
        store:
          type: boolean
          description: 항상 `false`입니다.
        background:
          type:
            - boolean
            - 'null'
          description: 항상 `false`입니다.
        previous_response_id:
          type:
            - string
            - 'null'
          description: 항상 `null`입니다.
        conversation:
          type:
            - object
            - 'null'
          description: 항상 `null`입니다.
        prompt_cache_options:
          type: object
          description: >-
            서버가 실제로 적용한 컨텍스트 캐시 쓰기 옵션입니다. prompt_cache_options를 생략한 경우 여기서 반환되는
            mode와 ttl을 기준으로 합니다.
          properties:
            mode:
              type: string
              enum:
                - implicit
              description: 실제로 적용된 쓰기 모드입니다.
            ttl:
              type: string
              enum:
                - 5m
                - 1h
              description: 실제로 적용된 캐시 유효 기간입니다.
    ResponsesStreamEvent:
      type: object
      description: >-
        `stream: true`일 때 반환되는 단일 SSE 이벤트입니다. 프레임은 `event: <type>`과 `data:
        <json>` 형식이며 나머지 필드는 `type`에 따라 달라집니다.
      required:
        - type
        - sequence_number
      properties:
        type:
          type: string
          enum:
            - response.created
            - response.in_progress
            - response.output_item.added
            - response.output_item.done
            - response.content_part.added
            - response.content_part.done
            - response.output_text.delta
            - response.output_text.done
            - response.reasoning_summary_part.added
            - response.reasoning_summary_part.done
            - response.reasoning_summary_text.delta
            - response.reasoning_summary_text.done
            - response.function_call_arguments.delta
            - response.function_call_arguments.done
            - response.custom_tool_call_input.delta
            - response.custom_tool_call_input.done
            - response.web_search_call.in_progress
            - response.web_search_call.searching
            - response.web_search_call.completed
            - response.completed
            - response.incomplete
            - response.failed
            - error
        sequence_number:
          type: integer
          description: 0부터 단조 증가하는 이벤트 순번입니다.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: 오류 원인을 설명하는 메시지입니다.
            type:
              type: string
              description: 오류 유형
            code:
              type: string
              description: 오류 코드
          required:
            - message
      required:
        - error
    ResponsesInputItem:
      description: input 배열의 요소로 `type`으로 구분합니다. `type` 생략 시 `message`로 처리합니다.
      oneOf:
        - $ref: '#/components/schemas/ResponsesMessageItem'
        - $ref: '#/components/schemas/ResponsesReasoningItem'
        - $ref: '#/components/schemas/ResponsesFunctionCallItem'
        - $ref: '#/components/schemas/ResponsesFunctionCallOutputItem'
        - $ref: '#/components/schemas/ResponsesCustomToolCallItem'
        - $ref: '#/components/schemas/ResponsesCustomToolCallOutputItem'
        - $ref: '#/components/schemas/ResponsesWebSearchCallItem'
        - $ref: '#/components/schemas/ResponsesAdditionalToolsItem'
    ResponsesTool:
      description: >-
        `type`으로 구분하는 도구 정의입니다. `function`, `custom`(`apply_patch`만),
        `namespace`, `web_search`를 지원하며 다른 유형은 지원하지 않습니다.
      oneOf:
        - $ref: '#/components/schemas/ResponsesFunctionTool'
        - $ref: '#/components/schemas/ResponsesCustomTool'
        - $ref: '#/components/schemas/ResponsesNamespaceTool'
        - $ref: '#/components/schemas/ResponsesWebSearchTool'
      discriminator:
        propertyName: type
        mapping:
          function: '#/components/schemas/ResponsesFunctionTool'
          custom: '#/components/schemas/ResponsesCustomTool'
          namespace: '#/components/schemas/ResponsesNamespaceTool'
          web_search: '#/components/schemas/ResponsesWebSearchTool'
    ResponsesToolChoice:
      type: string
      enum:
        - auto
      description: 도구 호출을 제어합니다. `auto`이면 모델이 도구 호출 여부를 결정합니다.
    ResponsesOutputItem:
      description: '`type`으로 구분하는 output 배열의 요소입니다.'
      oneOf:
        - $ref: '#/components/schemas/ResponsesOutputReasoningItem'
        - $ref: '#/components/schemas/ResponsesOutputMessageItem'
        - $ref: '#/components/schemas/ResponsesOutputFunctionCallItem'
        - $ref: '#/components/schemas/ResponsesOutputCustomToolCallItem'
        - $ref: '#/components/schemas/ResponsesOutputWebSearchCallItem'
      discriminator:
        propertyName: type
        mapping:
          reasoning: '#/components/schemas/ResponsesOutputReasoningItem'
          message: '#/components/schemas/ResponsesOutputMessageItem'
          function_call: '#/components/schemas/ResponsesOutputFunctionCallItem'
          custom_tool_call: '#/components/schemas/ResponsesOutputCustomToolCallItem'
          web_search_call: '#/components/schemas/ResponsesOutputWebSearchCallItem'
    ResponsesUsage:
      type: object
      description: >-
        input_tokens는 캐시 읽기와 쓰기를 포함합니다. K3.1 시리즈의 일반 입력은 cached_tokens와
        cache_write_tokens를 빼고, `kimi-k3`는 cached_tokens만 뺍니다. output_tokens에는
        추론이 이미 포함되어 있습니다.
      properties:
        input_tokens:
          type: integer
          description: 캐시 적중분을 포함한 입력 토큰 수입니다.
        input_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
              description: 컨텍스트 캐시에서 읽은 토큰 수입니다.
            cache_write_tokens:
              type: integer
              description: 컨텍스트 캐시에 기록한 토큰 수입니다.
        output_tokens:
          type: integer
          description: 추론 토큰을 포함한 출력 토큰 수입니다.
        output_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
              description: 추론에 사용한 토큰 수입니다.
        total_tokens:
          type: integer
          description: 총 토큰 수입니다.
    ResponsesMessageItem:
      type: object
      title: 메시지
      description: 대화 메시지입니다. `type`은 생략할 수 있습니다.
      required:
        - role
        - content
      properties:
        type:
          type: string
          enum:
            - message
        role:
          type: string
          enum:
            - user
            - assistant
            - developer
          description: 메시지 역할입니다. `developer`는 시스템 지시로 처리됩니다.
        content:
          description: 문자열 또는 콘텐츠 항목 배열 형식의 메시지 내용입니다.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputContentPart'
        status:
          type: string
          enum:
            - completed
    ResponsesReasoningItem:
      type: object
      title: 추론
      description: 이전 턴의 추론 내용을 재전송합니다. `content`가 `summary`보다 우선합니다.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - reasoning
        id:
          type: string
        summary:
          type: array
          items:
            type: object
            required:
              - type
              - text
            properties:
              type:
                type: string
                enum:
                  - summary_text
              text:
                type: string
        content:
          type: array
          items:
            type: object
            required:
              - type
              - text
            properties:
              type:
                type: string
                enum:
                  - reasoning_text
              text:
                type: string
        status:
          type: string
          enum:
            - completed
    ResponsesFunctionCallItem:
      type: object
      title: Function Call
      description: 함수 호출을 재전송합니다.
      required:
        - type
        - call_id
        - name
        - arguments
      properties:
        type:
          type: string
          enum:
            - function_call
        id:
          type: string
        call_id:
          type: string
          description: 해당 `function_call_output`과 연결되는 호출 ID입니다.
        name:
          type: string
        namespace:
          type: string
          description: 도구의 네임스페이스로 네임스페이스 도구 호출 시 반환됩니다.
        arguments:
          type: string
          description: JSON 문자열 형식의 함수 인수입니다.
        status:
          type: string
          enum:
            - completed
    ResponsesFunctionCallOutputItem:
      type: object
      title: 함수 호출 결과
      description: 함수 호출의 실행 결과입니다.
      required:
        - type
        - call_id
        - output
      properties:
        type:
          type: string
          enum:
            - function_call_output
        call_id:
          type: string
          description: 해당 `function_call`과 같은 호출 ID입니다.
        output:
          description: 도구가 반환한 내용입니다.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputContentPart'
        status:
          type: string
          enum:
            - completed
    ResponsesCustomToolCallItem:
      type: object
      title: 사용자 정의 도구 호출
      description: 사용자 정의 도구 호출을 재전송합니다.
      required:
        - type
        - call_id
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - custom_tool_call
        id:
          type: string
        call_id:
          type: string
          description: 해당 `custom_tool_call_output`과 연결되는 호출 ID입니다.
        name:
          type: string
        namespace:
          type: string
          description: 도구의 네임스페이스로 네임스페이스 도구 호출 시 반환됩니다.
        input:
          type: string
          description: 모델이 생성한 자유 형식 텍스트 입력입니다.
        status:
          type: string
          enum:
            - completed
    ResponsesCustomToolCallOutputItem:
      type: object
      title: 사용자 정의 도구 호출 결과
      description: 사용자 정의 도구 호출의 실행 결과입니다.
      required:
        - type
        - call_id
        - output
      properties:
        type:
          type: string
          enum:
            - custom_tool_call_output
        call_id:
          type: string
          description: 해당 `custom_tool_call`과 같은 호출 ID입니다.
        output:
          description: 도구가 반환한 내용입니다.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputContentPart'
        status:
          type: string
          enum:
            - completed
    ResponsesWebSearchCallItem:
      type: object
      title: 웹 검색 호출
      description: 이전 턴의 웹 검색 기록으로 전체 대화 기록과 함께 전달하세요.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - web_search_call
        id:
          type: string
        status:
          type: string
          enum:
            - completed
        action:
          type: object
          properties:
            type:
              type: string
              enum:
                - search
            query:
              type: string
    ResponsesAdditionalToolsItem:
      type: object
      title: 동적 도구
      description: 대화 도중 호출 가능한 도구를 추가합니다. 이 항목의 위치부터 적용됩니다.
      required:
        - type
        - role
        - tools
      properties:
        type:
          type: string
          enum:
            - additional_tools
        id:
          type: string
        role:
          type: string
          enum:
            - developer
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesTool'
    ResponsesFunctionTool:
      type: object
      title: 함수 도구
      description: JSON Schema로 매개변수를 정의하는 함수 도구입니다.
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - function
        name:
          type: string
          description: 함수 이름으로 정규식 ^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$를 따라야 합니다.
          pattern: ^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$
        description:
          type: string
        parameters:
          type: object
          description: 함수 매개변수를 정의하는 JSON Schema입니다.
        strict:
          type: boolean
    ResponsesCustomTool:
      type: object
      title: 사용자 정의 도구
      description: >-
        자유 형식 텍스트를 받는 사용자 정의 도구입니다. 현재 `apply_patch`만 지원하며 `grammar` + `lark` 형식
        정의가 필수입니다. 호출은 output의 `custom_tool_call` 항목으로 반환됩니다.
      required:
        - type
        - name
        - format
      properties:
        type:
          type: string
          enum:
            - custom
        name:
          type: string
          enum:
            - apply_patch
          description: 도구 이름으로 현재 `apply_patch`만 지원합니다.
        description:
          type: string
        format:
          type: object
          description: 입력 형식 제약입니다. `grammar` 유형과 `lark` 문법만 지원합니다.
          required:
            - type
            - syntax
            - definition
          properties:
            type:
              type: string
              enum:
                - grammar
            syntax:
              type: string
              enum:
                - lark
            definition:
              type: string
              description: Lark 문법 정의입니다.
    ResponsesNamespaceTool:
      type: object
      title: 네임스페이스 도구
      description: 함수 도구나 사용자 정의 도구를 하나의 네임스페이스로 묶습니다.
      required:
        - type
        - name
        - description
        - tools
      properties:
        type:
          type: string
          enum:
            - namespace
        name:
          type: string
        description:
          type: string
        tools:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/ResponsesFunctionTool'
              - $ref: '#/components/schemas/ResponsesCustomTool'
    ResponsesWebSearchTool:
      type: object
      title: 웹 검색 도구
      description: >-
        모델이 온라인 정보가 필요할 때 호출하는 웹 검색 도구입니다. 검색 기록은 web_search_call로 반환됩니다. 요청당 최대
        하나를 선언할 수 있습니다.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - web_search
        filters:
          type: object
          description: 검색 범위 필터입니다.
          properties:
            allowed_domains:
              type: array
              items:
                type: string
              maxItems: 100
              description: 지정한 도메인에서만 검색하며 최대 100개입니다.
        search_content_types:
          type: array
          items:
            type: string
            enum:
              - text
              - image
          default:
            - text
          description: 검색 결과 유형으로 기본값은 `text`만입니다. `image`를 포함하면 이미지 검색도 실행합니다.
        image_settings:
          type: object
          description: 이미지 검색 설정으로 `search_content_types`에 `image`가 포함된 경우에만 적용됩니다.
          properties:
            max_results:
              type: integer
              minimum: 1
              maximum: 10
              default: 3
              description: 반환할 최대 이미지 수입니다.
            caption:
              type: boolean
              default: false
              description: 이미지 설명을 생성할지 여부입니다.
    ResponsesOutputReasoningItem:
      type: object
      title: 추론
      description: 모델의 추론 내용입니다.
      properties:
        type:
          type: string
          enum:
            - reasoning
        id:
          type: string
          example: rs_68f0c1c2d3e4f5a6b7c8d9e0
        summary:
          type: array
          description: 추론 내용입니다.
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - summary_text
              text:
                type: string
        encrypted_content:
          type:
            - string
            - 'null'
          description: 항상 `null`입니다.
        status:
          type: string
          enum:
            - in_progress
            - completed
    ResponsesOutputMessageItem:
      type: object
      title: 메시지
      description: 모델의 텍스트 답변입니다.
      properties:
        type:
          type: string
          enum:
            - message
        id:
          type: string
          example: msg_68f0c1c2d3e4f5a6b7c8d9e0
        role:
          type: string
          enum:
            - assistant
        content:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - output_text
              text:
                type: string
              annotations:
                type: array
                items: {}
        status:
          type: string
          enum:
            - in_progress
            - completed
    ResponsesOutputFunctionCallItem:
      type: object
      title: Function Call
      description: 모델이 요청한 함수 호출입니다.
      properties:
        type:
          type: string
          enum:
            - function_call
        id:
          type: string
          example: fc_68f0c1c2d3e4f5a6b7c8d9e0
        call_id:
          type: string
          description: 결과를 돌려줄 때 `function_call_output`에 이 값을 사용하세요.
        name:
          type: string
        namespace:
          type: string
          description: 네임스페이스 도구 호출 시 반환됩니다.
        arguments:
          type: string
          description: JSON 문자열 형식의 함수 인수입니다.
        status:
          type: string
          enum:
            - in_progress
            - completed
    ResponsesOutputCustomToolCallItem:
      type: object
      title: 사용자 정의 도구 호출
      description: 모델이 요청한 사용자 정의 도구 호출입니다.
      properties:
        type:
          type: string
          enum:
            - custom_tool_call
        id:
          type: string
          example: ctc_68f0c1c2d3e4f5a6b7c8d9e0
        call_id:
          type: string
          description: 결과를 돌려줄 때 `custom_tool_call_output`에 이 값을 사용하세요.
        name:
          type: string
        namespace:
          type: string
          description: 네임스페이스 도구 호출 시 반환됩니다.
        input:
          type: string
          description: 모델이 생성한 자유 형식 텍스트 입력입니다.
        status:
          type: string
          enum:
            - in_progress
            - completed
    ResponsesOutputWebSearchCallItem:
      type: object
      title: 웹 검색 호출
      description: >-
        서버 측 웹 검색 호출입니다. 요청에 `web_search`가 있고 서버가 검색이 필요하다고 판단한 경우에만 output 배열의
        맨 앞에 반환됩니다.
      properties:
        type:
          type: string
          enum:
            - web_search_call
        id:
          type: string
          example: ws_68f0c1c2d3e4f5a6b7c8d9e0
        status:
          type: string
          enum:
            - in_progress
            - completed
        action:
          type: object
          description: 이번 검색에서 수행한 작업입니다.
          properties:
            type:
              type: string
              enum:
                - search
            query:
              type: string
              description: 실제로 사용한 검색어입니다.
            sources:
              type: array
              description: >-
                검색된 웹 출처입니다. `include`에 `web_search_call.action.sources`가 있을 때만
                반환됩니다.
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - url
                  url:
                    type: string
                  title:
                    type: string
        results:
          type: array
          description: >-
            이미지 검색 결과입니다. `include`에 `web_search_call.results`가 있고
            `search_content_types`에 `image`가 있을 때만 반환됩니다.
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - image_result
              image_url:
                type: string
              thumbnail_url:
                type: string
              source_website_url:
                type: string
              caption:
                type: string
                description: 이미지 설명으로 `image_settings.caption`을 켠 경우에만 반환됩니다.
    ResponsesInputContentPart:
      description: '`type`으로 구분하는 content 배열의 요소입니다.'
      oneOf:
        - type: object
          title: 입력 텍스트
          required:
            - type
            - text
          properties:
            type:
              type: string
              enum:
                - input_text
            text:
              type: string
        - type: object
          title: 입력 이미지
          required:
            - type
            - image_url
          properties:
            type:
              type: string
              enum:
                - input_image
            image_url:
              type: string
              description: >-
                이미지 data URL(예: `data:image/png;base64,<base64>`)입니다. 공개 http(s)
                URL은 지원하지 않습니다.
            detail:
              type: string
              enum:
                - auto
                - low
                - high
                - original
        - type: object
          title: 출력 텍스트
          description: assistant 텍스트 기록을 재전송할 때 사용합니다.
          required:
            - type
            - text
          properties:
            type:
              type: string
              enum:
                - output_text
            text:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        ##모든 API에는 Bearer Token 인증이 필요합니다##

        **API Key 발급:**

        [API Key 관리 페이지](https://evolink.ai/dashboard/keys)에서 API Key를 발급받으세요

        **요청 헤더에 추가:**
        ```
        Authorization: Bearer YOUR_API_KEY
        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.