Kimi K3 실사용 가이드: 새로운 파라미터와 API 지원 매트릭스

이 글에서는 Kimi K3의 새로운 파라미터와 사용 시 참고 사항을 다룹니다. AIHubMix에서 K3는 Chat Completions, Responses, Claude 호환 Messages API를 통해 사용할 수 있습니다. 참고: Moonshot 공식 플랫폼 문서.

각 섹션의 "검증됨" 결론과 샘플 응답은 2026-07-17에 AIHubMix API(Chat Completions / Responses / Messages)를 통해 실제로 호출한 결과에서 나온 것입니다.

1. 모델 사양 한눈에 보기

검증됨: 두 stop 제한이 모두 검증되며, 어느 쪽이든 초과하면 400이 반환됩니다. Messages API도 stop_sequences에 동일한 검증을 적용합니다.

❗ 중지 시퀀스에 도달했을 때 Messages API는 Anthropic 의미 체계를 따르지 않습니다: 테스트에서 stop_reason은 ("stop_sequence" 대신) "end_turn"이었고, stop_sequence는 null이었으며, 중지 단어 앞의 가시 텍스트가 비어 있을 수도 있었습니다. 이 두 필드로 응답 잘림을 감지하는 클라이언트는 이 점에 유의하세요.

# stop with 6 entries / a 33-byte entry -> HTTP 400
"Invalid request: stop array too long. Expected an array with maximum length 5, but got an array with length 6 instead"
"Invalid request: stop sequence must not be longer than 32, but got 33 instead"

2. 사고 모드: reasoning_effort는 max만 지원

K3의 사고 기능은 기본적으로 켜져 있으며, reasoning_effort는 "max" 한 단계만 지원합니다.

다중 턴 대화에서는 사고 기록을 원문 그대로 다시 전달해야 합니다: Moonshot 공식 문서에 따르면 K3는 사고 보존(preserved thinking) 방식으로 학습되었으므로, 다중 턴 대화에서 이전 assistant 메시지를 완전하고 수정되지 않은 상태로(사고 내용 포함) 전달해야 합니다. 사고 기록이 빠지면 출력 품질이 불안정해집니다. 세션 관리 프레임워크나 프록시 계층을 사용한다면 사고 내용이 잘리지 않고 다시 전달되는지 확인하세요.
Chat Completions

사고 내용은 응답의 reasoning_content 필드로 반환됩니다. 다중 턴 대화에서는 이전 assistant 메시지(reasoning_content 포함)를 원문 그대로 다시 전달하세요.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    messages=[
        {"role": "user", "content": "A snail is at the bottom of a 10-meter well. Each day it climbs 3 meters, but each night it slides back 2 meters. How many days does it take to reach the top?"}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)

# Multi-turn: pass the previous assistant message back verbatim
messages = [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "Paris.", "reasoning_content": "<reasoning_content from the previous response>"},
    {"role": "user", "content": "And its population?"},
]

검증됨: 응답에 reasoning_content가 반환되며, 이전 assistant 메시지(reasoning_content 포함)를 원문 그대로 다시 전달한 후에도 이후 턴이 정상적으로 응답합니다.
Responses

사고 내용은 reasoning 출력 항목으로 반환됩니다. 다중 턴 대화에서는 이전 턴의 출력 항목(reasoning + message)을 원문 그대로 input에 덧붙이세요.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

response = client.responses.create(
    model="kimi-k3",
    input="Answer in one word: capital of France",
)

# Observed response.output item types: ["reasoning", "message"]; text: "Paris"
# Multi-turn: input = [first user message] + response.output + [next user message]
# Observed second-turn answer with output items passed back: "Berlin"

Messages

사고 내용은 기본 thinking 콘텐츠 블록으로 반환됩니다. 다중 턴 대화에서는 이전 assistant 콘텐츠 블록(thinking 블록 포함)을 원문 그대로 다시 전달하세요.

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com"
)

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Answer in one word: capital of France"}
    ],
)

# Observed response.content block types: ["thinking", "text"]; text: "Paris"
# Multi-turn: pass response.content back verbatim as the assistant message

3. 샘플링 파라미터는 고정되어 있음

K3의 샘플링 파라미터는 모델 제공자가 고정해 두었습니다: temperature 1.0, top_p 0.95, n 1, presence_penalty / frequency_penalty 0. 공식 권장 사항은 요청에서 이 파라미터들을 생략하는 것입니다.

참고: 고정된 샘플링 값은 공식 사양의 일부이며 응답 신호로는 검증할 수 없습니다. 공식 권장 사항에 따라 이 파라미터들을 생략하세요.

4. 도구 호출과 동적 도구 로딩

tools는 최대 128개의 도구를 지원하며, tool_choice는 도구 호출 강제 및 비활성화를 지원합니다. K3는 동적 도구 로딩도 지원합니다. 시스템 메시지의 tools 필드(Chat API에만 해당하는 메시지 형태)를 통해 대화 중간에 새 도구를 주입할 수 있습니다.
Chat Completions

tool_choice는 auto / none / required를 지원하며, required는 모델이 반드시 도구를 호출하도록 강제합니다. 동적 도구 로딩의 경우, 도구를 주입하는 시스템 메시지에는 content가 없고, 주입된 도구는 이후 턴부터 적용되며, 해당 메시지는 모든 요청에 다시 포함해야 합니다.

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello."},
    {"role": "assistant", "content": "Hi, how can I help you?"},
    # Inject a new tool mid-conversation: tools field only, no content
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "Get the current time",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "What time is it now?"},
]

# tool_choice="required" with prompt "Hello" -> the model is forced to call the tool
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]

검증됨: tool_choice: "required"는 관련 없는 프롬프트에서도 도구 호출을 강제합니다. "none"은 도구 호출을 억제합니다. content 없이 시스템 메시지로 대화 중에 주입된 도구도 정상적으로 호출할 수 있습니다.
Responses

도구 정의는 평면 구조를 사용합니다(name이 최상위에 위치). 호출을 강제할 때도 마찬가지로 tool_choice: "required"를 사용하며, 호출은 function_call 출력 항목으로 반환됩니다. 동적 도구 로딩 지원은 개발 중입니다. 현재는 모든 도구를 최상위 tools 파라미터에 선언하세요.

response = client.responses.create(
    model="kimi-k3",
    input="Hello",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# Observed output contains: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}

Messages

도구는 Anthropic 형식(input_schema)을 사용합니다. 호출을 강제하려면 tool_choice: {"type": "any"}를, 호출을 비활성화하려면 {"type": "none"}을 사용하세요. ❗ Kimi K3의 공식 Messages(Anthropic 호환) 엔드포인트는 동적 도구 로딩을 지원하지 않습니다: 테스트에서 주입 메시지는 200을 반환했지만 주입된 도구는 효과가 없었습니다(모델이 해당 도구를 호출할 수 없었습니다). 모든 도구를 최상위 tools 파라미터에 선언하세요.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "Get weather for a city",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "Hello"}],
)

# Observed: stop_reason "tool_use"; content contains a tool_use block calling get_weather

5. 구조화된 출력

구조화된 출력은 모델이 주어진 JSON Schema를 엄격히 따르는 내용을 반환하도록 합니다.
Chat Completions

response_format은 strict 모드와 함께 json_schema를 지원합니다.

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Paris is the capital of France. Extract the city name."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# Observed response content: {"city":"Paris"}

검증됨: 출력이 스키마를 따르는 유효한 JSON입니다.
Responses

구조화된 출력은 text.format으로 선언합니다.

response = client.responses.create(
    model="kimi-k3",
    input="Paris is the capital of France. Extract the city name.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# Observed output text: {"city":"Paris"}

Messages

❗ Kimi K3의 공식 Messages(Anthropic 호환) 엔드포인트는 구조화된 출력을 지원하지 않습니다: 구조화된 출력 필드가 조용히 무시되어, 요청은 HTTP 200으로 자유 형식 텍스트를 반환하며 오류나 대체 안내는 없습니다. 이로 인해 다운스트림 JSON 파싱이 실패합니다. 구조화된 출력이 필요하다면 Chat Completions 또는 Responses API를 사용하세요.

6. 컨텍스트 캐싱은 자동

K3의 컨텍스트 캐싱은 자동으로 활성화되며 별도의 파라미터가 필요하지 않습니다. 반복되는 긴 프리픽스가 캐시에 적중하면, 적중한 양이 usage에 보고됩니다(필드 이름은 API마다 다릅니다). 캐시 요금은 모델 페이지에서 확인할 수 있습니다.
Chat Completions

# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 1536}

검증됨: 동일한 긴 프리픽스를 가진 두 번째 요청에서 적중 내역이 usage.prompt_tokens_details.cached_tokens에 보고됩니다.
Responses

# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}

Messages

# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536

7. partial 프리픽스 완성

프리픽스 완성은 모델이 주어진 프리픽스에서 이어서 생성하도록 하며, 코드 완성과 형식이 정해진 출력에 적합합니다.
Chat Completions

마지막 assistant 메시지에 "partial": true를 전달하세요.

messages = [
    {"role": "user", "content": "Write a haiku about the sea."},
    {"role": "assistant", "content": "Waves fold into foam,", "partial": True},
]

# Prefix: "Waves fold into foam,"  ->  continuation returned by the model
# salt hangs in the air—
# moon pulls the tide home.

검증됨: 주어진 프리픽스를 반복하지 않고 그 뒤에서 생성이 이어집니다.
Responses

프리픽스는 input 배열 끝에 assistant 메시지로 전달하세요. partial 파라미터는 필요하지 않습니다.

response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "Write a haiku about the sea."},
        {"role": "assistant", "content": "Waves fold into foam,"},
    ],
)

# Observed continuation: "salt hangs in the air— / moon pulls the tide home."

Messages

같은 기능을 partial 파라미터 없이 프로토콜 고유의 assistant prefill로 구현할 수 있습니다. 프리픽스를 마지막 assistant 메시지로 전달하세요.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Write a haiku about the sea."},
        {"role": "assistant", "content": "Waves fold into foam,"},
    ],
)

# Observed continuation: "salt wind carries the gull's cry— / tide pulls ..."

8. 비전 입력

이미지는 base64로 전달하며, 콘텐츠 블록 형식은 API마다 다릅니다.
Chat Completions

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is the dominant color of this image? One word."},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
        ],
    }
]

# Observed response content: "Red"  (input: a 64x64 solid red PNG)

검증됨: base64 이미지 입력이 작동하며, 모델이 테스트 이미지를 올바르게 설명합니다.
Responses

input = [
    {
        "role": "user",
        "content": [
            {"type": "input_text", "text": "What is the dominant color of this image? One word."},
            {"type": "input_image", "image_url": "data:image/png;base64,<BASE64>"},
        ],
    }
]

# Observed output text: "Red"

Messages

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What is the dominant color of this image? One word."},
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<BASE64>"}},
        ],
    }
]

# Observed response text: "Red"

9. 검증된 참고 자료: 긴 단일 호출 작업의 지연 시간과 사용량

K3의 사고는 max 수준으로 고정되어 있으므로, 복잡한 작업에 대한 단일 요청은 일반적인 모델보다 상당히 오래 걸립니다. 단일 파일 HTML 게임 생성 작업(참고 이미지가 포함된 프롬프트 하나로 반복 없이 한 번에 생성)의 측정 데이터는 다음과 같습니다. 단일 요청에 2,541초(약 42분)가 걸렸고, 완성 토큰은 74,994개였으며, 그중 54,486개(73%)가 사고 토큰이었습니다. 최종 출력은 바로 실행 가능한 코드 1,275줄이었고, finish_reason은 stop이었습니다.

클라이언트 측 권장 사항:

• 클라이언트 타임아웃을 몇 분 이상으로 설정하고, 긴 작업에는 스트리밍을 우선 사용하세요.
• max_completion_tokens에 충분한 여유를 두세요. 이 경우 사고만으로 54,486개의 토큰이 소모되었습니다.

10. 기능 × API 지원 매트릭스

아래 표의 모든 셀은 2026-07-17에 AIHubMix 운영 API를 실제로 호출하여 검증했으며, 각 셀은 해당 API의 파라미터 / 필드 문법을 보여줍니다.

FAQ

K3는 AIHubMix에서 어떤 API를 지원하나요?
Chat Completions(/v1/chat/completions), Responses(/v1/responses), Claude 호환 Messages API(/v1/messages)를 지원합니다.

사고 기능을 끄거나 낮출 수 있나요?
아니요. K3의 사고 기능은 기본적으로 켜져 있으며, reasoning_effort는 단일 "max" 수준만 지원합니다.

다중 턴 대화에서 왜 reasoning_content를 다시 전달해야 하나요?
K3는 보존된 사고(preserved thinking) 방식으로 학습되었으며, Moonshot은 이전 assistant 메시지를 수정하지 않고 완전한 형태로 다시 전달할 것을 요구합니다. 사고 이력이 빠지면 출력 품질이 불안정해집니다.

stop 파라미터에는 어떤 제한이 있나요?
stop 시퀀스는 최대 5개까지 가능하며, 각각 32바이트를 넘을 수 없습니다. 어느 한도든 초과하면 400 오류가 반환됩니다.

Messages API는 구조화된 출력을 지원하나요?
❗ 아니요. Kimi K3의 공식 Messages(Anthropic 호환) 엔드포인트는 구조화된 출력 필드를 조용히 무시합니다(오류 없이 200을 반환하며 자유 형식 텍스트가 나옴). 구조화된 출력이 필요하면 Chat Completions에서는 response_format을, Responses에서는 text.format을 사용하세요.

K3 단일 요청은 왜 이렇게 오래 걸리나요?
K3의 사고(thinking)는 최대 수준으로 고정되어 있으며, 복잡한 작업에서는 사고 토큰이 전체 completion 토큰의 큰 비중을 차지합니다(측정 사례에서는 73%). 클라이언트 타임아웃을 몇 분 이상으로 설정하고 스트리밍을 사용하세요.

가격 및 실시간 상태는 Kimi K3 모델 페이지에서 확인할 수 있으며, 더 많은 모델은 모델 갤러리를 방문하세요.

최종 업데이트: 2026-07-17