Kimi K3는 모델 ID kimi-k3를 사용하는 Moonshot AI의 OpenAI 호환 Chat Completions API를 통해 사용할 수 있습니다. 이 API는 상시 추론, 스트리밍, 이미지, 업로드된 동영상, 엄격한 JSON Schema, 사용자 지정 도구, 동적 도구 로딩, 100만 토큰 컨텍스트 윈도우를 지원합니다.
호환된다고 해서 동작이 완전히 동일한 것은 아닙니다. K3는 샘플링 값이 고정되어 있고, 이후 도구 호출 및 대화 턴에서 완전한 assistant 상태를 요구하며, 추론과 최종 콘텐츠를 별도로 처리합니다. 이 가이드에서는 이러한 세부 사항에 초점을 맞춥니다.
2026년 7월 22일 제공 상태 및 가격 업데이트. Kimi K3는 Poyo.ai에서
kimi-k3모델 ID와 OpenAI 호환 Chat Completions API로 사용할 수 있습니다. 가격은 입력 100만 토큰당 $2.28, 출력 100만 토큰당 $11.40으로 공식 가격보다 24% 저렴합니다.
요구 사항
다음이 필요합니다.
- Python 3.9 이상
openaiPython 패키지 버전 1.0 이상- 소스 코드 관리 시스템 외부에 저장된 Moonshot API 키
- 기본 URL
https://api.moonshot.ai/v1 - 모델 ID
kimi-k3
SDK를 설치합니다.
python -m pip install --upgrade "openai>=1.0"
셸에서 키를 설정합니다.
export MOONSHOT_API_KEY="your-key"
PowerShell에서는 다음과 같이 설정합니다.
$env:MOONSHOT_API_KEY="your-key"
프로덕션 키를 코드 예제, 클라이언트 측 번들, 로그 또는 저장소에 절대 포함하지 마세요.
첫 Kimi K3 요청 보내기
Python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.ai/v1",
)
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{"role": "user", "content": "Review this migration plan and list its three highest risks."}
],
)
print(response.choices[0].message.content)
cURL
curl https://api.moonshot.ai/v1/chat/completions \
-H "Authorization: Bearer $MOONSHOT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3",
"messages": [
{"role": "user", "content": "Explain Kimi Delta Attention in plain language."}
]
}'
추론 수준 구성하기
K3는 항상 사고 모드를 사용합니다. 최상위 reasoning_effort 필드를 통해 추론 수준을 구성할 수 있습니다.
response = client.chat.completions.create(
model="kimi-k3",
reasoning_effort="high",
messages=[
{"role": "user", "content": "Find the flaw in this distributed lock design."}
],
)
지원되는 값은 다음과 같습니다.
| 값 | 용도 |
|---|---|
low | 지연 시간과 출력량이 중요한 비교적 쉬운 작업 |
high | 어려운 코딩, 분석 및 도구 계획 |
max | 가장 어려운 작업과 벤치마크 방식의 평가 |
문서에 명시된 기본값은 max입니다. 이를 가장 저렴한 프로덕션 설정이라고 가정하지 마세요. 각 추론 수준에서 성공률, 지연 시간 및 생성 토큰 수를 평가하세요.
추론과 최종 콘텐츠 스트리밍하기
스트리밍 응답에서는 서로 다른 delta 필드를 통해 추론과 최종 텍스트가 별도로 노출됩니다.
stream = client.chat.completions.create(
model="kimi-k3",
messages=[{"role": "user", "content": "Review this architecture for race conditions."}],
stream=True,
)
for chunk in stream:
delta = chunk.choices[0].delta
reasoning = getattr(delta, "reasoning_content", None)
if reasoning:
# Store or process according to your product and provider policies.
pass
if delta.content:
print(delta.content, end="", flush=True)
사용자에게 보여주는 최종 콘텐츠와 내부 처리를 분리하세요. reasoning_content에서 구조화된 출력을 파싱하지 마세요.
Kimi K3에 이미지 보내기
K3 비전 메시지는 콘텐츠 객체 배열을 사용합니다. 이 방식에서는 공개 이미지 URL을 지원하지 않으므로 로컬 이미지를 base64로 인코딩하세요.
import base64
from pathlib import Path
image_data = base64.b64encode(Path("interface.png").read_bytes()).decode()
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {"url": f"data:image/png;base64,{image_data}"},
},
{
"type": "text",
"text": "Identify the three largest accessibility problems in this interface.",
},
],
}
],
)
사용자가 업로드한 파일을 인코딩하기 전에 파일 형식과 크기를 검증하세요. base64 페이로드를 로그에 기록하지 마세요.
Kimi K3에 동영상 보내기
Files API를 통해 동영상을 업로드하고, 반환된 ID를 ms:// 스킴으로 참조한 다음 더 이상 필요하지 않을 때 파일을 삭제하세요.
from pathlib import Path
video = client.files.create(file=Path("demo.mp4"), purpose="video")
try:
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{
"role": "user",
"content": [
{
"type": "video_url",
"video_url": {"url": f"ms://{video.id}"},
},
{"type": "text", "text": "Summarize the workflow and identify failed steps."},
],
}
],
)
finally:
client.files.delete(video.id)
엄격한 JSON Schema 출력 반환하기
다운스트림 코드에서 예측 가능한 구조가 필요하다면 strict: true를 사용하세요.
import json
response = client.chat.completions.create(
model="kimi-k3",
messages=[
{"role": "user", "content": "Extract the risk, severity, and owner from this incident note."}
],
response_format={
"type": "json_schema",
"json_schema": {
"name": "incident_risk",
"strict": True,
"schema": {
"type": "object",
"properties": {
"risk": {"type": "string"},
"severity": {"type": "string", "enum": ["low", "medium", "high"]},
"owner": {"type": ["string", "null"]},
},
"required": ["risk", "severity", "owner"],
"additionalProperties": False,
},
},
},
)
result = json.loads(response.choices[0].message.content or "{}")
최종 message.content만 파싱한 다음, 애플리케이션 코드에서 다시 검증하세요.
사용자 지정 도구 호출하기
첫 번째 응답에서는 하나 이상의 도구를 요청할 수 있습니다. 허용된 각 호출을 실행하고, 완전한 assistant 메시지를 추가한 다음, 각 tool_call_id에 대응하는 도구 결과를 하나씩 추가하세요.
import json
tools = [
{
"type": "function",
"function": {
"name": "get_build_status",
"description": "Return the current build status for an allowed project.",
"parameters": {
"type": "object",
"properties": {"project": {"type": "string"}},
"required": ["project"],
"additionalProperties": False,
},
},
}
]
messages = [{"role": "user", "content": "Check the web build and summarize any failure."}]
first = client.chat.completions.create(
model="kimi-k3",
messages=messages,
tools=tools,
tool_choice="required",
)
assistant_message = first.choices[0].message
messages.append(assistant_message)
for call in assistant_message.tool_calls or []:
arguments = json.loads(call.function.arguments)
# Authorize and validate before executing a real tool.
tool_result = {"project": arguments["project"], "status": "passed"}
messages.append(
{
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(tool_result),
}
)
final = client.chat.completions.create(
model="kimi-k3",
messages=messages,
tools=tools,
)
권한 경계, 입력 검증, 범위가 제한된 환경 및 감사 추적 없이 모델이 생성한 임의의 셸 명령을 절대 실행하지 마세요.
도구 동적으로 로드하기
K3는 도구를 사용할 수 있게 되는 시점에 완전한 도구 정의를 system 메시지에 포함하는 방식을 지원합니다. 이후 기록에도 해당 메시지를 유지하세요. 서버가 대신 보관해 주지 않습니다.
동적 로딩을 사용하면 대규모 에이전트 시스템에서 매 턴마다 모든 도구 스키마를 전송하지 않아도 됩니다. 동시에 새로운 상태 관리 요구 사항도 생깁니다. 이후 도구 결과를 해석할 때 모델이 정확한 선언을 볼 수 있어야 합니다.
100만 토큰 컨텍스트 윈도우 사용하기
대규모 컨텍스트는 서로 멀리 떨어진 증거를 함께 추론해야 할 때 가장 큰 가치를 발휘합니다. 다음과 같이 의도적으로 사용하세요.
- 안정적인 저장소 또는 문서 코퍼스를 앞부분에 유지합니다.
- 접두부를 다시 작성하지 말고 질문과 결과를 추가합니다.
- 캐시된 입력과 캐시되지 않은 입력을 별도로 추적합니다.
- 전체 코퍼스가 필요하지 않다면 더 작은 하위 집합을 검색합니다.
- 최종 답변을 검증할 수 있도록 소스 식별자를 설정합니다.
- 클라이언트가 K3에 필요한 모든 상태를 보존할 때만 압축합니다.
자동 캐싱에는 cache ID나 일반적인 TTL 매개변수가 없습니다. 안정적인 접두부를 유지하면 서비스가 캐시를 적중할 가능성을 가장 높일 수 있습니다.
완전한 멀티턴 상태 유지하기
이것이 K3에 특화된 통합 규칙 중 가장 중요합니다.
대화를 이어가거나 도구 결과를 반환할 때는 API가 반환한 완전한 assistant 메시지를 추가하세요. content만 보관하지 마세요. Moonshot은 K3가 보존된 사고 기록을 기반으로 학습되었으며, 하네스가 필요한 기록을 삭제하거나 세션 중간에 K3로 전환하면 불안정해질 수 있다고 경고합니다.
대화 상태를 안전하게 저장하고, 보존 기간을 제한하며, 해당 상태를 볼 권한이 없는 사용자에게 숨겨진 상태가 노출되지 않도록 하세요.
Kimi K3 API의 주요 제한 사항
- K3는 항상 사고 기능이 활성화되어 있습니다.
reasoning_effort는low,high,max를 지원합니다.max_completion_tokens의 기본값은 131,072이며 최대 1,048,576까지 설정할 수 있습니다.temperature=1.0,top_p=0.95,n=1,presence_penalty=0,frequency_penalty=0은 고정되어 있으므로 생략하세요.- 비전 메시지에서는 공개 이미지 URL을 지원하지 않습니다.
- 멀티턴 및 도구 요청에서는 완전한 assistant 메시지를 보존해야 합니다.
- Moonshot은 웹 검색 도구를 업데이트 중이며 현재 프로덕션 사용에는 권장하지 않는다고 밝혔습니다.
프로덕션 체크리스트
- API 키는 서버 측에 보관합니다.
- 요청 타임아웃과 제한된 재시도를 추가합니다.
- 도구 인자를 검증하고 모든 작업에 권한을 부여합니다.
- 도구 호출 턴 수와 완료 길이를 제한합니다.
- 완전한 K3 assistant 상태를 보존합니다.
- 생성 후 엄격한 JSON을 검증합니다.
- 입력, 캐시된 입력, 출력, 지연 시간 및 오류를 기록합니다.
- K3 세션 중간에 모델을 전환하지 않습니다.
- 과도한 선제적 동작을 줄일 수 있도록 명시적인 행동 경계를 추가합니다.
- 고장 난 도구, 부분 응답 및 긴 대화 기록으로 테스트합니다.
컨텍스트와 출력 제한을 선택하기 전에 Kimi K3 API 가격을 확인하세요. Poyo.ai에서의 제공 여부는 Kimi K3 모델 페이지를 확인하세요.
자주 묻는 질문
Kimi K3 API는 OpenAI와 호환되나요?
예. Moonshot은 OpenAI 호환 Chat Completions 엔드포인트를 제공합니다. 다만 K3 고유의 상태, 추론, 샘플링 및 미디어 규칙은 여전히 적용됩니다.
Kimi K3의 모델 ID는 무엇인가요?
공식 Moonshot API 모델 ID는 kimi-k3입니다.
Kimi K3는 함수 호출을 지원하나요?
예. 사용자 지정 도구, 필수 도구 선택, 대응하는 도구 결과 및 동적 도구 로딩을 지원합니다.
Kimi K3는 동영상을 처리할 수 있나요?
예. Files API를 통해 동영상을 업로드한 다음, 동영상 콘텐츠 객체에서 해당 ms:// 파일 ID를 참조하세요.
100만 토큰 컨텍스트 윈도우는 어떻게 사용하나요?
표준 모델 요청을 통해 필요한 메시지와 콘텐츠를 보내고, 자동 캐싱을 위해 안정적인 접두부를 변경하지 않으며, 완료 길이에 제한을 설정하세요.