Kimi K3 API 가이드: 컨텍스트, 비용, 에이전트 루프 및 출시

빠른 답변

Moonshot AI는 2026년 7월 16일에 새로운 플래그십 모델로 Kimi K3를 출시했습니다. 공식 제품 및 API 인터페이스는 현재 Kimi, Kimi Work, Kimi Code, 그리고 Kimi API로 이용 가능합니다. API 모델 이름은 kimi-k3입니다.

주요 사양은 상당합니다: 총 2.8조 개의 파라미터 (parameters), 네이티브 비전 (native vision), 100만 토큰의 컨텍스트 윈도우 (context window), 그리고 896개의 전문가 중 16개를 활성화하는 아키텍처를 갖추고 있습니다. 하지만 독립 개발자에게는 파라미터 수보다 두 가지 출시 경계 조건이 더 중요합니다:

• K3는 항상 사고 모드 (thinking mode)를 사용합니다. reasoning_effort는 low, high, max를 지원하며, max가 기본값입니다.
• Moonshot은 7월 27일까지 전체 모델 가중치 (model weights)가 제공될 것이라고 밝혔습니다. 가중치와 기술 보고서 (technical report)가 실제로 사용 가능해질 때까지, K3를 오늘 바로 검증할 수 있는 셀프 호스팅 (self-hosting) 옵션이 아닌, API 및 호스팅 제품 출시로 취급하십시오.

K3는 장기적인 코딩, 멀티모달 엔지니어링 (multimodal engineering), 그리고 에이전트 기반 지식 작업 (agentic knowledge work)을 위한 합리적인 카나리 (canary) 모델입니다. 일상적인 리포지토리 (repository) 작업에 대해 Kimi K2.7 Code를 자동으로 대체해서는 안 됩니다. K3는 더 큰 컨텍스트와 더 높은 능력 상한선을 가지고 있지만, 비용이 실질적으로 더 많이 들고 더 엄격한 히스토리 처리 요구 사항을 부과합니다.

이 가이드의 대상

이 가이드는 Kimi K3를 AI 코딩 도구, 연구 워크플로, 문서 에이전트, 또는 멀티 툴 애플리케이션에 추가할지 결정하려는 개발자를 위한 것입니다. 출시 벤치마크를 반복하기보다는 API 계약 (API contract)과 출시 리스크에 초점을 맞춥니다.

여러 프런티어 모델 (frontier models)을 비교 중이라면, 이 가이드를 Grok 4.5 코딩 에이전트 평가 체크리스트 및 GPT-5.6 모델 라우팅 가이드와 함께 사용하십시오. 만약 귀하의 에이전트가 리포지토리 명령을 실행한다면, 모델의 품질과 관계없이 신뢰할 수 없는 리포지토리 샌드박스 게이트를 유지하십시오.

변경된 사항 — 그리고 아직 보류 중인 사항

Kimi K3는 네 가지 별도의 인터페이스(Surfaces)를 통해 이용 가능합니다:

작업에 따라 K3, K2.7 Code 또는 K2.6 선택하기

1M 컨텍스트 창을 열기 전에 작업 비용 계산하기

백만 토큰당 공식 종량제(Pay-as-you-go) 가격은 다음과 같습니다:

캐싱(Caching)은 자동으로 이루어지지만, 이전 프롬프트가 256 토큰을 초과해야 하며 재사용 가능한 접두사가 변경되지 않은 상태로 유지되어야 합니다. 1M 컨텍스트 창은 컨텍스트 길이 가격 계층(Context-length price tier)을 제거하는 것이지, 긴 프롬프트를 무료로 만드는 것이 아닙니다. 캐시 히트, 입력, 추론/출력, 재시도(Retries), 도구 라운드(Tool rounds), 실제 소요 시간(Wall time), 그리고 수락된 작업당 비용을 기록하십시오.

가장 작고 정확한 API 호출로 시작하기

import os
from openai import OpenAI

...

제한된 분류 (triage) 작업에는 low로 시작하고, high 또는 max를 사용했을 때 지연 시간(latency)과 출력 비용을 정당화할 만큼 수락률(acceptance)이 충분히 개선되는 경우에만 업그레이드하세요. K3는 temperature 및 top-p와 같은 샘플링 설정(sampling settings)을 고정하므로, 이전 제공자(provider)의 설정을 맹목적으로 복사하는 대신 해당 필드들을 생략하십시오.

에이전트 루프 (agent-loop) 계약 유지

K3는 사고 이력(thinking history)이 보존된 상태로 학습되었습니다. 다회차 대화(multi-turn conversations) 및 도구 호출(tool calls)의 경우, API가 반환한 전체 어시스턴트 메시지(assistant message)를 다음 요청에 추가하십시오. 가시적인 content만 유지하면 추론(reasoning) 및 도구 호출 상태(tool-call state)가 누락되어 이후의 생성 과정이 불안정해질 수 있습니다.

다음의 불변 사항(invariants)을 준수하십시오:

1. 다른 모델에서 K3로 전환할 때는 새로운 세션을 시작하십시오.
2. 전체 어시스턴트 메시지를 변경 없이 저장하고 다시 재생(replay)하십시오.
3. K3에게 계속 진행하도록 요청하기 전에, 모든 tool_call_id에 대해 하나의 도구 결과(tool result)를 반환하십시오.
4. 동적으로 로드된 도구 정의(tool definitions)를 이후 요청에도 유지하십시오. 서버가 이를 대신 보관해주지 않습니다.
5. 구조화된 출력(structured output)은 reasoning_content가 아닌 최종 message.content에서만 파싱하십시오.
6. 시각 데이터(vision data)는 base64 또는 업로드된 ms:// 파일 ID로 전송하십시오. 출시 API 계약(launch API contract)에서는 공개 이미지 URL을 지원하지 않습니다.
7. 공식 웹 검색(web-search) 도구는 당분간 프로덕션 카나리(production canaries)에서 제외하십시오. Moonshot 측은 해당 도구가 업데이트 중이며 당분간은 권장되지 않는다고 밝혔습니다.

K3는 모호한 작업에 대해 지나치게 주도적으로 행동할 수도 있습니다. 시스템 프롬프트(system prompt)나 AGENTS.md에 승인 경계(approval boundaries), 허용된 도구, 파일 범위, 지출 한도(spend caps), 중단 조건(stop conditions)을 설정하십시오.

7단계 출시 게이트 (Seven-case rollout gate)

달러당 수락된 결과(accepted outcomes)가 개선되거나, 더 저렴한 모델이 수행할 수 없는 범주의 작업을 완료할 때만 K3를 승격시키십시오. K2.7 Code 또는 기존 제공자로 즉시 되돌릴 수 있는 원플래그 롤백(one-flag rollback) 체계를 유지하십시오.

일반적인 실수

• 계획된 7월 27일 출시 전에 가중치(weights)를 다운로드할 수 있다고 말하는 것.
• 1M 컨텍스트 윈도우(window)를 매 턴마다 전체 리포지토리(repository)를 전송해도 되는 이유로 취급하는 것.
• 기존 대화를 K3로 전환하면서 대화 기록(history) 손상에 대해 모델을 탓하는 것.
• 메시지를 재구성할 때 reasoning_content 또는 도구 호출(tool-call) 필드를 누락하는 것.
• 추론 노력(reasoning effort)과 에이전트 하네스(agent harness)를 일치시키지 않고 벤치마크 점수를 비교하는 것.
• 출력 및 재시도(retries) 비용을 측정하지 않고 모든 작업에 max를 사용하는 것.
• 장기 자율성(long-horizon autonomy)을 위해 훈련된 에이전트가 명시적인 제한 없이 제품, 파일 또는 네트워크 결정을 내리도록 허용하는 것.

FAQ

Kimi K3는 현재 오픈 소스인가요?

호스팅된(Hosted) K3는 현재 사용 가능합니다. Moonshot은 전체 가중치(weights)가 7월 27일까지 출시될 예정이며, 기술 보고서(technical report)를 통해 더 자세한 아키텍처 및 평가 세부 정보를 제공할 것이라고 밝혔습니다. 현재 셀프 호스팅(self-hosting)이 완료되었다고 설명하기보다는, 해당 출시 이후에 파일, 라이선스, 체크섬(checksums) 및 추론(inference) 지원 여부를 다시 확인하십시오.

API가 OpenAI와 호환되나요?

OpenAI Python SDK와 https://api.moonshot.ai/v1 베이스 URL(base URL)을 사용합니다. 호환성이 완전히 동일하지는 않습니다. K3는 reasoning_effort를 추가하고, 사고 기록(thinking history)을 보존하며, 여러 샘플링 파라미터(sampling parameters)를 고정하고, 스트리밍되는 추론(streamed reasoning)을 분리하며, 특정 비전(vision) 및 도구 루프(tool-loop) 규칙을 가지고 있습니다.

K3가 K2.7 Code를 대체해야 하나요?

기본적으로는 아닙니다. 어려운 장기 자율성(long-horizon), 멀티모달(multimodal) 또는 백만 토큰(million-token) 작업에 대해 K3를 테스트하십시오. 작업 수준의 근거가 업그레이드를 정당화할 때까지 K2.7 Code를 일상적인 코딩을 위한 더 저렴한 베이스라인(baseline)으로 유지하십시오.

Sources

• Moonshot AI: Kimi K3 technical launch blog
• Kimi API Platform: Kimi K3 quickstart and limits
• Kimi API Platform: current model pricing
• Moonshot AI product and research availability