> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Kimi K3 실측 호출 가이드: 새 파라미터와 3개 인터페이스 지원 매트릭스
> 2026년 7월 Kimi K3 호출 가이드: reasoning_effort max, 사고 히스토리 회신, 동적 도구 로딩, 구조화된 출력, 자동 캐시, partial 접두사 이어쓰기, 비전 입력. AIHubMix 3개 인터페이스 예제 포함.
> 이 글은 [Kimi K3](https://aihubmix.com/model/kimi-k3)의 새 파라미터와 호출 시 유의 사항을 소개합니다. K3는 AIHubMix에서 Chat Completions, Responses 및 Claude 호환 Messages 인터페이스로 호출할 수 있습니다. 참고 자료: [Moonshot 공식 플랫폼 문서](https://platform.moonshot.ai/docs).
>
> 각 절의 「실측」 결론과 예시 응답은 모두 2026-07-17에 AIHubMix 인터페이스(Chat Completions / Responses / Messages)를 통해 실제 호출한 결과입니다.
## 1. 모델 사양 요약
| 항목 | 값 |
| :------- | :------------------------------------------------ |
| 컨텍스트 윈도우 | 1M tokens |
| 최대 출력 | `max_completion_tokens` 기본값 131,072, 최대 1,048,576 |
| 입력 모달리티 | 텍스트, 이미지(비디오 입력은 Moonshot 공식 문서 참조) |
| 사고 모드 | 기본 활성화, `reasoning_effort`는 `"max"`만 지원 |
| 정지 시퀀스 | `stop` 최대 5개, 각 32바이트 이하 |
> **실측**: `stop`의 두 상한 모두 검증되며, 초과 시 400을 반환합니다. Messages 인터페이스의 `stop_sequences`도 동일한 검증을 수행합니다.
>
> ❗ **Messages 인터페이스에서 정지 시퀀스에 도달해도 Anthropic 의미론대로 반환되지 않습니다**: 실측 결과 `stop_reason`은 `"end_turn"`(`"stop_sequence"`가 아님), `stop_sequence`는 `null`이며, 정지 시퀀스 이전의 가시 텍스트가 비어 있을 수 있습니다. 이 두 필드로 잘림 원인을 판단하는 클라이언트는 주의가 필요합니다.
```text theme={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 메시지를(사고 내용 포함) **원본 그대로 완전하게** 다시 전달해야 합니다. 사고 히스토리가 누락되면 출력 품질이 불안정해집니다. 대화 관리 프레임워크나 프록시 계층을 사용하는 경우, 다시 전달하기 전에 사고 내용이 잘리지 않았는지 확인하세요.
사고 내용은 응답의 `reasoning_content` 필드로 반환됩니다. 멀티턴 시 이전 턴의 assistant 메시지(`reasoning_content` 포함)를 원본 그대로 다시 전달하세요.
```text theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
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)
```
```text theme={null}
# 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": ""},
{"role": "user", "content": "And its population?"},
]
```
> **실측**: 응답에서 `reasoning_content`가 반환됩니다. 이전 턴의 assistant 메시지(`reasoning_content` 포함)를 원본 그대로 다시 전달하면 이후 턴이 정상적으로 응답합니다.
사고 내용은 `reasoning` 출력 항목으로 반환됩니다. 멀티턴 시 이전 턴의 출력 항목(`reasoning` + `message`)을 원본 그대로 `input`에 이어 붙이세요.
```text theme={null}
from openai import OpenAI
client = OpenAI(
base_url="https://aihubmix.com/v1",
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"
```
사고 내용은 네이티브 `thinking` 콘텐츠 블록으로 반환됩니다. 멀티턴 시 이전 턴 assistant의 콘텐츠 블록(thinking 블록 포함)을 원본 그대로 다시 전달하세요.
```text theme={null}
from anthropic import Anthropic
client = Anthropic(
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는 동적 도구 로딩도 지원합니다: 대화 도중 system 메시지의 `tools` 필드로 새 도구를 주입할 수 있습니다(Chat 인터페이스 고유의 메시지 형태).
`tool_choice`는 `auto` / `none` / `required`를 지원하며, `required`는 모델이 도구를 호출하도록 강제합니다. 동적 도구 로딩: 도구를 주입하는 system 메시지는 `content`를 포함하지 않고, 주입된 도구는 이후 턴에 적용되며, 매 턴 요청마다 반복해서 포함해야 합니다.
```text theme={null}
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?"},
]
```
```text theme={null}
# 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` 없는 system 메시지로 도중 주입한 도구는 정상적으로 호출됩니다.
도구 정의는 평탄한 구조(`name`이 최상위)이며, 강제 호출은 동일하게 `tool_choice: "required"`를 사용하고, 호출은 `function_call` 출력 항목으로 반환됩니다. 동적 도구 로딩은 지원 예정이므로, 현재는 최상위 `tools` 파라미터에 모든 도구를 선언하세요.
```text theme={null}
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\"}"}
```
도구는 Anthropic 형식(`input_schema`)을 사용하며, 강제 호출은 `tool_choice: {"type": "any"}`, 비활성화는 `{"type": "none"}`입니다. ❗ **Kimi K3 공식 Messages(Anthropic 호환) 엔드포인트는 동적 도구 로딩을 지원하지 않습니다**: 실측 결과 주입 메시지는 200을 반환하지만 주입된 도구는 작동하지 않으므로(모델이 호출할 수 없음), 최상위 `tools` 파라미터에 모든 도구를 선언하세요.
```text theme={null}
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에 엄격히 부합하는 내용을 반환합니다.
`response_format`은 `json_schema`와 `strict` 모드를 지원합니다.
```text theme={null}
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"}
```
> **실측**: 출력은 schema에 부합하는 유효한 JSON입니다.
구조화된 출력은 `text.format`으로 선언합니다.
```text theme={null}
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"}
```
❗ **Kimi K3 공식 Messages(Anthropic 호환) 엔드포인트는 구조화된 출력을 지원하지 않습니다**: 구조화된 출력 필드는 조용히 무시됩니다. 요청은 HTTP 200과 자유 텍스트를 반환하며 오류나 다운그레이드 안내가 전혀 없어, 다운스트림 JSON 파싱이 실패합니다. 구조화된 출력이 필요하면 Chat Completions 또는 Responses 인터페이스를 사용하세요.
## 6. 컨텍스트 캐시 자동 활성화
K3의 컨텍스트 캐시는 자동으로 활성화되며 어떤 파라미터도 전달할 필요가 없습니다. 반복되는 긴 접두사가 캐시에 히트하면 히트량이 usage에 보고됩니다(필드명은 인터페이스마다 다름). 캐시 가격은 [모델 페이지](https://aihubmix.com/model/kimi-k3)를 참조하세요.
```text theme={null}
# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 1536}
```
> **실측**: 동일한 긴 접두사의 두 번째 요청에서 `usage.prompt_tokens_details.cached_tokens`에 히트가 보고됩니다.
```text theme={null}
# usage of the second Responses call with identical long instructions
"input_tokens_details": {"cached_tokens": 1536}
```
```text theme={null}
# usage of the second Messages call with an identical long system prompt
"cache_read_input_tokens": 1536
```
## 7. `partial` 접두사 이어쓰기
접두사 이어쓰기는 주어진 접두사에서 이어서 생성하는 기능으로, 코드 자동 완성과 형식이 제어된 출력에 적합합니다.
마지막 assistant 메시지에 `"partial": true`를 전달합니다.
```text theme={null}
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.
```
> **실측**: 생성이 주어진 접두사에서 이어지며, 접두사를 반복하지 않습니다.
접두사를 `input` 배열 끝의 assistant 메시지로 전달하며, `partial` 파라미터는 필요 없습니다.
```text theme={null}
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."
```
프로토콜 네이티브의 assistant 프리필로 동등한 기능을 구현하며, `partial` 파라미터는 필요 없습니다. 접두사를 마지막 assistant 메시지로 전달하면 됩니다.
```text theme={null}
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로 전달하며, 콘텐츠 블록 작성 방식은 인터페이스마다 다릅니다.
```text theme={null}
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,"}},
],
}
]
# Observed response content: "Red" (input: a 64x64 solid red PNG)
```
> **실측**: base64 이미지 입력이 작동하며, 모델이 테스트 이미지 내용을 정확히 설명합니다.
```text theme={null}
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,"},
],
}
]
# Observed output text: "Red"
```
```text theme={null}
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": ""}},
],
}
]
# Observed response text: "Red"
```
## 9. 실측 참고: 장시간 작업 단일 호출의 소요 시간과 사용량
K3의 사고는 max 단계로 고정되어 있어, 복잡한 작업의 단일 요청 소요 시간이 일반 모델보다 현저히 깁니다. 단일 파일 HTML 게임 생성 작업(단일 prompt에 참고 이미지 첨부, 1회 생성, 반복 없음)의 실측 데이터: 단일 요청 소요 시간 2,541초(약 42분), completion tokens 74,994, 그중 사고 부분 54,486으로 73% 차지, 최종적으로 한 번에 바로 실행 가능한 1,275줄의 코드를 산출했으며 `finish_reason`은 `stop`이었습니다.
호출 측 권장 사항:
* 클라이언트 타임아웃은 분 단위 이상으로 설정하고, 장시간 작업은 스트리밍 반환을 우선 사용하세요.
* `max_completion_tokens`에 충분한 여유를 두세요. 이 사례에서는 사고만으로 54,486 tokens를 소비했습니다.
## 10. 기능 × 인터페이스 지원 매트릭스
아래 표의 각 칸은 모두 2026-07-17에 AIHubMix 라이브 인터페이스를 통해 실제 호출로 검증한 결과이며, 칸 안은 해당 인터페이스의 파라미터 / 필드 작성 방식입니다.
| 기능 | Chat Completions | Responses | Messages |
| :-------------- | :-------------------------------------------- | :------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| 사고 내용 반환 | ✅ `reasoning_content` 필드 | ✅ `reasoning` 출력 항목 | ✅ `thinking` 콘텐츠 블록 |
| 사고 히스토리 회신 | ✅ assistant 메시지 원본 그대로 회신 | ✅ 출력 항목 원본 그대로 회신 | ✅ 콘텐츠 블록 원본 그대로 회신 |
| 도구 호출 강제 / 비활성화 | ✅ `tool_choice: "required"` / `"none"` | ✅ `tool_choice: "required"` | ✅ `{"type": "any"}` / `{"type": "none"}` |
| 동적 도구 로딩 | ✅ system 메시지에 `tools` 포함(`content` 없음) | ➖ 지원 예정 | ❗ 공식 Messages(Anthropic 호환) 엔드포인트 미지원 |
| 구조화된 출력 | ✅ `response_format`(json\_schema + strict) | ✅ `text.format`(json\_schema) | ❗ 공식 엔드포인트 미지원, 필드가 **조용히 무시됨**(200 + 자유 텍스트), Chat / Responses 사용 권장 |
| 자동 캐시 히트 계측 | ✅ `usage.prompt_tokens_details.cached_tokens` | ✅ `usage.input_tokens_details.cached_tokens` | ✅ `usage.cache_read_input_tokens` |
| 접두사 이어쓰기 | ✅ `"partial": true` | ✅ assistant 프리필 | ✅ assistant 프리필(프로토콜 네이티브) |
| 비전 입력 | ✅ `image_url`(base64) | ✅ `input_image`(base64) | ✅ `image` 콘텐츠 블록(base64) |
| 정지 시퀀스 | ✅ `stop`(상한 검증) | ➖ 지원 예정 | ❗ `stop_sequences` 상한 검증은 동일하나, 도달 시 `stop_reason: "stop_sequence"` / `stop_sequence` 값을 반환하지 않음 |
## 자주 묻는 질문(FAQ)
**K3는 AIHubMix에서 어떤 인터페이스를 지원합니까?**
Chat Completions(`/v1/chat/completions`), Responses(`/v1/responses`) 및 Claude 호환 Messages(`/v1/messages`)입니다.
**사고를 비활성화하거나 사고 강도를 낮출 수 있습니까?**
불가능합니다. K3의 사고는 기본 활성화되어 있으며, `reasoning_effort`는 `"max"` 한 단계만 지원합니다.
**멀티턴 대화에서 왜 `reasoning_content`를 다시 전달해야 합니까?**
K3는 preserved thinking 방식으로 학습되어, 공식적으로 이전 턴의 assistant 메시지를 원본 그대로 완전하게 다시 전달하도록 요구합니다. 사고 히스토리가 누락되면 출력 품질이 불안정해집니다.
**`stop` 파라미터에는 어떤 제한이 있습니까?**
최대 5개의 정지 시퀀스, 각 32바이트 이하이며, 초과 시 400 오류를 반환합니다.
**Messages 인터페이스는 구조화된 출력을 지원합니까?**
❗ 지원하지 않습니다. Kimi K3 공식 Messages(Anthropic 호환) 엔드포인트는 구조화된 출력 필드를 조용히 무시합니다(200과 자유 텍스트 반환, 오류 없음). 구조화된 출력이 필요하면 Chat Completions의 `response_format` 또는 Responses의 `text.format`을 사용하세요.
**K3의 단일 요청은 왜 시간이 오래 걸립니까?**
K3의 사고는 max 단계로 고정되어 있어, 복잡한 작업에서 사고 token 비중이 높습니다(실측 사례에서 completion tokens의 73% 차지). 클라이언트 타임아웃을 분 단위 이상으로 설정하고 스트리밍 반환을 사용하는 것을 권장합니다.
***
모델 가격과 실시간 상태는 [Kimi K3 모델 페이지](https://aihubmix.com/model/kimi-k3)를, 더 많은 모델은 [모델 광장](https://aihubmix.com/models)을 참조하세요.
업데이트: 2026-07-17