Kimi K3.1 Pro API: 엔드포인트, 툴 호출, 캐싱 및 오류

Kimi K3.1 Pro API는 https://api.moonshot.ai/v1에서 모델 ID kimi-k3.1-pro와 kimi-k3.1-pro-highspeed로 실행됩니다. 세 가지 전송 형식을 지원합니다: OpenAI Chat Completions, Responses API, Anthropic Messages. 따라서 이미 사용 중인 SDK를 베이스 URL만 바꿔 그대로 사용할 수 있습니다. 이 모델은 최소 $1을 충전하면 잠금이 해제됩니다.

이 문서는 프로덕션 코드를 위한 레퍼런스입니다. 첫 호출, 스트리밍, Codex 또는 Claude Code 설정에 대해서는 Kimi K3.1 Pro 사용 방법을 참고하세요. 비용은 Kimi K3.1 Pro 가격에서 확인할 수 있습니다. 내용은 Moonshot의 K3.1 Pro 퀵스타트와 연결된 문서를 2026년 10월 24일에 확인한 것을 바탕으로 합니다.

Kimi K3.1 Pro Responses API, Anthropic API와 Chat Completions

Moonshot은 세 가지 API 인터페이스로 K3.1 Pro를 제공합니다. 클라이언트 라이브러리나 에이전트가 이미 지원하는 것을 선택하세요. 모델, 키, 청구는 세 가지 모두 동일합니다.

이들은 캐시 TTL을 설정하는 방식과 사용량이 표시되는 위치에서 차이가 있습니다(아래 캐싱 참고). K3에서 넘어오시나요? Kimi K3 API 가이드가 여전히 적용됩니다. K3.1 Pro는 동일한 1,048,576 토큰 컨텍스트를 가진 포스트 트레이닝된 K3입니다.

Kimi K3.1 Pro API 키: 잠금 해제 및 접근 확인

충전된 계정과 올바른 제품의 키가 필요합니다. 네 단계입니다:

1. Kimi API 플랫폼에서 최소 $1을 충전하세요. K3.1 Pro는 플래그십 모델이며 충전이 성공해야만 잠금이 해제됩니다.
2. API 키 콘솔에서 키를 만들고 MOONSHOT_API_KEY로 내보내세요.
3. GET /v1/models로 해당 키에서 모델이 보이는지 확인하세요.
4. 코드에서 kimi-k3.1-pro를 호출하세요.

curl https://api.moonshot.ai/v1/models \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" | grep -o '"kimi-k3.1-pro[^"]*"'

모델이 목록에 없으면 그것부터 해결하세요. Kimi API, Kimi Code, Kimi Membership은 별개의 제품입니다. Kimi Code 키는 API 엔드포인트에서 작동하지 않으며, 멤버십이 API 잔액이 되지도 않습니다.

K3.1 Pro에서 중요한 요청 파라미터

대부분의 OpenAI 파라미터는 예상대로 동작합니다. 다음은 다르거나 사람들이 자주 실수하는 것들입니다:

추론 토큰도 사용량에 포함되므로 분류와 추출에는 "low"를 사용하세요. Preserved Thinking은 항상 켜져 있어 모든 assistant 메시지가 reasoning_content를 그대로 유지한 채 반환됩니다(사고 모델 가이드).

Kimi K3.1 Pro 도구 호출: Python으로 구현하는 완전한 루프

K3.1 Pro의 프로덕션 도구 루프는 Moonshot 문서의 네 가지 규칙을 따릅니다:

• 첫 턴에서는 tool_choice="required"로 도구 호출을 강제하고, 그다음 "auto"로 전환하세요.
• reasoning_content와 tool_calls를 포함한 완전한 assistant 메시지를 추가하세요.
• tool_call_id마다 하나의 tool 메시지를 보내세요.
• 모델이 혼란에 빠져 무한 루프를 돌지 않도록 턴 수를 제한하세요.

import json, os
from openai import OpenAI

client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"],
                base_url="https://api.moonshot.ai/v1")

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up an order's shipping status by ID",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]}}}]

def get_order_status(order_id):
    return {"order_id": order_id, "status": "shipped"}

messages = [{"role": "user", "content": "Where is order A-1042?"}]
tool_choice = "required"
for _ in range(8):  # hard cap on turns
    resp = client.chat.completions.create(
        model="kimi-k3.1-pro", reasoning_effort="high",
        messages=messages, tools=TOOLS, tool_choice=tool_choice)
    msg = resp.choices[0].message
    messages.append(msg)  # whole message, not msg.content
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        result = get_order_status(**json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result)})
    tool_choice = "auto"

대표적인 버그는 msg 대신 msg.content를 추가하는 것으로, 이렇게 하면 tool_calls와 reasoning_content가 사라집니다.

search_tools로 대규모 도구 호출 처리하기

에이전트에 수십 개에서 수백 개의 도구가 있을 때 모든 요청마다 모든 정의를 보내지 마세요. Moonshot의 K3 도구 호출 모범 사례는 다음 흐름을 권장합니다:

1. search_tools 함수 하나(백엔드에서 구현)와 몇 가지 핵심 도구를 선언하세요.
2. 모델이 답변 전에 검색하도록 첫 턴에 tool_choice: "required"를 설정하세요.
3. tools 필드를 가진 system 메시지를 통해 일치하는 도구 정의를 주입하세요.
4. 이후 턴에서는 tool_choice를 다시 "auto"로 두고 모델이 로드된 도구를 호출하게 하세요.

# after search_tools returns ["create_github_pr"]
messages.append({"role": "system",
                 "tools": [CATALOG["create_github_pr"]]})

주입된 정의는 최상위 tools 형식을 사용하며 해당 메시지부터 적용됩니다. 서버는 이를 보관하지 않으므로 이후 요청에서도 메시지를 유지하세요. tool_choice를 바꾸거나 정의를 추가해도 프리픽스 캐시는 깨지지 않습니다.

비전 및 비디오 입력

K3.1 Pro는 텍스트와 함께 이미지와 비디오를 입력받고 텍스트를 반환합니다. content를 여러 파트의 배열로 만드세요: image_url 파트(퀵스타트 예제는 base64 데이터 URL을 전송하며, 공개 이미지 URL은 지원되지 않는다고 명시합니다) 또는 ms:// ID로 업로드된 파일을 가리키는 video_url 파트입니다.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")
content = [{"type": "video_url", "video_url": {"url": f"ms://{video.id}"}},
           {"type": "text", "text": "Summarize this video."}]

content를 사용자 메시지로 전달하고, 완료 후 client.files.delete(video.id)로 파일을 삭제하세요.

코드에서의 컨텍스트 캐싱

반복되는 프리픽스에는 기본 TTL 5분으로 캐싱이 자동 적용됩니다. 캐시 적중은 백만 토큰당 $0.20로, 캐시되지 않은 입력의 $2.00와 대비됩니다. 1시간 쓰기는 $4.00이고 5분은 $2.00입니다. 1M 토큰 프리픽스에서는 1시간 TTL이 두 번 적중하면 본전을 뽑습니다.

안정적인 콘텐츠(시스템 프롬프트, 도구 정의, 문서)를 앞에 두고, 변하는 콘텐츠를 뒤에 두며, 프리픽스에 타임스탬프를 넣지 마세요. openai SDK에서는 extra_body를 통해 TTL을 전달합니다:

resp = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "system", "content": DOCS},
              {"role": "user", "content": question}],
    extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
d = resp.usage.prompt_tokens_details
print(resp.usage.prompt_tokens, d.cached_tokens,
      getattr(d, "cache_write_tokens", 0))

Anthropic API는 최상위 cache_control 필드로 TTL을 설정하며, 메시지 내부의 마커는 무시됩니다:

curl https://api.moonshot.ai/anthropic/v1/messages \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{"model": "kimi-k3.1-pro", "max_tokens": 256,
    "cache_control": {"type": "ephemeral", "ttl": "1h"},
    "messages": [{"role": "user", "content": "Hello"}]}'

캐시 사용량이 표시되는 위치는 인터페이스에 따라 다릅니다:

Chat Completions를 스트리밍할 때 마지막 청크에서 사용량을 받으려면 stream_options.include_usage=true를 설정하세요. 각 적중은 TTL을 갱신하며, TTL은 최초 쓰기 시 고정됩니다. 전체 규칙은 컨텍스트 캐싱 가이드를 참고하세요.

Kimi K3.1 Pro API 오류와 해결 방법

대부분의 실패는 여섯 가지 패턴에 해당합니다. 모든 429에서 error.type을 확인하세요. 해결 방법이 이에 따라 달라집니다.

재시도에 주의하세요. OpenAI SDK는 연결 오류, 408, 409, 429, 5xx에서 기본적으로 2회 재시도하므로, 한 번의 호출이 RPM에 대해 세 번의 요청이 될 수 있습니다. 낮은 티어에서는 클라이언트의 max_retries를 낮추고 error.type에 따라 직접 백오프하세요. 429로 중단된 요청에는 요금이 부과되지 않습니다.

서드파티 에이전트가 실패하면 동일한 키, 엔드포인트, 모델로 API를 직접 호출해 보세요. 그게 작동한다면 도구가 문제입니다. 문제 해결 페이지와 오류 코드를 참고하세요.

티어별 Kimi K3.1 Pro 요청 한도

누적 충전 금액이 한도 페이지의 티어를 결정합니다:

Tier0은 분당 3회 요청을 허용하며, 도구 루프의 모든 턴이 하나의 요청입니다. 5턴짜리 에이전트 실행은 이미 그 티어에서 1분을 넘깁니다. 따라서 에이전트를 본격적으로 테스트하기 전에 누적 $10을 확보하세요.

Apidog CLI로 Kimi API 계약 테스트하기

계약 테스트는 도구 루프가 tool_calls를 더 이상 받지 못하게 되는 날을 잡아냅니다. 코딩 에이전트가 Apidog CLI로 이를 구축하도록 하세요. 한 번 설치하고 로그인하세요:

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

그런 다음 Claude Code, Codex 또는 사용 중인 에이전트에 프롬프트를 입력하세요:

In Apidog project <projectId>, create an environment for https://api.moonshot.ai/v1
and an endpoint for POST /chat/completions. Add a test case that sends model
kimi-k3.1-pro, reasoning_effort "low", one get_order_status tool and
tool_choice "required". Assert status 200 and that choices[0].message.tool_calls
is non-empty. Run it and report failures.

에이전트가 스키마를 읽고, 페이로드를 검증하고, 케이스를 실행합니다:

apidog environment create kimi-prod --project <projectId> --base-url https://api.moonshot.ai/v1
apidog endpoint create --project <projectId> --file ./endpoint.json
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>로 목록을 확인할 수 있습니다. 실행이 통과하면 -r cli,json을 --out-dir와 함께 -r junit로 바꾸면 동일한 검사가 CI를 통과시킵니다. 이는 Apidog CLI CI/CD 가이드에서 확인할 수 있습니다. 에이전트 설정은 Claude Code에서의 Apidog CLI에 있습니다. Apidog의 무료 플랜은 최대 4명의 사용자를 지원합니다.

FAQ

Kimi K3.1 Pro API의 베이스 URL은 무엇인가요?

Chat Completions와 Responses API는 https://api.moonshot.ai/v1이고, Anthropic 호환 Messages API는 https://api.moonshot.ai/anthropic입니다.

Kimi K3.1 Pro API는 thinking 파라미터를 지원하나요?

아니요. 사고는 항상 켜져 있습니다. 최상위 reasoning_effort 필드("low", "high" 또는 "max")로 제어하세요.

충전 직후에 왜 429가 발생하나요?

error.type을 확인하세요. engine_overloaded_error는 서버 용량 문제로 충전으로 해결되지 않습니다. rate_limit_reached_error는 해당 티어의 한도를 의미하며, Tier0은 3 RPM만 허용합니다.

캐싱이 작동하는지 어떻게 알 수 있나요?

usage의 캐시 읽기 필드가 0이 아니면 적중입니다: Chat Completions에서는 prompt_tokens_details.cached_tokens, Messages에서는 cache_read_input_tokens입니다.

Kimi K3.1 Pro API 무료 티어가 있나요?

아니요. API는 최소 $1 충전이 필요합니다. Kimi 앱의 무료 채팅이 $0 경로이며, Kimi K3.1 Pro 무료 사용 방법에서 다룹니다. 모델 배경은 Kimi K3.1 Pro란 무엇인가를 참고하세요.