> ## 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 - OpenAI 호환 인터페이스

> - OpenAI Chat Completions 프로토콜로 DeepSeek V4 모델 호출
- `deepseek-v4-flash`(빠른 범용)와 `deepseek-v4-pro`(심층 추론) 두 모델 지원
- **순수 텍스트 대화**: 단일 또는 다중 턴 컨텍스트 대화, 1M 초장문 컨텍스트 지원
- **시스템 프롬프트**: AI의 역할 및 동작 사용자 정의
- **사고 모드**: `thinking.type`으로 심층 추론 제어; `deepseek-v4-pro`의 사고 내용은 `reasoning_content`로 반환
- **스트리밍 출력**: SSE 스트림 반환 지원
- **도구 호출**: Function Calling 지원 (최대 128개 도구)
- **JSON 모드**: `response_format`으로 활성화
- **컨텍스트 캐시**: 동일한 접두사 요청은 자동으로 캐시 히트하여 입력 비용을 대폭 절감

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


## OpenAPI

````yaml ko/api-manual/language-series/deepseek-v4/deepseek-v4-chat.json POST /v1/chat/completions
openapi: 3.1.0
info:
  title: DeepSeek V4 전체 매개변수 문서 (OpenAI 호환)
  description: >-
    DeepSeek V4 시리즈 채팅 인터페이스(`deepseek-v4-flash` / `deepseek-v4-pro`)의 전체 API
    레퍼런스입니다.


    **모델 기능**:

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

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

    - 사고 모드: `thinking` 필드로 전환, `deepseek-v4-pro`는 복잡한 추론에 능숙

    - 컨텍스트 하드디스크 캐시: 자동 히트, 히트와 미스를 각각 과금


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

    | 모델 | 입력 캐시 히트 | 입력 캐시 미스 | 출력 |

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

    | deepseek-v4-flash | 20 | 100 | 200 |

    | deepseek-v4-pro | 100 | 1200 | 2400 |
  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/chat/completions:
    post:
      tags:
        - 채팅 생성
      summary: DeepSeek V4 채팅 인터페이스 (OpenAI 호환)
      description: >-
        - OpenAI Chat Completions 프로토콜로 DeepSeek V4 모델 호출

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

        - **순수 텍스트 대화**: 단일 또는 다중 턴 컨텍스트 대화, 1M 초장문 컨텍스트 지원

        - **시스템 프롬프트**: AI의 역할 및 동작 사용자 정의

        - **사고 모드**: `thinking.type`으로 심층 추론 제어; `deepseek-v4-pro`의 사고 내용은
        `reasoning_content`로 반환

        - **스트리밍 출력**: SSE 스트림 반환 지원

        - **도구 호출**: Function Calling 지원 (최대 128개 도구)

        - **JSON 모드**: `response_format`으로 활성화

        - **컨텍스트 캐시**: 동일한 접두사 요청은 자동으로 캐시 히트하여 입력 비용을 대폭 절감
      operationId: createChatCompletionDeepSeekV4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              simple_text:
                summary: 단일 턴 텍스트 대화 (Flash)
                value:
                  model: deepseek-v4-flash
                  messages:
                    - role: user
                      content: 자기소개를 해주세요
              multi_turn:
                summary: 다중 턴 대화 (컨텍스트 이해)
                value:
                  model: deepseek-v4-flash
                  messages:
                    - role: user
                      content: Python이란 무엇인가요?
                    - role: assistant
                      content: Python은 고급 프로그래밍 언어입니다...
                    - role: user
                      content: 어떤 장점이 있나요?
              system_prompt:
                summary: 시스템 프롬프트 사용
                value:
                  model: deepseek-v4-flash
                  messages:
                    - role: system
                      content: 당신은 전문 Python 프로그래밍 어시스턴트입니다. 간결한 언어로 질문에 답하세요.
                    - role: user
                      content: 파일을 어떻게 읽나요?
              thinking_mode:
                summary: Pro 모델 사용 + 사고 모드 명시적 활성화
                value:
                  model: deepseek-v4-pro
                  thinking:
                    type: enabled
                    reasoning_effort: high
                  messages:
                    - role: user
                      content: √2가 무리수임을 증명하세요
              disable_thinking:
                summary: 사고 모드 비활성화 (직접 응답만)
                value:
                  model: deepseek-v4-pro
                  thinking:
                    type: disabled
                  messages:
                    - role: user
                      content: 프랑스의 수도는 어디인가요?
              json_mode:
                summary: JSON 모드 구조화 출력
                value:
                  model: deepseek-v4-flash
                  response_format:
                    type: json_object
                  messages:
                    - role: system
                      content: 엄격한 JSON을 출력해야 합니다.
                    - role: user
                      content: name과 age 필드를 포함한 예시 JSON을 주세요
              tool_calling:
                summary: Function Calling 도구 호출
                value:
                  model: deepseek-v4-flash
                  messages:
                    - role: user
                      content: 오늘 베이징의 날씨를 조회해주세요
                  tools:
                    - type: function
                      function:
                        name: get_weather
                        description: 지정된 도시의 날씨 정보를 조회합니다
                        parameters:
                          type: object
                          properties:
                            city:
                              type: string
                              description: 도시 이름
                          required:
                            - city
                  tool_choice: auto
              streaming:
                summary: 스트리밍 출력
                value:
                  model: deepseek-v4-flash
                  stream: true
                  stream_options:
                    include_usage: true
                  messages:
                    - role: user
                      content: 봄에 관한 짧은 시를 써주세요
      responses:
        '200':
          description: 채팅 생성 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
              examples:
                thinking_disabled:
                  summary: thinking 비활성화 (순수 텍스트 응답)
                  value:
                    id: 837f529d-00f9-4731-b2e1-4a54fc31790a
                    object: chat.completion
                    created: 1777026806
                    model: deepseek-v4-flash
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: 안녕하세요! 저는 DeepSeek 어시스턴트입니다. 언제든지 질문에 답하고 도와드리겠습니다.
                        logprobs: null
                        finish_reason: stop
                    usage:
                      prompt_tokens: 7
                      completion_tokens: 31
                      total_tokens: 38
                      prompt_tokens_details:
                        cached_tokens: 0
                      prompt_cache_hit_tokens: 0
                      prompt_cache_miss_tokens: 7
                    system_fingerprint: fp_evolink_v4_20260402
                thinking_enabled:
                  summary: thinking 활성화 (reasoning_content 포함)
                  value:
                    id: 658083bb-1137-49d2-8c4d-900e508cbd53
                    object: chat.completion
                    created: 1777026807
                    model: deepseek-v4-flash
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: 프랑스의 수도는 **파리**입니다.
                          reasoning_content: >-
                            사용자가 "프랑스의 수도는?"이라고 묻고 있습니다. 상식적인 질문이므로 "파리"라고 바로
                            답하면 됩니다.
                        logprobs: null
                        finish_reason: stop
                    usage:
                      prompt_tokens: 7
                      completion_tokens: 53
                      total_tokens: 60
                      prompt_tokens_details:
                        cached_tokens: 0
                      completion_tokens_details:
                        reasoning_tokens: 45
                      prompt_cache_hit_tokens: 0
                      prompt_cache_miss_tokens: 7
                    system_fingerprint: fp_evolink_v4_20260402
                cache_hit:
                  summary: 컨텍스트 캐시 히트 (대량의 cache_hit_tokens)
                  value:
                    id: 3e4a1b70-8c59-4b22-a011-9f2c7d5a3e88
                    object: chat.completion
                    created: 1777026900
                    model: deepseek-v4-flash
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: 안녕하세요!
                        logprobs: null
                        finish_reason: stop
                    usage:
                      prompt_tokens: 694
                      completion_tokens: 10
                      total_tokens: 704
                      prompt_tokens_details:
                        cached_tokens: 640
                      prompt_cache_hit_tokens: 640
                      prompt_cache_miss_tokens: 54
                    system_fingerprint: fp_evolink_v4_20260402
        '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 or expired token
                  type: authentication_error
        '402':
          description: 할당량 부족, 충전 필요
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 402
                  message: Insufficient quota
                  type: insufficient_quota_error
        '403':
          description: 해당 모델에 대한 접근 권한 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 403
                  message: Access denied for this model
                  type: permission_error
                  param: model
        '404':
          description: 리소스를 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 404
                  message: Specified model not found
                  type: not_found_error
                  param: model
        '413':
          description: 요청 본문이 너무 큼
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 413
                  message: Request body too large
                  type: request_too_large_error
                  param: messages
        '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: internal_server_error
        '502':
          description: 게이트웨이 오류
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 502
                  message: Bad gateway
                  type: bad_gateway_error
        '503':
          description: 서비스 일시적으로 사용 불가
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 503
                  message: Service temporarily unavailable
                  type: service_unavailable_error
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: >-
            채팅 모델 이름


            - `deepseek-v4-flash`: 빠른 범용 모델, 1M 컨텍스트

            - `deepseek-v4-pro`: 심층 추론 모델, 수학·프로그래밍 및 복잡한 논리에 능숙


            **팁**: 두 모델 **모두 기본적으로 `thinking`이 활성화**되어 있어 응답에
            `reasoning_content`가 포함됩니다. 출력 token 비용을 낮추려면
            `thinking.type="disabled"`로 끌 수 있습니다. 두 모델의 매개변수는 완전히 동일합니다.
          enum:
            - deepseek-v4-flash
            - deepseek-v4-pro
          default: deepseek-v4-flash
          example: deepseek-v4-flash
        messages:
          type: array
          description: |-
            대화 메시지 목록, 다중 턴 대화 지원

            역할마다 메시지 필드 구조가 다르므로 해당 역할을 선택하여 확인하세요
          items:
            oneOf:
              - $ref: '#/components/schemas/SystemMessage'
              - $ref: '#/components/schemas/UserMessage'
              - $ref: '#/components/schemas/AssistantRequestMessage'
              - $ref: '#/components/schemas/ToolMessage'
            discriminator:
              propertyName: role
              mapping:
                system:
                  $ref: '#/components/schemas/SystemMessage'
                user:
                  $ref: '#/components/schemas/UserMessage'
                assistant:
                  $ref: '#/components/schemas/AssistantRequestMessage'
                tool:
                  $ref: '#/components/schemas/ToolMessage'
          minItems: 1
        thinking:
          type: object
          description: >-
            사고 모드 제어 (V4 신규)


            **설명**:

            - 심층 사고(Chain of Thought) 기능 제어에 사용

            - **두 모델 모두 기본 활성화** (`type=enabled`)

            - 활성화되면 추론 과정이 `choices[].message.reasoning_content`로 반환되며 출력
            token으로 과금됩니다


            ⚠️ **다중 턴 대화/도구 호출 주의사항**: 이번 턴의 응답에 `reasoning_content`가 포함된 경우,
            **다음 요청의 `messages` 히스토리 내 해당 assistant 메시지에 이 필드를 그대로 돌려보내야 합니다**.
            그렇지 않으면 API가 400 `The reasoning_content in the thinking mode must be
            passed back to the API`를 반환합니다. 처리하고 싶지 않다면 세션 전체에
            `thinking.type="disabled"`를 명시적으로 설정할 수 있습니다.
          properties:
            type:
              type: string
              description: |-
                사고 모드 스위치

                - `enabled`: 심층 사고 활성화 (기본값)
                - `disabled`: 심층 사고 비활성화, 모델이 직접 응답
              enum:
                - enabled
                - disabled
              default: enabled
            reasoning_effort:
              type: string
              description: |-
                추론 노력 수준

                - `low`: 낮은 노력, 빠른 응답과 적은 reasoning_tokens
                - `medium`: 중간 노력 (기본값)
                - `high`: 높은 노력, 더 철저한 사고 과정, 더 많은 reasoning_tokens 소비
              enum:
                - low
                - medium
                - high
              default: medium
        temperature:
          type: number
          description: |-
            샘플링 온도, 출력의 무작위성을 제어합니다

            **설명**:
            - 낮은 값(예: 0.2): 더 결정적이고 집중된 출력
            - 높은 값(예: 1.5): 더 무작위적이고 창의적인 출력
            - 기본값: 1
          minimum: 0
          maximum: 2
          default: 1
          example: 1
        top_p:
          type: number
          description: |-
            Nucleus Sampling (핵 샘플링) 매개변수

            **설명**:
            - 누적 확률 상위 몇 %의 token에서 샘플링할지 제어합니다
            - 예를 들어 0.9는 누적 확률 90%까지의 token 중에서 선택합니다
            - 기본값: 1.0 (모든 token 고려)

            **권장**: temperature와 top_p를 동시에 조정하지 마세요
          minimum: 0
          maximum: 1
          default: 1
          example: 1
        max_tokens:
          type: integer
          description: |-
            생성 콘텐츠의 최대 token 수 제한

            **설명**:
            - V4 시리즈는 최대 **384,000 tokens**까지 가능
            - thinking 활성화 시 reasoning_tokens도 max_tokens 상한에 포함됩니다
            - 설정하지 않으면 모델이 생성 길이를 스스로 결정합니다
          minimum: 1
          maximum: 384000
          example: 4096
        frequency_penalty:
          type: number
          description: |-
            빈도 페널티 매개변수, 반복 내용을 줄이는 데 사용

            **설명**:
            - 양수 값은 이미 생성된 텍스트에서의 token 빈도에 따라 페널티를 부여합니다
            - 값이 클수록 이미 등장한 내용이 반복될 가능성이 낮아집니다
            - 기본값: 0 (페널티 없음)
          minimum: -2
          maximum: 2
          default: 0
          example: 0
        presence_penalty:
          type: number
          description: |-
            존재 페널티 매개변수, 새로운 주제 생성을 장려하는 데 사용

            **설명**:
            - 양수 값은 token이 이미 텍스트에 등장했는지 여부에 따라 페널티를 부여합니다
            - 값이 클수록 새로운 주제를 논의하는 경향이 강해집니다
            - 기본값: 0 (페널티 없음)
          minimum: -2
          maximum: 2
          default: 0
          example: 0
        response_format:
          type: object
          description: |-
            응답 형식 지정

            **설명**:
            - `{"type": "json_object"}`로 설정하면 JSON 모드가 활성화됩니다
            - JSON 모드에서는 모델이 유효한 JSON 형식의 콘텐츠를 출력합니다
            - 최상의 결과를 얻으려면 system 또는 user 메시지에서 JSON 형식 출력을 명시적으로 요청하는 것이 좋습니다
          properties:
            type:
              type: string
              enum:
                - text
                - json_object
              description: 응답 형식 유형
              default: text
        stop:
          description: |-
            중지 시퀀스, 모델이 이 문자열을 만나면 생성을 중단합니다

            **설명**:
            - 단일 문자열 또는 문자열 배열일 수 있습니다
            - 최대 16개의 중지 시퀀스 지원
          oneOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 16
        stream:
          type: boolean
          description: |-
            응답을 스트리밍 방식으로 반환할지 여부

            - `true`: 스트리밍 반환, SSE(Server-Sent Events)를 통해 청크 단위로 실시간 반환
            - `false`: 완전한 응답을 기다린 후 한 번에 반환 (기본값)
          default: false
          example: false
        stream_options:
          type: object
          description: |-
            스트리밍 응답 옵션

            `stream=true`일 때만 유효합니다
          properties:
            include_usage:
              type: boolean
              description: 스트리밍 종료 시 usage 통계 정보 반환 (캐시 세부 항목 포함)
        tools:
          type: array
          description: |-
            도구 정의 목록, Function Calling에 사용

            **설명**:
            - 최대 128개의 도구 정의 지원
            - 각 도구는 이름, 설명, 매개변수 schema를 정의해야 합니다
          items:
            $ref: '#/components/schemas/Tool'
          maxItems: 128
        tool_choice:
          description: >-
            도구 호출 동작 제어


            **가능한 값**:

            - `none`: 어떤 도구도 호출하지 않음

            - `auto`: 모델이 도구 호출 여부를 자동 결정 (tools 제공 시 기본값)

            - `required`: 모델이 하나 이상의 도구를 반드시 호출하도록 강제

            - 객체 형식 `{"type":"function","function":{"name":"xxx"}}`: 특정 도구를 지정하여
            호출


            **기본값**: tools 미제공 시 `none`, tools 제공 시 `auto`
          oneOf:
            - type: string
              enum:
                - none
                - auto
                - required
            - type: object
              description: 특정 도구 지정 호출
              properties:
                type:
                  type: string
                  enum:
                    - function
                function:
                  type: object
                  properties:
                    name:
                      type: string
                      description: 호출할 함수 이름
                  required:
                    - name
        logprobs:
          type: boolean
          description: |-
            token의 로그 확률을 반환할지 여부

            **설명**:
            - `true`로 설정하면 응답에 각 token의 로그 확률 정보가 포함됩니다
          default: false
        top_logprobs:
          type: integer
          description: |-
            확률 상위 N개 token의 로그 확률 반환

            **설명**:
            - `logprobs`가 `true`로 설정되어야 합니다
            - 값 범위: `[0, 20]`
          minimum: 0
          maximum: 20
        logit_bias:
          type: object
          description: |-
            Token 바이어스 매핑

            **설명**:
            - 키는 tokenizer의 token ID이고, 값은 -100에서 100 사이의 바이어스 값입니다
            - -100은 해당 token을 완전히 금지, 100은 강제 생성을 의미합니다
            - 일반적인 -1에서 1 범위의 값도 관찰 가능한 영향을 미칩니다
          additionalProperties:
            type: number
            minimum: -100
            maximum: 100
        'n':
          type: integer
          description: |-
            각 입력 메시지에 대해 생성할 채팅 완성 옵션 수

            **설명**:
            - 기본값 1; N으로 설정 시 N개의 후보를 반환 (N × output_tokens로 과금)
          minimum: 1
          maximum: 8
          default: 1
          example: 1
        seed:
          type: integer
          description: |-
            랜덤 시드 (Beta)

            **설명**:
            - 지정하면 모델이 결정적 샘플링을 시도합니다
            - 동일한 seed + 동일한 기타 매개변수 → 동일한 출력 (100% 보장은 아님)
        user:
          type: string
          description: |-
            최종 사용자를 나타내는 고유 식별자

            **설명**:
            - 플랫폼이 남용 행위를 모니터링하고 감지하는 데 도움이 됩니다
            - 해시된 사용자 ID 사용을 권장합니다
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: 채팅 완성의 고유 식별자
          example: 53c548dc-ec02-4a2f-bbb6-eca4184630b8
        model:
          type: string
          description: 실제 사용된 모델 이름
          example: deepseek-v4-flash
        object:
          type: string
          enum:
            - chat.completion
          description: 응답 유형
          example: chat.completion
        created:
          type: integer
          description: 생성 타임스탬프 (Unix 초)
          example: 1777021417
        choices:
          type: array
          description: 채팅 생성의 선택 목록
          items:
            $ref: '#/components/schemas/Choice'
        usage:
          $ref: '#/components/schemas/Usage'
        system_fingerprint:
          type: string
          description: 시스템 지문 식별자
          example: fp_evolink_v4_20260402
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP 상태 오류 코드
            message:
              type: string
              description: 오류 설명 정보
            type:
              type: string
              description: 오류 유형
            param:
              type: string
              description: 관련 매개변수 이름
    SystemMessage:
      title: System Message
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - system
          description: 역할 식별자, 고정값 `system`
        content:
          type: string
          description: 시스템 프롬프트 내용, AI의 역할과 동작을 설정하는 데 사용
        name:
          type: string
          description: 참여자 이름, 서로 다른 시스템 프롬프트 출처를 구분하는 데 사용
    UserMessage:
      title: User Message
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
          description: 역할 식별자, 고정값 `user`
        content:
          type: string
          description: 사용자 메시지 내용 (순수 텍스트 문자열)
        name:
          type: string
          description: 참여자 이름, 서로 다른 사용자를 구분하는 데 사용
    AssistantRequestMessage:
      title: Assistant Message
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - assistant
          description: 역할 식별자, 고정값 `assistant`
        content:
          type:
            - string
            - 'null'
          description: |-
            어시스턴트 메시지 내용

            **설명**:
            - 다중 턴 대화에서 이전 어시스턴트 응답을 전달하는 데 사용
            - `tool_calls`가 존재할 경우 `null`일 수 있습니다
        name:
          type: string
          description: 참여자 이름
        prefix:
          type: boolean
          description: |-
            접두사 연속 생성 모드 활성화 여부 (Beta)

            **설명**:
            - 마지막 메시지에서만 설정 가능
            - `true`로 설정하면 모델이 해당 메시지의 `content`를 접두사로 하여 이어서 생성합니다
          default: false
        reasoning_content:
          type:
            - string
            - 'null'
          description: >-
            사고 체인 내용 (Beta)


            **설명**:

            - `deepseek-v4-flash`와 `deepseek-v4-pro` 모두 thinking 활성화 시(기본값)
            생성됩니다

            - **다중 턴 시나리오에서 반드시 원본 그대로 돌려보내야 함**: 이전 턴 응답의
            `choices[0].message.reasoning_content`를 히스토리 assistant 메시지의
            `reasoning_content` 필드로 그대로 전달하세요. 누락되면 API에서 거부됩니다 (400)

            - 히스토리 컨텍스트로 전달할 때는 `prefix`와 함께 쓸 필요 없음; 접두사 연속 생성을 명시적으로 활성화할 때만
            `prefix=true`를 사용합니다
        tool_calls:
          type: array
          description: |-
            도구 호출 목록

            다중 턴 대화에서 이전 도구 호출 정보를 전달하는 데 사용
          items:
            type: object
            properties:
              id:
                type: string
                description: 도구 호출의 고유 식별자
              type:
                type: string
                enum:
                  - function
              function:
                type: object
                properties:
                  name:
                    type: string
                    description: 호출된 함수 이름
                  arguments:
                    type: string
                    description: 함수 매개변수 (JSON 문자열)
    ToolMessage:
      title: Tool Message
      type: object
      required:
        - role
        - content
        - tool_call_id
      properties:
        role:
          type: string
          enum:
            - tool
          description: 역할 식별자, 고정값 `tool`
        content:
          type: string
          description: 도구 호출의 반환 결과 내용
        tool_call_id:
          type: string
          description: |-
            도구 호출 ID

            assistant 메시지의 `tool_calls`가 반환한 `id` 필드에 대응합니다
    Tool:
      type: object
      required:
        - type
        - function
      properties:
        type:
          type: string
          enum:
            - function
          description: 도구 유형, 현재 `function`만 지원
        function:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              description: |-
                호출할 함수 이름

                **설명**:
                - a-z, A-Z, 0-9 문자로 구성되어야 하며, 밑줄과 하이픈을 포함할 수 있습니다
                - 최대 길이 64자
            description:
              type: string
              description: 함수 기능 설명, 모델이 언제 어떻게 함수를 호출할지 이해하도록 돕습니다
            parameters:
              type: object
              description: |-
                함수 입력 매개변수, JSON Schema 객체로 기술

                **설명**:
                - `parameters`를 생략하면 매개변수 목록이 비어 있는 함수로 정의됩니다
            strict:
              type: boolean
              description: |-
                엄격 모드 활성화 여부 (Beta)

                **설명**:
                - `true`로 설정하면 API가 strict 모드로 함수 호출을 수행합니다
                - 출력이 항상 함수의 JSON Schema 정의에 부합하도록 보장합니다
              default: false
    Choice:
      type: object
      properties:
        index:
          type: integer
          description: 선택의 인덱스
          example: 0
        message:
          $ref: '#/components/schemas/AssistantMessage'
        logprobs:
          type:
            - object
            - 'null'
          description: 로그 확률 정보 (요청에 `logprobs=true`인 경우에만 반환)
        finish_reason:
          type: string
          description: |-
            종료 원인

            - `stop`: 자연 종료 또는 중지 시퀀스 트리거
            - `length`: 최대 token 한도 도달
            - `content_filter`: 내용이 안전 정책에 의해 필터링됨
            - `tool_calls`: 모델이 도구를 호출함
            - `insufficient_system_resource`: 백엔드 리소스 부족
          enum:
            - stop
            - length
            - content_filter
            - tool_calls
            - insufficient_system_resource
          example: stop
    Usage:
      type: object
      description: Token 사용 통계 정보 (캐시 및 추론 세부 항목 포함)
      properties:
        prompt_tokens:
          type: integer
          description: 입력 내용의 총 token 수 (캐시 히트 및 미스 포함)
          example: 694
        completion_tokens:
          type: integer
          description: 출력 내용의 token 수 (reasoning 부분 포함)
          example: 20
        total_tokens:
          type: integer
          description: 총 token 수 = prompt_tokens + completion_tokens
          example: 714
        prompt_cache_hit_tokens:
          type: integer
          description: >-
            입력 중 컨텍스트 캐시에 히트한 token 수


            **설명**: 캐시 히트 token은 **캐시 히트 단가**로 과금됩니다 (Flash 20 UC/1K, Pro 100
            UC/1K)
          example: 640
        prompt_cache_miss_tokens:
          type: integer
          description: |-
            입력 중 캐시에 미스된 token 수

            **설명**: **표준 입력 단가**로 과금됩니다 (Flash 100 UC/1K, Pro 1200 UC/1K)
          example: 54
        prompt_tokens_details:
          type: object
          description: 입력 token 세부 항목 (OpenAI 스타일)
          properties:
            cached_tokens:
              type: integer
              description: 캐시 히트 token 수 (`prompt_cache_hit_tokens`과 동일, 프레임워크에서 자동 매핑)
              example: 640
        completion_tokens_details:
          type: object
          description: 출력 token 세부 항목
          properties:
            reasoning_tokens:
              type: integer
              description: 사고 모드에서 생성된 추론 token 수 (출력에 포함되며 출력 단가로 과금)
              example: 10
    AssistantMessage:
      type: object
      properties:
        role:
          type: string
          description: 메시지 발신자의 역할
          enum:
            - assistant
          example: assistant
        content:
          type: string
          description: AI의 응답 메시지 내용
          example: 안녕하세요! 저는 DeepSeek V4입니다. 일반 대화, 코드 생성, 수학적 추론 등 다양한 작업에 능숙합니다.
        reasoning_content:
          type: string
          description: >-
            사고 체인 내용 (thinking 활성화 시에만 반환)


            **설명**:

            - `deepseek-v4-pro`는 기본 활성화되어 완전한 추론 과정을 반환합니다

            - `deepseek-v4-flash`는 `thinking.type="enabled"`를 명시적으로 설정해야 반환됩니다

            - 출력 token으로 과금되며 `completion_tokens_details.reasoning_tokens`에
            포함됩니다
          example: 이 문제를 분석해 보겠습니다...
        tool_calls:
          type: array
          description: 도구 호출 목록 (모델이 도구 호출을 결정할 때 반환)
          items:
            type: object
            properties:
              id:
                type: string
                description: 도구 호출의 고유 식별자
              type:
                type: string
                enum:
                  - function
              function:
                type: object
                properties:
                  name:
                    type: string
                    description: 호출된 함수 이름
                  arguments:
                    type: string
                    description: 함수 매개변수 (JSON 문자열)
  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
        ```

````