> ## 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(모든 모델) - Messages 전체 참조

> 공개 엔드포인트는 POST /v1/messages입니다. 추론 강도는 output_config.effort로 설정합니다. 최상위 cache_control은 5m/1h 캐시 쓰기를 제어합니다(K3.1 시리즈만 지원). thinking, signature, tool_use 및 서버 측 검색 결과 블록을 모두 보존하세요.

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


## OpenAPI

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


    세 모델 모두 추론이 항상 활성화되며 `output_config.effort`로 강도를 조절합니다. 구조화된 출력, 중지 시퀀스, 캐시
    쓰기 TTL은 K3.1 시리즈만 지원합니다. `model` 필드 설명을 확인하세요. 여러 턴의 대화에서는 thinking,
    signature, tool_use를 포함한 전체 assistant 콘텐츠 블록을 변경 없이 다시 전송하세요.
  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: Messages
    description: Anthropic Messages 호환 API
paths:
  /v1/messages:
    post:
      tags:
        - Messages
      summary: Kimi Messages API(모든 모델, Anthropic 호환)
      description: >-
        공개 엔드포인트는 POST /v1/messages입니다. 추론 강도는 output_config.effort로 설정합니다. 최상위
        cache_control은 5m/1h 캐시 쓰기를 제어합니다(K3.1 시리즈만 지원). thinking, signature,
        tool_use 및 서버 측 검색 결과 블록을 모두 보존하세요.
      operationId: createMessageKimi
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
            examples:
              simple:
                summary: Pro 최소 요청
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: Reply with OK.
              highspeed:
                summary: Highspeed 최소 요청
                value:
                  model: kimi-k3.1-pro-highspeed
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: Reply with OK.
              k3:
                summary: Kimi K3 최소 요청
                value:
                  model: kimi-k3
                  max_tokens: 1024
                  messages:
                    - role: user
                      content: Reply with OK.
              system_prompt:
                summary: system 프롬프트
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 2048
                  output_config:
                    effort: low
                  system: 당신은 정확한 기술 편집자입니다.
                  messages:
                    - role: user
                      content: 컨텍스트 캐싱을 설명해 주세요.
              streaming:
                summary: Anthropic SSE 스트리밍
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: Reply with OK.
                  stream: true
              multimodal:
                summary: 이미지 입력
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content:
                        - type: image
                          source:
                            type: base64
                            media_type: image/jpeg
                            data: /9j/4AAQSkZJRgABAQAA...
                        - type: text
                          text: 이 이미지를 설명해 주세요.
              tool_use:
                summary: 도구 사용
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 2048
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: 오늘 베이징 날씨를 확인해 주세요.
                  tools:
                    - name: get_weather
                      description: 지정한 도시의 날씨 조회
                      input_schema:
                        type: object
                        properties:
                          city:
                            type: string
                            description: 도시 이름
                        required:
                          - city
                  tool_choice:
                    type: auto
              web_search:
                summary: 서버 측 웹 검색
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: Use web search to find the official Kimi homepage URL.
                  tools:
                    - type: web_search_20250305
                      name: web_search
                      max_uses: 1
              structured_output:
                summary: 엄격한 구조화된 출력(K3.1 시리즈만 지원)
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                    format:
                      type: json_schema
                      schema:
                        type: object
                        properties:
                          result:
                            type: string
                        required:
                          - result
                        additionalProperties: false
                  messages:
                    - role: user
                      content: Return a JSON object with result equal to OK.
              cache_1h:
                summary: 최상위 1h 캐시(K3.1 시리즈만 지원)
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: Reply with OK.
                  cache_control:
                    type: ephemeral
                    ttl: 1h
      responses:
        '200':
          description: Message 응답입니다. 스트리밍 요청은 Anthropic SSE 이벤트 스트림을 반환합니다
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
            text/event-stream:
              schema:
                type: string
                description: >-
                  일반적인 이벤트 순서는 message_start, content_block_*, message_delta,
                  message_stop입니다.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateMessageRequest:
      type: object
      required:
        - model
        - max_tokens
        - messages
      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이며 추론이 항상 활성화됩니다.


            구조화된 출력(`output_config.format`), 중지 시퀀스(`stop_sequences`), 캐시 쓰기
            TTL(`cache_control`)은 K3.1 시리즈만 지원하며 `kimi-k3`는 지원하지 않습니다.
            `kimi-k3`의 응답은 `thinking` 블록 없이 `text` 블록만 포함할 수 있습니다.
        max_tokens:
          type: integer
          minimum: 1
          description: thinking과 최종 텍스트를 포함해 이번 생성에 허용되는 최대 token 수입니다.
          maximum: 1048576
        messages:
          type: array
          minItems: 1
          description: >-
            Anthropic Messages 메시지 목록입니다. 여러 턴 대화에서는 assistant의 전체 콘텐츠 블록을 변경하지
            말고 다시 전달하세요.
          items:
            $ref: '#/components/schemas/Message'
        system:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/MessagesTextBlockParam'
          description: 문자열 또는 text 블록 배열 형식의 시스템 프롬프트입니다.
        stream:
          type: boolean
          default: false
          description: Anthropic SSE 이벤트 스트림 반환 여부입니다.
        tools:
          type: array
          description: >-
            사용자 정의 함수 또는 서버 측 웹 검색입니다. 내장 검색은 type=web_search_20250305,
            name=web_search를 사용하며 실제 호출 횟수로 과금합니다.
          items:
            oneOf:
              - $ref: '#/components/schemas/Tool'
              - $ref: '#/components/schemas/WebSearchTool'
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        stop_sequences:
          type: array
          items:
            type: string
          maxItems: 5
          description: >-
            중지 시퀀스. 정확히 일치하면 출력을 중단하며 일치한 시퀀스 자체는 출력하지 않습니다. 최대 5개, 각각 32바이트
            이하입니다. 일치 시 `stop_reason`은 `end_turn`, `stop_sequence`는 `null`입니다.


            `kimi-k3.1-pro` / `kimi-k3.1-pro-highspeed`만 지원하며 `kimi-k3`는 지원하지
            않습니다.
        cache_control:
          type: object
          description: >-
            최상위 캐시 쓰기 옵션. `kimi-k3.1-pro` / `kimi-k3.1-pro-highspeed`만 지원하며
            `kimi-k3`는 이 매개변수를 지원하지 않습니다. 쓰기 TTL은 최상위 cache_control만 제어하며 메시지 블록
            내부의 캐시 표시는 이 필드를 대체할 수 없습니다. 생략하면 기본값은 5m입니다.
          properties:
            type:
              type: string
              enum:
                - ephemeral
              description: 캐시 유형으로 ephemeral로 고정됩니다.
            ttl:
              type: string
              enum:
                - 5m
                - 1h
              default: 5m
              description: 캐시 유효 기간은 5m 또는 1h이며 기본값은 5m입니다.
          required:
            - type
        output_config:
          type: object
          description: '출력 설정: 추론 강도 및 구조화 출력.'
          properties:
            effort:
              type: string
              enum:
                - low
                - high
                - max
                - medium
                - xhigh
                - minimal
                - none
              default: max
              description: >-
                추론 강도. 추론은 항상 활성화되며 `thinking.type: "disabled"`를 전달해도 꺼지지 않습니다.


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

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


                강도를 높이면 일반적으로 추론 토큰과 지연 시간이 증가합니다. 추론 토큰은 출력에 포함됩니다.
            format:
              type: object
              description: >-
                구조화된 출력: 모델이 지정한 JSON Schema를 엄격히 따르는 JSON을 출력합니다.
                `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
                schema:
                  type: object
                  description: 출력이 따라야 하는 JSON Schema입니다.
                  additionalProperties: true
              required:
                - type
                - schema
        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`는 지원하지 않는 값에 대해
            오류를 반환합니다.
    MessageResponse:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - message
        role:
          type: string
          enum:
            - assistant
        model:
          type: string
          example: kimi-k3.1-pro
        content:
          type: array
          items:
            $ref: '#/components/schemas/ContentBlock'
        stop_reason:
          type:
            - string
            - 'null'
          enum:
            - end_turn
            - max_tokens
            - tool_use
            - refusal
            - null
        stop_sequence:
          type:
            - string
            - 'null'
        usage:
          $ref: '#/components/schemas/MessageUsage'
    Message:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          description: 메시지 역할입니다. user와 assistant만 지원합니다.
          enum:
            - user
            - assistant
        content:
          description: 일반 텍스트 문자열 또는 Anthropic 콘텐츠 블록 배열 형식의 메시지 내용입니다.
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentBlock'
    MessagesTextBlockParam:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
      required:
        - type
        - text
    Tool:
      type: object
      required:
        - name
        - input_schema
      properties:
        name:
          type: string
          description: 도구 이름입니다.
        description:
          type: string
          description: 모델이 도구를 언제 사용할지 판단하는 데 도움이 되는 설명입니다.
        input_schema:
          type: object
          additionalProperties: true
          description: JSON Schema 형식의 도구 매개변수 정의입니다.
    WebSearchTool:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - web_search_20250305
        name:
          type: string
          enum:
            - web_search
        max_uses:
          type: integer
          minimum: 1
          description: 이번 응답에 허용되는 최대 검색 횟수입니다.
    ToolChoice:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: 도구 선택입니다. auto는 모델이 결정하고 any는 도구 호출을 요구하며 none은 도구 호출을 비활성화합니다.
          enum:
            - auto
            - any
            - none
          default: auto
    ContentBlock:
      description: 텍스트, 이미지, 추론, 도구 사용 또는 도구 결과를 위한 Anthropic 콘텐츠 블록입니다.
      oneOf:
        - $ref: '#/components/schemas/TextBlock'
        - $ref: '#/components/schemas/ImageBlock'
        - $ref: '#/components/schemas/ThinkingBlock'
        - $ref: '#/components/schemas/ToolUseBlock'
        - $ref: '#/components/schemas/ToolResultBlock'
        - $ref: '#/components/schemas/ServerToolUseBlock'
        - $ref: '#/components/schemas/WebSearchResultBlock'
    MessageUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          description: 캐시 읽기와 쓰기를 제외한 일반 입력 토큰 수입니다. 세 입력 항목은 중복되지 않으므로 캐시 토큰을 다시 빼지 마세요.
        cache_creation_input_tokens:
          type: integer
          description: 캐시에 기록된 입력 tokens입니다.
        cache_read_input_tokens:
          type: integer
          description: 캐시에서 제공된 입력 tokens입니다.
        output_tokens:
          type: integer
          description: thinking tokens를 포함한 출력 tokens입니다.
        output_tokens_details:
          type: object
          properties:
            thinking_tokens:
              type: integer
        cache_creation:
          type: object
          properties:
            ephemeral_5m_input_tokens:
              type: integer
              minimum: 0
            ephemeral_1h_input_tokens:
              type: integer
              minimum: 0
          description: >-
            cache_creation_input_tokens의 두 캐시 쓰기 구간별 내역. K3.1 시리즈는 실제 TTL에 따라 각각
            과금합니다.
        server_tool_use:
          type: object
          properties:
            web_search_requests:
              type: integer
              minimum: 0
          description: 이번 응답의 검색 사용량입니다.
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
            - error
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
        request_id:
          type: string
    TextBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          description: 콘텐츠 블록 유형입니다. text로 고정됩니다.
          enum:
            - text
        text:
          type: string
          description: 텍스트 내용입니다.
    ImageBlock:
      type: object
      required:
        - type
        - source
      description: 이미지 콘텐츠 블록(멀티모달 입력)입니다.
      properties:
        type:
          type: string
          enum:
            - image
          description: 콘텐츠 블록 유형입니다. image로 고정됩니다.
        source:
          type: object
          required:
            - type
          description: 이미지 출처입니다.
          properties:
            type:
              type: string
              enum:
                - base64
                - url
              description: 이미지 소스입니다. base64는 인라인 데이터, url은 파일 참조입니다.
            media_type:
              type: string
              enum:
                - image/jpeg
                - image/png
                - image/gif
                - image/webp
              description: '`type=base64`일 때의 이미지 MIME 유형입니다.'
            data:
              type: string
              description: '`type=base64`일 때의 이미지 Base64 데이터입니다(`data:` 접두사 제외).'
            url:
              type: string
              description: 이미지 파일 참조이며 type=url일 때만 사용합니다.
    ThinkingBlock:
      type: object
      required:
        - type
        - thinking
      properties:
        type:
          type: string
          description: 콘텐츠 블록 유형입니다. thinking으로 고정됩니다.
          enum:
            - thinking
        thinking:
          type: string
          description: 모델의 추론 내용입니다. 여러 턴 대화에서는 signature와 함께 변경하지 말고 다시 전달하세요.
        signature:
          type: string
          description: 여러 턴 대화에서는 thinking 블록과 함께 변경하지 말고 다시 전달하세요.
    ToolUseBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          description: 콘텐츠 블록 유형입니다. tool_use로 고정됩니다.
          enum:
            - tool_use
        id:
          type: string
          description: 결과를 반환할 때 참조하는 tool_use ID입니다.
        name:
          type: string
          description: 모델이 요청한 도구 이름입니다.
        input:
          type: object
          additionalProperties: true
          description: 모델이 생성한 도구 입력 객체입니다.
    ToolResultBlock:
      type: object
      required:
        - type
        - tool_use_id
        - content
      properties:
        type:
          type: string
          description: 콘텐츠 블록 유형입니다. tool_result로 고정됩니다.
          enum:
            - tool_result
        tool_use_id:
          type: string
          description: 대응하는 tool_use 콘텐츠 블록의 ID입니다.
        content:
          description: 문자열 또는 텍스트와 이미지 블록 배열 형식의 도구 실행 결과입니다.
          oneOf:
            - type: string
            - type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/ImageBlock'
        is_error:
          type: boolean
          default: false
          description: 도구 실행 실패 여부입니다.
    ServerToolUseBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - server_tool_use
        id:
          type: string
        name:
          type: string
        input:
          type: object
          additionalProperties: true
    WebSearchResultBlock:
      type: object
      required:
        - type
        - tool_use_id
        - content
      properties:
        type:
          type: string
          enum:
            - web_search_tool_result
        tool_use_id:
          type: string
        content:
          oneOf:
            - type: array
              items:
                type: object
                additionalProperties: true
            - type: object
              additionalProperties: true
              description: 검색 오류 객체로 type=web_search_tool_result_error입니다.
  responses:
    BadRequest:
      description: 잘못된 요청 매개변수
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: API Key가 없거나 유효하지 않습니다
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: 요청 한도 초과 또는 할당량 부족
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: 내부 서비스 오류
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  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.