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

# DeepSeek V4 - Responses 인터페이스

> - OpenAI Responses 프로토콜로 DeepSeek V4 모델을 호출합니다
- `deepseek-v4-flash`(빠른 범용)와 `deepseek-v4-pro`(심층 추론) 두 모델을 지원합니다
- **입력 형태**: `input`은 일반 텍스트일 수도 있고, 입력 항목 배열(메시지, 함수 호출, 함수 결과, 사고, 검색 기록)일 수도 있습니다
- **시스템 지시**: `instructions`로 전달하며, 맨 앞의 system 메시지와 동일합니다
- **사고 모드**: `reasoning.effort`로 추론 강도를 제어하며, 사고 내용은 `reasoning` 출력 항목으로 반환됩니다
- **스트리밍 출력**: 시맨틱 SSE 이벤트를 지원하며 `response.completed`로 종료되고, **`[DONE]`은 전송되지 않습니다**
- **도구 호출**: Function Calling과 내장 `web_search` 웹 검색을 지원합니다
- **구조화 출력**: `text.format`으로 JSON 객체 또는 JSON Schema를 활성화합니다
- **컨텍스트 캐시**: 동일한 접두사를 가진 요청은 자동으로 캐시에 적중하여 입력 비용을 크게 낮춥니다

**스트리밍 이벤트**: `response.created`, `response.output_item.added`, `response.reasoning_text.delta`, `response.output_text.delta`이며, 종료 이벤트는 `response.completed` / `response.incomplete` / `response.failed`입니다. 모든 이벤트에는 정렬용 `sequence_number`가 포함됩니다.

**효과가 없는 필드**: 다음 OpenAI 필드는 그대로 전송해도 오류가 발생하지 않지만 실제 효과는 없습니다.

| 필드 | 동작 |
| --- | --- |
| `store` | 항상 `false`이며 응답을 저장하지 않습니다 |
| `previous_response_id` | 항상 `null`이며 대화 이어가기를 지원하지 않습니다 |
| `conversation` | 미지원 |
| `background` / `metadata` / `include` | 무시 |
| `prompt` / `truncation` / `service_tier` | 무시 |
| `safety_identifier` / `context_management` | 무시 |
| `stream_options` | 무시 |
| `parallel_tool_calls` | 무시되며 병렬 도구 호출은 항상 활성화됩니다 |
| `max_tool_calls` | 무시 |
| `file_search` / `code_interpreter` / `mcp` 도구 | 무시 |

**기타 제한**:
- 커스텀 도구(`type: custom`)는 `apply_patch`만 지원합니다
- `web_search` 도구는 `search_context_size`와 `user_location`을 무시합니다
- 이미지와 파일 콘텐츠 블록은 플레이스홀더로 변환됩니다. DeepSeek V4는 비전 모델이 아닙니다
- 입력이 컨텍스트 윈도우를 초과하면 400을 반환하며 자동 절단은 수행하지 않습니다

<Note>
  **BaseURL**: 기본 BaseURL은 `https://direct.evolink.ai`이며, 텍스트 모델 지원이 더 우수하고 장시간 연결을 지원합니다. `https://api.evolink.ai`는 멀티모달 서비스의 주력 엔드포인트이며, 텍스트 모델에 대해서는 대체 주소로 사용됩니다.
</Note>


## OpenAPI

````yaml ko/api-manual/language-series/deepseek-v4/deepseek-v4-responses.json POST /v1/responses
openapi: 3.1.0
info:
  title: DeepSeek V4 전체 파라미터 문서 (Responses API)
  description: >-
    DeepSeek V4 시리즈 Responses 인터페이스(`deepseek-v4-flash` / `deepseek-v4-pro`)의 전체
    API 레퍼런스입니다.


    **모델 성능**:

    - 컨텍스트 길이: **1,000,000 tokens**(1M)

    - 최대 출력: **384,000 tokens**(384K)

    - 사고 모드: `reasoning.effort`로 추론 강도를 제어하며, `deepseek-v4-pro`는 복잡한 추론에 강합니다

    - 컨텍스트 디스크 캐시: 자동 적중하며 적중과 미적중은 각각 별도로 과금됩니다

    - 내장 웹 검색: `web_search` 도구는 서버 측에서 실행되며 클라이언트 개입이 필요 없습니다


    **프로토콜 설명**: 본 인터페이스는 OpenAI Responses API 프로토콜과 완전히 호환됩니다. 요청 본문은 그대로 유지되며
    필드 재정렬이나 제거를 하지 않으므로, 선언되지 않은 확장 필드와 캐시 접두사는 영향을 받지 않습니다.


    **무상태**: DeepSeek Responses는 어떤 세션도 저장하지 않으므로, 멀티턴 대화에서는 클라이언트가 매번 전체 히스토리를
    전송해야 합니다.


    **과금 단가(UC/1K tokens, EvoLink 내부 단위)**:

    | 모델 | 입력 캐시 적중 | 입력 캐시 미적중 | 출력 |

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

    | deepseek-v4-flash | 2 | 100 | 200 |

    | deepseek-v4-pro | 3 | 300 | 600 |
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: 프로덕션 (권장)
  - url: https://api.evolink.ai
    description: 대체 URL
security:
  - bearerAuth: []
tags:
  - name: 채팅 생성
    description: AI 채팅 생성 관련 인터페이스
paths:
  /v1/responses:
    post:
      tags:
        - 채팅 생성
      summary: DeepSeek V4 Responses 인터페이스(OpenAI 호환)
      description: >-
        - OpenAI Responses 프로토콜로 DeepSeek V4 모델을 호출합니다

        - `deepseek-v4-flash`(빠른 범용)와 `deepseek-v4-pro`(심층 추론) 두 모델을 지원합니다

        - **입력 형태**: `input`은 일반 텍스트일 수도 있고, 입력 항목 배열(메시지, 함수 호출, 함수 결과, 사고, 검색
        기록)일 수도 있습니다

        - **시스템 지시**: `instructions`로 전달하며, 맨 앞의 system 메시지와 동일합니다

        - **사고 모드**: `reasoning.effort`로 추론 강도를 제어하며, 사고 내용은 `reasoning` 출력 항목으로
        반환됩니다

        - **스트리밍 출력**: 시맨틱 SSE 이벤트를 지원하며 `response.completed`로 종료되고, **`[DONE]`은
        전송되지 않습니다**

        - **도구 호출**: Function Calling과 내장 `web_search` 웹 검색을 지원합니다

        - **구조화 출력**: `text.format`으로 JSON 객체 또는 JSON Schema를 활성화합니다

        - **컨텍스트 캐시**: 동일한 접두사를 가진 요청은 자동으로 캐시에 적중하여 입력 비용을 크게 낮춥니다


        **스트리밍 이벤트**: `response.created`, `response.output_item.added`,
        `response.reasoning_text.delta`, `response.output_text.delta`이며, 종료 이벤트는
        `response.completed` / `response.incomplete` / `response.failed`입니다. 모든
        이벤트에는 정렬용 `sequence_number`가 포함됩니다.


        **효과가 없는 필드**: 다음 OpenAI 필드는 그대로 전송해도 오류가 발생하지 않지만 실제 효과는 없습니다.


        | 필드 | 동작 |

        | --- | --- |

        | `store` | 항상 `false`이며 응답을 저장하지 않습니다 |

        | `previous_response_id` | 항상 `null`이며 대화 이어가기를 지원하지 않습니다 |

        | `conversation` | 미지원 |

        | `background` / `metadata` / `include` | 무시 |

        | `prompt` / `truncation` / `service_tier` | 무시 |

        | `safety_identifier` / `context_management` | 무시 |

        | `stream_options` | 무시 |

        | `parallel_tool_calls` | 무시되며 병렬 도구 호출은 항상 활성화됩니다 |

        | `max_tool_calls` | 무시 |

        | `file_search` / `code_interpreter` / `mcp` 도구 | 무시 |


        **기타 제한**:

        - 커스텀 도구(`type: custom`)는 `apply_patch`만 지원합니다

        - `web_search` 도구는 `search_context_size`와 `user_location`을 무시합니다

        - 이미지와 파일 콘텐츠 블록은 플레이스홀더로 변환됩니다. DeepSeek V4는 비전 모델이 아닙니다

        - 입력이 컨텍스트 윈도우를 초과하면 400을 반환하며 자동 절단은 수행하지 않습니다
      operationId: createResponseDeepSeekV4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
            examples:
              simple_text:
                summary: 싱글턴 텍스트 대화 (Flash)
                value:
                  model: deepseek-v4-flash
                  input: 항저우를 한 문장으로 소개해 주세요.
              with_instructions:
                summary: 시스템 지시 사용
                value:
                  model: deepseek-v4-flash
                  instructions: 당신은 꼼꼼한 기술 문서 작성자입니다. 답변은 간결하게 유지하세요.
                  input: 컨텍스트 캐시가 무엇인지 설명해 주세요.
              multi_turn:
                summary: 멀티턴 대화 (입력 항목 배열)
                value:
                  model: deepseek-v4-flash
                  input:
                    - type: message
                      role: user
                      content: 제품 이름 세 개를 제안해 주세요.
                    - type: message
                      role: assistant
                      content: 윈치, 계명, 영풍.
                    - type: message
                      role: user
                      content: 두 번째 이름의 유의어 다섯 개를 알려 주세요.
              reasoning_effort:
                summary: Pro 모델 + 고강도 추론 사용
                value:
                  model: deepseek-v4-pro
                  input: >-
                    수영장에 급수관과 배수관이 있습니다. 급수관은 3시간이면 가득 채우고 배수관은 5시간이면 모두 비웁니다. 두
                    관을 동시에 열면 채우는 데 얼마나 걸리나요? 풀이 과정도 함께 제시해 주세요.
                  reasoning:
                    effort: high
              disable_thinking:
                summary: 사고 비활성화 (직접 답변만)
                value:
                  model: deepseek-v4-flash
                  input: 베이징에서 상하이까지 고속철도로 대략 얼마나 걸리나요?
                  reasoning:
                    effort: none
              json_schema:
                summary: 구조화 출력 (JSON Schema)
                value:
                  model: deepseek-v4-flash
                  input: '다음 문장에서 인물과 도시를 추출하세요: 장웨이는 다음 주에 청두로 출장을 갑니다.'
                  text:
                    format:
                      type: json_schema
                      name: extraction
                      schema:
                        type: object
                        properties:
                          person:
                            type: string
                          city:
                            type: string
                        required:
                          - person
                          - city
              function_calling:
                summary: Function Calling 도구 호출
                value:
                  model: deepseek-v4-flash
                  input: 지금 항저우 날씨는 어떤가요?
                  tools:
                    - type: function
                      name: get_weather
                      description: 지정한 도시의 실시간 날씨를 조회합니다
                      parameters:
                        type: object
                        properties:
                          city:
                            type: string
                            description: 도시 이름
                        required:
                          - city
                  tool_choice: auto
              web_search:
                summary: 내장 웹 검색 (서버 측 실행)
                value:
                  model: deepseek-v4-flash
                  input: 이번 주 인공지능 분야의 주요 뉴스를 정리해 주세요.
                  tools:
                    - type: web_search
              streaming:
                summary: 스트리밍 출력
                value:
                  model: deepseek-v4-flash
                  input: 가을에 관한 짧은 시를 써 주세요.
                  stream: true
      responses:
        '200':
          description: 생성 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
              example:
                id: resp_9f2c1a4b8e7d
                object: response
                created_at: 1755000000
                status: completed
                model: deepseek-v4-flash
                output:
                  - id: rs_2b7f
                    type: reasoning
                    summary: []
                    content:
                      - type: reasoning_text
                        text: 사용자는 한 문장 소개를 원하며, 지리와 인문 두 가지 요점을 담아야 한다.
                  - id: msg_5d1a
                    type: message
                    role: assistant
                    status: completed
                    content:
                      - type: output_text
                        text: 항저우는 저장성의 성도로, 시후의 경관과 디지털 경제로 유명합니다.
                        annotations: []
                error: null
                incomplete_details: null
                usage:
                  input_tokens: 694
                  input_tokens_details:
                    cached_tokens: 640
                  output_tokens: 20
                  output_tokens_details:
                    reasoning_tokens: 10
                  total_tokens: 714
        '400':
          description: 요청 매개변수 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 400
                  message: Invalid request parameters
                  type: invalid_request_error
        '401':
          description: 인증되지 않음, 유효하지 않거나 만료된 토큰
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid authentication credentials
                  type: authentication_error
        '402':
          description: 할당량 부족, 충전 필요
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 402
                  message: Insufficient quota
                  type: insufficient_quota
        '403':
          description: 해당 모델에 대한 접근 권한 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 403
                  message: Model access denied
                  type: permission_error
        '404':
          description: 리소스를 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 404
                  message: Model not found
                  type: not_found_error
        '413':
          description: 요청 본문이 너무 큼
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 413
                  message: Request entity too large
                  type: invalid_request_error
        '429':
          description: 요청 빈도 초과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  type: rate_limit_error
        '500':
          description: 내부 서버 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 500
                  message: Internal server error
                  type: server_error
        '502':
          description: 게이트웨이 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 502
                  message: Bad gateway
                  type: server_error
        '503':
          description: 서비스 일시적으로 사용 불가
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 503
                  message: Service temporarily unavailable
                  type: server_error
components:
  schemas:
    ResponsesRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
          description: |-
            모델 ID

            - `deepseek-v4-flash`: 빠른 범용 모델로 일상 대화, 요약, 추출에 적합합니다
            - `deepseek-v4-pro`: 심층 추론 모델로 복잡한 수학, 코드, 다단계 계획에 적합합니다
          enum:
            - deepseek-v4-flash
            - deepseek-v4-pro
          default: deepseek-v4-flash
          example: deepseek-v4-flash
        input:
          type:
            - string
            - array
          description: >-
            모델 입력입니다. `input`과 `instructions` 중 최소 하나는 제공해야 합니다.


            - **문자열 형태**: 전체 텍스트가 하나의 `user` 메시지로 처리됩니다

            - **배열 형태**: 입력 항목 목록으로 `message`, `function_call`,
            `function_call_output`, `reasoning`, `web_search_call` 다섯 가지 유형을
            지원합니다


            **멀티턴 대화**: 본 인터페이스는 무상태이므로 대화를 이어가려면 전체 히스토리를 배열에 담아야 합니다.
          items:
            $ref: '#/components/schemas/InputItem'
          example: 항저우를 한 문장으로 소개해 주세요.
        instructions:
          type: string
          description: 시스템 수준 지시로, 맨 앞에 삽입되는 system 메시지와 동일하며 역할, 어조, 출력 제약을 설정하는 데 사용합니다.
          example: 당신은 꼼꼼한 기술 문서 작성자입니다. 답변은 간결하게 유지하세요.
        stream:
          type: boolean
          description: >-
            스트리밍 반환 여부


            - `false`(기본값): 완전한 응답 객체를 한 번에 반환합니다

            - `true`: 시맨틱 SSE 이벤트로 전송하며, 마지막 이벤트는 `response.completed` /
            `response.incomplete` / `response.failed`이고 **`[DONE]`은 전송되지 않습니다**
          default: false
          example: false
        max_output_tokens:
          type: integer
          description: >-
            이번 생성의 최대 출력 토큰 수(사고 토큰 포함)입니다. 범위는 1 ~ 393216(384K)이며, 비워 두면 모델이
            스스로 결정합니다.
          minimum: 1
          maximum: 393216
          example: 4096
        temperature:
          type: number
          description: 샘플링 온도로, 값이 클수록 출력이 무작위해집니다. **사고 모드에서는 적용되지 않습니다.**
          minimum: 0
          maximum: 2
          default: 1
          example: 1
        top_p:
          type: number
          description: >-
            뉴클리어스 샘플링 임계값으로, `temperature`와 둘 중 하나만 조정하기를 권장합니다. **사고 모드에서는 적용되지
            않습니다.**
          maximum: 1
          default: 1
          example: 1
        top_logprobs:
          type: integer
          description: 각 위치에서 확률이 가장 높은 후보 토큰과 그 로그 확률을 반환합니다.
          minimum: 0
          maximum: 20
          example: 0
        reasoning:
          type: object
          description: >-
            사고 모드 설정입니다. DeepSeek V4는 기본적으로 사고가 활성화되어 있으며, 사고 내용은 `reasoning` 출력
            항목으로 반환되고 해당 토큰은 출력에 포함되어 출력 단가로 과금됩니다.
          properties:
            effort:
              type: string
              description: |-
                추론 강도

                - `none`: 사고를 끄고 바로 답변합니다
                - `minimal` / `low` / `medium`: 낮은 강도
                - `high`(기본값): 일반적인 심층 추론
                - `xhigh` / `max`: 최고 강도로, 소요 시간과 출력 토큰이 크게 늘어납니다
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
                - max
              default: high
              example: high
            max_output_tokens:
              type:
                - integer
                - 'null'
              description: 사고 단계의 출력 토큰 상한이며, 비워 두면 추가 제한이 없습니다.
            summary:
              type: string
              description: 전달할 수 있지만 사고 요약은 생성되지 않으므로 이 필드는 실제 효과가 없습니다.
        text:
          type: object
          description: 텍스트 출력 형식 설정입니다.
          properties:
            format:
              type: object
              description: >-
                출력 형식


                - `text`(기본값): 자유 형식 텍스트

                - `json_object`: 유효한 JSON 객체를 출력하며, **프롬프트에 JSON이라는 단어가 포함되어야
                합니다**

                - `json_schema`: 지정한 JSON Schema에 따라 출력하며, `name`과 `schema`를 함께
                제공해야 합니다
              properties:
                type:
                  type: string
                  enum:
                    - text
                    - json_object
                    - json_schema
                  default: text
                  description: 출력 형식 유형
                name:
                  type: string
                  description: Schema 이름이며 `json_schema` 모드에서는 필수입니다
                schema:
                  type: object
                  description: JSON Schema 정의이며 `json_schema` 모드에서는 필수입니다
                strict:
                  type: boolean
                  description: Schema를 엄격히 따를지 여부
        tools:
          type: array
          description: >-
            모델이 호출할 수 있는 도구 목록입니다. 함수 도구는 클라이언트가 실행하고 결과를
            `function_call_output`으로 반환하며, `web_search`는 서버 측에서 직접 실행되어 클라이언트
            개입이 필요 없습니다.
          items:
            $ref: '#/components/schemas/Tool'
        tool_choice:
          type:
            - string
            - object
          description: |-
            도구 호출 전략

            - `none`: 도구 호출 금지
            - `auto`(기본값): 모델이 결정
            - `required`: 최소 하나의 도구를 반드시 호출
            - `{"type": "function", "name": "get_weather"}`: 지정한 함수를 강제로 호출
            - `{"type": "web_search"}`: 웹 검색을 강제로 실행
          example: auto
    ResponsesResponse:
      type: object
      description: Responses 인터페이스의 응답 객체입니다.
      properties:
        id:
          type: string
          description: 이번 응답의 고유 식별자
          example: resp_9f2c1a4b8e7d
        object:
          type: string
          description: 객체 유형이며 항상 `response`
          example: response
        created_at:
          type: integer
          description: 생성 시각(Unix 타임스탬프, 초)
          example: 1755000000
        status:
          type: string
          description: |-
            응답 상태

            - `completed`: 정상 완료
            - `in_progress`: 생성 중
            - `incomplete`: 길이 등의 이유로 잘림. 자세한 내용은 `incomplete_details` 참조
            - `failed`: 생성 실패. 자세한 내용은 `error` 참조
          enum:
            - in_progress
            - completed
            - incomplete
            - failed
          example: completed
        model:
          type: string
          description: 실제로 이번 응답을 생성한 모델 ID
          example: deepseek-v4-flash
        output:
          type: array
          description: >-
            생성 순서대로 나열된 출력 항목 목록입니다. 유형별 필드:


            - `reasoning`: 사고 과정이며 `id`, `status`, `content`(`reasoning_text` 블록
            목록), `summary`를 포함합니다

            - `message`: 최종 답변이며 `id`, `status`, `role`, `content`(`output_text`
            블록 목록)를 포함합니다

            - `function_call`: 모델이 발생시킨 함수 호출이며 `id`, `status`, `call_id`,
            `name`, `arguments`를 포함하고, 클라이언트가 실행한 뒤 `function_call_output`으로
            반환합니다

            - `web_search_call`: 서버 측에서 실행된 웹 검색 기록이며 `id`, `status`,
            `action`(수행된 검색 내용)을 포함합니다
          items:
            type: object
        error:
          type:
            - object
            - 'null'
          description: 실패 원인이며 성공 시에는 `null`
        incomplete_details:
          type:
            - object
            - 'null'
          description: 잘림 원인이며 잘리지 않았을 때는 `null`
        usage:
          $ref: '#/components/schemas/Usage'
    ErrorResponse:
      type: object
      description: 오류 응답
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP 상태 코드
              example: 400
            message:
              type: string
              description: 오류 설명
              example: Invalid request parameters
            type:
              type: string
              description: 오류 유형
              example: invalid_request_error
    InputItem:
      type: object
      title: 입력 항목
      description: '`input` 배열의 단일 입력 항목입니다. `type`이 해당 항목의 의미를 결정합니다.'
      required:
        - type
      properties:
        type:
          type: string
          description: |-
            입력 항목 유형

            - `message`: 대화 메시지 한 건
            - `function_call`: 히스토리에서 모델이 발생시킨 함수 호출
            - `function_call_output`: 함수 실행 결과
            - `reasoning`: 이전 사고 내용
            - `web_search_call`: 이전 웹 검색 기록
          enum:
            - message
            - function_call
            - function_call_output
            - reasoning
            - web_search_call
          example: message
        role:
          type: string
          description: '메시지 역할이며 `type: message`에서만 사용합니다. `developer`는 `system`으로 처리됩니다.'
          enum:
            - user
            - assistant
            - system
            - developer
          example: user
        content:
          type:
            - string
            - array
          description: >-
            메시지 내용이며 `type: message`에서만 사용합니다. 일반 텍스트일 수도 있고 콘텐츠 블록 배열일 수도 있으며,
            입력 측 블록 유형은 `input_text`입니다. **`input_image` 등 이미지·파일 블록은 오류를 일으키지
            않지만 플레이스홀더 텍스트로 대체됩니다**. DeepSeek V4에는 비전 능력이 없습니다.
          example: 항저우를 한 문장으로 소개해 주세요.
        call_id:
          type: string
          description: 함수 호출 식별자이며 `function_call`과 `function_call_output`이 이를 통해 짝을 이룹니다.
        name:
          type: string
          description: '호출된 함수 이름이며 `type: function_call`에서만 사용합니다.'
        arguments:
          type: string
          description: '함수 호출 인자(JSON 문자열)이며 `type: function_call`에서만 사용합니다.'
        output:
          type: string
          description: '함수 실행 결과이며 `type: function_call_output`에서만 사용합니다.'
    Tool:
      type: object
      title: 도구 정의
      required:
        - type
      properties:
        type:
          type: string
          description: >-
            도구 유형


            - `function`: 클라이언트가 실행하는 커스텀 함수

            - `web_search` / `web_search_2025_08_26`: 서버 측에서 실행되는 웹 검색이며
            `search_context_size`와 `user_location`은 무시됩니다

            - `custom`: `apply_patch`만 지원


            `file_search`, `code_interpreter`, `mcp`는 무시됩니다.
          enum:
            - function
            - web_search
            - web_search_2025_08_26
            - custom
          example: function
        name:
          type: string
          description: 도구 이름이며 최대 128자, 영문자·숫자·`-`·`_`만 허용되고 같은 요청 내에서 중복할 수 없습니다.
          maxLength: 128
          example: get_weather
        description:
          type: string
          description: 도구의 용도 설명입니다. 명확하게 작성하면 모델이 호출 시점을 판단하는 데 도움이 됩니다.
          example: 지정한 도시의 실시간 날씨를 조회합니다
        parameters:
          type: object
          description: 파라미터 정의(JSON Schema 형식)입니다.
          example:
            type: object
            properties:
              city:
                type: string
                description: 도시 이름
            required:
              - city
    Usage:
      type: object
      description: 토큰 사용 통계(캐시 및 추론 세부 항목 포함)
      properties:
        input_tokens:
          type: integer
          description: 입력 토큰 총수(캐시 적중과 미적중 포함)
          example: 694
        input_tokens_details:
          type: object
          description: 입력 토큰 세부 항목
          properties:
            cached_tokens:
              type: integer
              description: >-
                컨텍스트 캐시에 적중한 토큰 수


                **설명**: 적중 부분은 **캐시 적중 단가**(Flash 2 UC/1K, Pro 3 UC/1K)로 과금되고,
                미적중 부분은 `input_tokens - cached_tokens`이며 **표준 입력 단가**(Flash 100
                UC/1K, Pro 300 UC/1K)로 과금됩니다
              example: 640
        output_tokens:
          type: integer
          description: 출력 토큰 수(사고 부분 포함)
          example: 20
        output_tokens_details:
          type: object
          description: 출력 토큰 세부 항목
          properties:
            reasoning_tokens:
              type: integer
              description: 사고 모드에서 생성된 추론 토큰 수(출력에 포함되어 출력 단가로 과금됩니다)
              example: 10
        total_tokens:
          type: integer
          description: 총 토큰 수 = input_tokens + output_tokens
          example: 714
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        ##모든 인터페이스는 Bearer Token 인증이 필요합니다##

        **API Key 받기**:

        [API Key 관리 페이지](https://evolink.ai/dashboard/keys)를 방문하여 API Key를 받으세요

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

````