Kimi K3.1 Pro 사용법

Kimi K3.1 Pro를 네 가지 방법으로 사용하는 방법은 다음과 같습니다. Kimi 웹 또는 모바일 앱에서 대화하기, https://api.moonshot.ai/v1의 OpenAI 호환 API를 통해 kimi-k3.1-pro 호출하기, 유료 멤버십으로 Kimi Code CLI 안에서 실행하기, 또는 Codex, Claude Code, OpenCode를 Moonshot의 엔드포인트로 지정하기입니다. API는 1달러를 충전하면 활성화되며, 100만 입력 토큰당 2달러, 100만 출력 토큰당 10달러의 비용이 듭니다.

Moonshot AI는 2026년 10월 23일에 Kimi K3.1 Pro를 출시했습니다. 이는 Kimi K3를 후속 학습(post-training)한 버전으로, 동일한 2.8T 파라미터 MoE 설계(활성 파라미터 약 104B), 1,048,576 토큰 컨텍스트 윈도우, 그리고 항상 켜져 있는 사고(thinking) 기능을 갖추고 있습니다. 먼저 배경 지식이 필요하다면 Kimi K3.1 Pro란 무엇인가를 읽어보세요. 비용을 전혀 쓰고 싶지 않다면 Kimi K3.1 Pro를 무료로 사용하는 방법 가이드에서 0달러 경로를 다룹니다. 아래의 모든 사실은 2026년 10월 24일에 확인한 Moonshot의 발표문, API 퀵스타트, 가격 페이지에서 가져왔습니다.

어떤 Kimi K3.1 Pro 경로를 선택해야 할까요?

무엇을 만들고 있는지에 따라 선택하세요. 채팅은 간단한 질문에, API는 앱에, Kimi Code는 관리할 키 없이 에이전트를 원하는 멤버에게, 그리고 자체 에이전트는 이미 Codex나 Claude Code에서 작업하는 팀에 적합합니다.

Kimi 웹 및 모바일 앱에서 Kimi K3.1 Pro 사용하기

채팅 앱이 가장 빠른 진입 방법입니다. Kimi 웹 앱이나 iOS, Android 또는 HarmonyOS 앱을 열고 무료 계정으로 로그인하면, K3.1 Pro가 이미 입력창의 기본 모델로 설정되어 있으며 사고 노력(thinking effort)은 High로 지정되어 있습니다.

로그인하기 전에는 입력창에 K2.8 Preview와 Instant도 표시됩니다. 프롬프트를 보내려면 계정이 필요합니다. Moonshot은 무료 플랜의 K3.1 Pro 메시지 할당량을 공개하지 않았으므로 [VERIFY], 채팅은 프로덕션 채널이 아니라 테스트 공간으로 생각하세요.

Kimi Work 데스크톱 3.1.0 이후 버전(Windows 및 Apple 실리콘 Mac)에서도 이 모델을 실행할 수 있습니다. Kimi Business와 Enterprise에서는 관리자가 직접 켜야 하는데, 출시 시점에 기본적으로 꺼져 있기 때문입니다.

Kimi K3.1 Pro API: Python과 cURL로 하는 첫 호출

Kimi K3.1 Pro API는 OpenAI 호환이므로, 기본 URL만 바꾸면 표준 openai SDK가 그대로 작동합니다. 설정은 세 단계입니다:

1. 최소 $1을 충전하세요. K3.1 Pro는 플래그십 모델이며 충전이 성공해야만 활성화됩니다.
2. API 키 콘솔에서 키를 생성하고 MOONSHOT_API_KEY로 내보내기(export)하세요.
3. https://api.moonshot.ai/v1에서 kimi-k3.1-pro(또는 kimi-k3.1-pro-highspeed) 모델을 호출하세요.

다음은 Moonshot의 공식 Python 예제입니다:

import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.ai/v1")
completion = client.chat.completions.create(
    model="kimi-k3.1-pro",
    reasoning_effort="high",
    messages=[{"role": "user", "content": "Introduce Kimi K3.1 Pro in one sentence."}],
)
print(completion.choices[0].message.content)

동일한 호출을 cURL로 하면 다음과 같습니다:

curl https://api.moonshot.ai/v1/chat/completions \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"model": "kimi-k3.1-pro","reasoning_effort": "high","messages": [{"role": "user", "content": "Introduce Kimi K3.1 Pro in one sentence."}]}'

이 모델은 텍스트, 이미지, 동영상을 입력으로 받고(퀵스타트에 image_url과 video_url 파트가 나와 있습니다) 텍스트를 반환합니다. 코드를 작성하기 전에 Playground에서 프롬프트를 시험해볼 수도 있습니다. 여전히 유효한 K3 시기의 패턴은 Kimi K3 API 가이드를 참고하세요.

Kimi K3.1 Pro 추론 노력(reasoning effort): low, high, max

reasoning_effort는 모델이 답변하기 전에 얼마나 생각할지를 지정하는 최상위 요청 필드입니다. "low", "high", "max"를 받으며 기본값은 "max"입니다. 사고 기능은 끌 수 없습니다. "medium" 단계는 없습니다.

Moonshot의 추론 노력 가이드에 전체 레퍼런스가 있습니다. 출력 토큰에 100만 개당 $10을 지불하므로, 간단한 호출에서 max를 low로 낮추는 것이 가장 쉽게 찾을 수 있는 절약 방법입니다. temperature와 top_p는 생략하세요. 퀵스타트에 각각 1.0과 0.95로 고정되어 있다고 나와 있습니다.

추론 스트리밍, 멀티턴 상태 유지, JSON 응답 받기

사람들이 자주 걸리는 세 가지 API 동작이 있으며, 각각 간단한 규칙이 있습니다.

스트리밍. 스트리밍 응답은 reasoning_content와 content 델타를 별도로 전송합니다. 첫 번째는 표시하거나 로그로 남기고, 두 번째를 렌더링하세요:

stream = client.chat.completions.create(
    model="kimi-k3.1-pro", reasoning_effort="low", stream=True,
    messages=[{"role": "user", "content": "Explain MoE routing briefly."}],
)
for chunk in stream:
    delta = chunk.choices[0].delta
    thinking = getattr(delta, "reasoning_content", None)
    if thinking:
        print(thinking, end="")
    if delta.content:
        print(delta.content, end="")

멀티턴과 도구 호출. 어시스턴트 메시지의 content만이 아니라 완전한 메시지를 그대로 되돌려 보내세요. Moonshot의 문서가 이 점을 명확히 밝히고 있으며, 도구 호출이 관련될 때 특히 중요합니다:

messages.append(completion.choices[0].message)  # whole message, not .content
messages.append({"role": "user", "content": "Now add tests."})

모델이 도구를 호출해야 할 때 tool_choice: "required"가 지원됩니다. 부분 모드(partial mode)도 작동합니다. 메시지 목록을 "partial": true가 있는 어시스턴트 메시지로 끝내면 모델이 그 내용을 이어서 작성합니다.

구조화된 출력. 타입이 json_schema이고 strict: true인 response_format을 전달한 다음, message.content만 파싱하세요. 추론 텍스트는 절대 파싱하지 마세요.

Kimi Code K3.1 Pro: 멤버십 경로

Kimi Code는 Moonshot 자체의 터미널 코딩 에이전트이며, API 키가 필요 없는 경로입니다. 대신 Kimi 계정으로 로그인합니다. 멤버십 혜택이므로 무료 Adagio 플랜에는 포함되지 않습니다.

설치하고 로그인하세요:

# macOS / Linux
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
# Windows PowerShell: irm https://code.kimi.com/kimi-code/install.ps1 | iex
kimi

세션 안에서 /login을 실행한 다음, /model로 K3.1 Pro를 선택하세요. 두 개의 ID는 플랜 등급에 대응합니다:

• k3.1-pro: Moderato(Plus) 이상. Allegretto(Pro) 이상은 최대 1M 컨텍스트까지 사용할 수 있습니다.
• k3.1-pro-highspeed: Allegretto(Pro) 이상, 약 2배의 할당량을 사용합니다.

멤버십 가격을 보면 Plus는 연간 결제 시 월 $15(월 결제 시 $19)이고 Pro는 연간 $31(월 결제 시 $39)입니다. Kimi Code 문서에서 명령어를 다루며, Kimi Code CLI 워크스루에서 일상적인 사용법을 더 깊이 다룹니다.

Codex에서의 Kimi K3.1 Pro

Codex는 Responses API를 통해 Kimi와 통신하며, Moonshot은 공식 Codex 가이드를 공개했습니다. 다음을 ~/.codex/config.toml에 추가하세요:

model = "kimi-k3.1-pro"
model_provider = "kimi"
model_context_window = 1048576

[model_providers.kimi]
name = "Kimi"
base_url = "https://api.moonshot.ai/v1"
env_key = "KIMI_API_KEY"
wire_api = "responses"

환경 변수 이름에 주의하세요. Codex는 MOONSHOT_API_KEY가 아니라 KIMI_API_KEY를 읽습니다. Moonshot 키를 그 이름으로 내보낸 다음, 평소처럼 codex를 실행하세요.

Claude Code에서의 Kimi K3.1 Pro

Moonshot은 https://api.moonshot.ai/anthropic에서 Anthropic 호환 Messages 엔드포인트를 운영하므로, Claude Code가 프록시 없이 작동합니다. ~/.claude/settings.json의 env 블록에 변수를 넣으세요:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.moonshot.ai/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_MOONSHOT_API_KEY",
    "ANTHROPIC_MODEL": "kimi-k3[1m]"
  }
}

이 별칭은 의도적인 것입니다. Moonshot의 문제 해결 페이지에 따르면 직접 API 호출과 Codex는 kimi-k3.1-pro를 사용하는 반면, Claude Code는 호환 별칭인 kimi-k3[1m]를 사용합니다. Claude Code 가이드에서는 다른 모델 변수들도 설정하므로, 그것들을 그대로 복사하세요.

한 가지 주의할 점: 설정 파일의 env 블록에 있는 오래된 값이 셸 export를 덮어씁니다. Claude Code가 계속 예전 모델을 호출한다면, 먼저 그 파일을 확인하세요.

OpenCode

OpenCode는 설정 파일이 필요하지 않습니다. opencode auth login을 실행하고 “Moonshot AI”를 선택한 뒤 키를 붙여넣고, Moonshot AI 모델 목록에서 K3.1 Pro를 고르세요. Moonshot의 OpenCode 가이드는 K3를 기준으로 작성되었으므로, 모델이 목록에 나타나는지 확인하세요 [VERIFY].

Apidog CLI로 에이전트가 Kimi API를 테스트하게 하기

Codex나 Claude Code가 K3.1 Pro에서 실행되기 시작하면, 같은 세션을 Kimi API 자체의 회귀 테스트에 활용하세요. 에이전트가 검사를 작성하고 실행하며, 여러분은 프롬프트 하나만 작성하면 됩니다. Apidog CLI는 구조화된 JSON 출력과 스키마를 제공하므로 페이로드 형태를 추측하지 않습니다.

CLI를 설치하고 로그인한 뒤 에이전트 스킬을 추가하세요:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install

그런 다음 에이전트에게 프롬프트 하나를 주세요:

In Apidog project <projectId>, create an environment for https://api.moonshot.ai/v1.
Then create a test case for POST /chat/completions with model kimi-k3.1-pro and
reasoning_effort "low" that asserts status 200 and non-empty choices[0].message.content.
Run it and summarize any failures.

에이전트가 환경을 만들고, 스키마를 읽고, 페이로드를 검증하고, 테스트 케이스를 작성해 실행합니다:

apidog environment create kimi-prod --project <projectId> --base-url https://api.moonshot.ai/v1
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

테스트 케이스에는 유효한 카테고리가 필요하며, apidog test-case category --project <projectId>로 목록을 확인할 수 있습니다. 비어 있지 않은 답변과 함께 200이 반환된다는 것은 API가 reasoning_effort를 받아들였다는 증거이기도 합니다. -r junit으로 바꾸면 같은 실행을 CI에 넣을 수 있습니다. Apidog CLI CI/CD 가이드에서 확인하세요. 에이전트별 설정은 Codex에서의 Apidog CLI와 Claude Code에서의 Apidog CLI에 있습니다. Apidog의 Free 플랜은 최대 4명의 사용자를 지원합니다.

Kimi K3.1 Pro 비용 참고 사항

API는 구독 없이 사용한 만큼 지불하는 방식이며, 가격에는 세금이 포함되지 않습니다.

K3.1 Pro는 입력과 출력 모두에서 K3보다 3분의 1 저렴합니다. 캐싱은 반복되는 프리픽스에 대해 자동으로 적용되며 기본 TTL은 5분이고, 캐시 적중은 $0.20로 청구됩니다. Highspeed는 두 배 가격에 2-3배 더 빠르게 실행됩니다.

최소 $1 충전으로 약 500K 입력 토큰 또는 100K 출력 토큰을 사용할 수 있습니다. 누적 충전액이 $5에 도달하면 $5 바우처를 받지만, 바우처는 누적 충전액에 포함되지 않으며, K3.1 Pro에 적용되는지는 명시되어 있지 않습니다 [VERIFY]. $1 계정은 한도 페이지의 Tier0에서 시작합니다. 즉, 동시 요청 1개, 분당 요청(RPM) 3회, 하루 1.5M 토큰입니다. 누적 $10의 Tier1에서는 이것이 100 RPM으로 올라갑니다.

FAQ

Kimi K3.1 Pro는 오픈 웨이트인가요?

아직 아닙니다. Moonshot은 2026년 11월 4일까지 전체 모델 가중치를 공개하겠다고 밝혔습니다. 라이선스는 아직 명시되지 않았습니다.

K3.1 Pro와 K3.1 Pro Highspeed의 차이는 무엇인가요?

같은 모델 패밀리지만 속도와 가격이 다릅니다. Highspeed는 2-3배 더 빠르게 실행되며 100만 토큰당 $4/$20로, $2/$10에 비해 비쌉니다. Kimi Code에서는 Pro 플랜이 필요하고 약 2배의 할당량을 사용합니다.

Kimi K3.1 Pro에서 사고(thinking)를 끌 수 있나요?

아니요. 사고 기능은 항상 켜져 있습니다. 추론 토큰과 지연 시간을 줄이려면 reasoning_effort를 "low"로 설정하세요.

멀티턴 대화가 왜 깨지나요?

아마도 어시스턴트의 content만 되돌려 보내고 있을 것입니다. Moonshot 문서가 멀티턴 대화와 도구 호출에 요구하는 대로, 완전한 어시스턴트 메시지 객체를 대화 기록에 추가하세요.

Kimi API는 무료인가요?

아니요. K3.1 Pro는 최소 $1 충전 후 활성화됩니다. Kimi 앱에서의 무료 채팅이 $0 옵션이며, 무료 가이드에서 다룹니다.

Kimi K3.1 Pro는 1M 컨텍스트 윈도우를 지원하나요?

네. API는 1,048,576 토큰을 지원합니다. Kimi Code에서는 전체 1M 컨텍스트를 사용하려면 Allegretto(Pro) 이상이 필요합니다.