Chat Completions API

Chat Completions API

Chat Completions API는 입력한 메시지 목록을 바탕으로 모델이 대화 응답을 생성하도록 하는 OpenAI 호환 엔드포인트예요. 기본적인 채팅뿐 아니라 Partial Mode, Tool Use(함수 호출), JSON Mode, 생각 모드까지 한 엔드포인트에서 함께 다뤄져요. 이 문서는 Kimi API 공식 문서의 Chat Completions API 페이지를 해요체로 옮긴 거예요. 원문은 Kimi API Docs에서 확인할 수 있어요.

엔드포인트

POST https://api.moonshot.cn/v1/chat/completions

Content-Type: application/json 헤더와 Authorization: Bearer $MOONSHOT_API_KEY 헤더를 붙이고, 요청 본문에 model과 messages를 담아 보내면 돼요.

핵심 파라미터

model

호출할 모델 ID예요. 예를 들어 kimi-k3, kimi-k2.7-code(또는 고속판 kimi-k2.7-code-highspeed), kimi-k2.6을 지정할 수 있어요.

messages와 content 필드

content 필드는 두 가지 형태를 지원해요.

순수 텍스트 문자열:

{ "content": "안녕하세요" }

객체 배열(다중 모달 입력) — 배열의 각 요소는 type 필드로 종류를 구분해요. 이미지/비디오는 base64(data:image/png;base64,...)나 파일 참조(ms://<file_id>)로 넣을 수 있어요. image_url과 video_url은 객체 대신 문자열을 직접 넣어도 돼요.

{ "type": "image_url", "image_url": "data:image/png;base64,..." }

streaming

"stream": true를 주면 Server-Sent Events(SSE)로 응답이 조각조각 내려와요. 채팅·코드 생성·긴 텍스트처럼 실시간성이 중요한 곳에서 권장해요.

thinking (생각 모드)

  • kimi-k3는 항상 추론하고 최상위 reasoning_effort("low"/"high"/"max", 기본 "max")로 강도를 조절해요.
  • kimi-k2.6·kimi-k2.7-code는 thinking 객체로 생각 모드를 제어해요.
    • thinking.type — "enabled" | "disabled" (생각 스위치. kimi-k2.7-code는 항상 enabled라 끌 수 없어요.)
    • thinking.keep — null(기본, 이력 생각 미보존) | "all" (이전 턴의 reasoning_content를 컨텍스트에 보존, Preserved Thinking). kimi-k2.7-code는 "all" 고정이라 다른 값을 넣으면 오류가 나요.

response_format (JSON Mode)

{
  "model": "kimi-k2.6",
  "messages": [
    {"role": "system", "content": "title, author, summary 필드를 포함한 JSON을 출력하세요."},
    {"role": "user", "content": "이 기사를 요약해 주세요..."}
  ],
  "response_format": {"type": "json_object"}
}

tools (Tool Use)

tools 파라미터에 JSON Schema로 정의한 외부 도구를 넘기면, 모델이 적절한 시점에 해당 도구를 호출할지 결정해요. 도구를 로컬에서 실행한 뒤에는 같은 tool_call_id를 붙여 role="tool" 메시지로 결과를 messages에 다시 넣어요:

{"role": "tool", "tool_call_id": "call_xxx", "content": "맑음, 25°C"}

응답 형식

비스트리밍 응답

{
  "id": "cmpl-04ea926191a14749b7f2c7a48a68abc6",
  "object": "chat.completion",
  "created": 1698999496,
  "model": "kimi-k2.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "안녕하세요, 이레! 1+1은 2입니다. 다른 질문이 있으면 언제든 물어보세요!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 21,
    "total_tokens": 40,
    "cached_tokens": 10
  }
}

응답의 "model" 필드는 요청에서 보낸 모델 이름을 따라가요 (kimi-k2.6이라면 "kimi-k2.6"으로 표시).

스트리밍 응답

각 데이터 블록의 message가 delta로 바뀌어요. stream_options: {"include_usage": true}를 주면 마지막 [DONE] 블록 직전에 usage(토큰 소모량)를 추가로 받을 수 있어요.

data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{"content":"안녕하세요"},"finish_reason":null}]}

추가 기능

  • 다중 턴 대화 — Kimi API는 무상태(stateless)라 기억이 없어요. 이전 턴의 assistant 응답(과 도구 실행 결과)을 그대로 messages에 이어붙여서 다시 보내야 해요.
  • Preserved Thinking — 다중 턴에서 생각 모드를 쓸 때는 매 턴 assistant 메시지의 reasoning_content를 원형 그대로 보존해야 추론 컨텍스트를 잃지 않아요.
  • Partial Mode — assistant 메시지에 "partial": true를 주고 부분 접두사를 미리 넣으면, 그 뒤부터 이어서 생성해요. finish_reason="length"로 잘린 출력을 이어갈 때 유용해요. 다만 response_format={"type":"json_object"}와는 섞어 쓰지 마세요.

더 알아보기