Kimi K3.1 Pro로 마이그레이션하기: 400 오류를 해결하고, 기본값인 Max Effort에 유의하며, Highspeed를 잘못 입력하지 마세요

Kimi K3.1 Pro는 Kimi Code에서 사용할 수 있으며, Moonshot API에서는 kimi-k3.1-pro로, AIHubMix에서는 같은 ID로 제공됩니다. Moonshot은 Kimi K3와 동일한 매개변수 제약을 적용하므로, K3에서 이미 작동하는 코드는 모델 ID를 바꾸고 새 세션을 시작하면 됩니다. K2.x용으로 작성된 코드는 Moonshot 플랫폼에서 사용 기한이 정해져 있습니다. Moonshot은 2026년 10월 31일부터 신규 가입자에게 K2 시리즈 제공을 중단하고, 12월 말까지 폐기할 계획입니다. 이 코드는 작동이 중단될 가능성도 가장 높습니다. 온도를 전송하거나 thinking을 끄는 경우가 많기 때문인데, 둘 다 K3.1 Pro에서는 작동하지 않습니다. 또한 effort 수준을 설정하지 않은 코드는 기본값인 max로 실행되므로, 예상보다 토큰을 더 많이 사용할 수 있고 Kimi Code에서는 K3보다 할당량을 더 많이 소모합니다.

이 글에서는 명확하게 드러나는 오류(400 오류와 404 오류 하나), 조용히 발생하는 문제(요금, 캐시, Highspeed ID), 그리고 AIHubMix를 통해 Claude Code와 Codex를 K3.1 Pro용으로 설정하는 방법을 설명합니다. K3.1 Pro의 규칙은 Moonshot의 Kimi Code 모델 문서와 모델 매개변수 참조 문서를 기준으로 하며, 두 문서에는 두 K3.1 Pro ID 모두 kimi-k3와 동일한 매개변수 제약을 따른다고 나와 있습니다. K3 규칙으로 표시된 내용은 Moonshot의 K3 가이드에서 가져왔으며 K3.1 Pro에서 다시 확인하지는 않았습니다. 오류 문구는 문서, 공개된 보고, AIHubMix의 7월 K3 테스트, 그리고 2026년 10월 24일에 진행한 AIHubMix의 K3.1 Pro 점검에서 인용했습니다. 점검에는 주요 ID와 코딩 채널 ID인 coding-kimi-k3.1-pro, coding-kimi-k3.1-pro-highspeed가 포함됐습니다. 각 내용의 출처도 함께 표시했습니다.

어떤 경로를 사용하시나요?

Moonshot API와 AIHubMix에서 사용하는 ID는 kimi-k3.1-pro와 kimi-k3.1-pro-highspeed입니다. Kimi Code에서는 k3.1-pro와 k3.1-pro-highspeed를 사용합니다. 10월 21일에 확인된 클라이언트 설정에서는 k3와 kimi-for-coding이 k3.1 모델에 매핑됐지만, 현재 Kimi Code 문서에는 k3가 K3로, kimi-for-coding이 K2.8 Preview로 나와 있으므로 K3.1 Pro를 명시적으로 선택하세요. 요금제도 중요합니다. Kimi Code에서 K3.1 Pro를 사용하려면 Plus 이상이 필요하고(1M 컨텍스트는 Pro), Highspeed는 Pro 이상이 필요합니다. 기존 요금제에서는 Moderato 이상이 필요하며, 1M 컨텍스트와 Highspeed에는 Allegretto가 필요합니다.

K2 관련 일정은 Moonshot에서 발표한 내용입니다. 2026년 10월 31일부터 신규 가입자는 K2 시리즈 모델을 사용할 수 없으며, 모든 모델은 2026년 12월 말까지 폐기될 예정입니다. Moonshot은 K3의 폐기 일정을 발표하지 않았습니다. 10월 24일 기준 AIHubMix에서는 K2.6과 K2.7 Code를 계속 제공하고 있었으며, 폐기 일정은 없었습니다.

명확하게 드러나는 오류

thinking을 끈 경우: HTTP 400 오류 또는 추론 결과가 전혀 없음

확인되는 증상: Kimi Code에서 HTTP 400 오류가 발생합니다. Moonshot의 Kimi Code 문서에는 K3.1 Pro 모델이 “thinking 모드만 지원합니다. thinking을 비활성화한 요청은 거부됩니다.”라고 나와 있습니다. 문서에는 오류 본문이 인용돼 있지 않습니다. Moonshot API에서 K3.1 Pro는 K3의 제약을 따르며, K3는 항상 추론합니다. AIHubMix에서는 400 오류가 발생하지 않습니다. 10월 24일, thinking: {"type": "disabled"}를 전송했을 때 Chat Completions와 Messages 모두에서 두 주요 ID가 200을 반환했지만, 응답에는 추론이 없었습니다. 이 경우에는 문제가 조용히 발생하므로 응답에 추론이 누락됐는지 확인하세요.

발생 원인: 더 빠르게 답하도록 thinking을 끄는 K2.x 코드입니다. 예를 들면 extra_body={"thinking": {"type": "disabled"}}를 사용하거나, 다음 섹션에서 설명할 off, none, disabled effort 값을 보내는 도구가 있습니다.

해결 방법: 비활성화 설정을 제거하세요. thinking을 짧게 유지하려면 대신 reasoning_effort: "low"를 전송하세요.

남아 있는 "enabled" 블록은 별개의 경우입니다. AIHubMix는 10월 24일 점검에서 K2.x의 thinking: {"type": "enabled"}를 K3.1 Pro에 전송했고, 주요 ID와 코딩 채널 모두에서 200을 받았습니다. Moonshot 문서에는 thinking이 “K2.x 전용 요청 매개변수”라고 나와 있고, K2.x에서 K3로 전환한 뒤 400 오류가 발생하는 원인으로 남아 있는 블록을 언급한 타사 문제 해결 가이드도 있으므로, 어쨌든 삭제하는 것이 좋습니다.

K2.7 Code가 폐기될 때까지 예비 티어로 유지한다면 thinking을 켜 두세요. Moonshot의 Claude Code 가이드에는 K2.7 Code에서 thinking을 끈 경우 400 invalid thinking: only type=enabled is allowed for this model 오류가 발생한다고 나와 있습니다.

Effort 값: off, none 및 알 수 없는 값은 400 오류를 반환

확인되는 증상: effort 값이 off, none, disabled이거나 Kimi Code에서 인식하지 못하는 값이면 HTTP 400 오류가 발생합니다. K3.1 Pro에는 low, high, max의 세 가지 수준이 있습니다. Moonshot의 Kimi Code 문서에서는 타사 도구가 보내는 값을 다음과 같이 매핑합니다.

Moonshot API 문서에는 K3.1 Pro에서 low, high, max만 지원된다고 나와 있으며, 기본값은 max이고 값 매핑에 대한 설명은 없습니다. AIHubMix에서는 10월 24일 점검 당시 네 가지 K3.1 Pro ID 모두에서 low, medium, high, max, xhigh가 모두 200을 반환했습니다. kimi-k3.1-pro에서는 off와 알 수 없는 값도 추론 결과와 함께 200을 반환했고, none은 추론 없이 200을 반환했습니다. AIHubMix에서는 400 오류가 아니라 조용히 실패합니다.

조용히 발생하는 문제: medium 수준은 없습니다. medium으로 설정한 도구는 high로 실행되고, xhigh로 설정한 도구는 비용이 가장 많이 드는 max로 실행됩니다.

해결 방법: low, high, max 중 하나를 명시적으로 전송하고, 도구가 실제 요청에 어떤 값을 넣는지 확인하세요.

"잘못된 temperature: 이 모델에는 1만 허용됩니다"

확인되는 증상: 400 invalid temperature: only 1 is allowed for this model 오류입니다. AIHubMix는 10월 24일 점검에서 temperature: 0.2를 전송했을 때 kimi-k3.1-pro와 kimi-k3.1-pro-highspeed에서 정확히 이 오류를 확인했습니다. 2026년 10월 3일에는 Moonshot API의 K3에서, 10월 21일에는 Kimi Code 엔드포인트의 k3에서 같은 문구가 보고됐습니다.

원인: Moonshot의 매개변수 참조 문서에는 K3.1 Pro가 K3의 제약을 따른다고 나와 있습니다. temperature는 1.0, top_p는 0.95, n은 1, 두 penalty 값은 0으로 고정되며, 그 외 값을 보내면 오류가 발생합니다. K2.6도 고정값을 사용했으며, thinking을 끈 경우 0.6이었습니다. 따라서 여전히 0.6을 전송하는 코드가 가장 유력한 원인입니다.

문제를 숨기는 예외: 같은 점검에서 AIHubMix의 코딩 채널은 temperature: 0.2를 허용했습니다. 코딩 채널에서만 테스트한 코드는 주요 ID나 Moonshot API에서 여전히 작동하지 않을 수 있습니다.

문제를 더 감추는 함정: 많은 프레임워크는 kimi- 접두사로 Kimi 모델을 식별해 해당 모델의 temperature를 제거합니다. Kimi Code의 k3.1-pro와 k3.1-pro-highspeed에는 이 접두사가 없고, coding-으로 시작하는 AIHubMix 코딩 채널 ID에도 없습니다. Hermes Agent 이슈에서는 K3에서 바로 이 문제가 발견됐습니다. 기본 채팅 경로에서는 temperature를 제외했지만, k3를 호출하는 보조 기능에서는 여전히 전송해 매번 400 오류가 발생했습니다.

해결 방법: temperature, top_p, n, presence_penalty, frequency_penalty를 아예 전송하지 마세요. 이름의 접두사가 아니라 모델 계열을 기준으로 판단하세요.

경로를 확인하려면 temperature를 포함한 요청을 하나 전송하세요.

curl https://aihubmix.com/v1/chat/completions \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kimi-k3.1-pro", "temperature": 0.2, "messages": [{"role": "user", "content": "hi"}]}'

10월 24일에 이 요청은 위와 같은 400 오류를 반환했습니다. 코드에서 사용하는 모든 모델 ID에 대해 실행하세요. 코딩 채널은 같은 요청에 200으로 응답했습니다.

AIHubMix를 통한 Codex: Responses API에서 404 오류

확인되는 증상: The model kimi-k3.1-pro is not available on this endpoint.라는 HTTP 404 오류입니다. AIHubMix는 10월 24일 점검에서 두 주요 ID 모두 Responses API로 요청했을 때 이 오류를 확인했습니다. Chat Completions와 Messages는 정상 응답했습니다.

해결 방법: Codex는 Responses API만 지원하므로, 같은 점검에서 Responses 요청에 응답한 coding-kimi-k3.1-pro를 사용하도록 설정하세요. AIHubMix는 코딩 채널을 프로덕션에 권장하지 않는 평가용 프리뷰로 표시하고 있으며, 일부 요청에서는 “The requested resource was not found”라는 일시적인 404가 반환됐으므로 디버깅하기 전에 한 번 재시도하세요. AIHubMix가 주요 ID에 Responses API를 추가할 때까지 이 ID를 사용하세요. Claude Code는 Messages를 사용하며 주요 ID에서 작동합니다.

stop 제한

확인되는 증상: AIHubMix의 7월 K3 테스트에서 다음 두 가지 메시지가 반환됐습니다.

• 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

원인: K3는 stop 시퀀스를 최대 5개까지 허용하며, 각 시퀀스는 최대 32바이트입니다. Messages API에서도 stop_sequences에 같은 검사를 적용합니다. Moonshot은 K3.1 Pro에 동일한 매개변수 제약을 적용하므로, 같은 제한이 있을 것으로 예상하세요.

해결 방법: 목록을 줄이세요. 32 바이트는 중국어나 일본어의 경우 문자 32개보다 적습니다.

Moonshot API의 Codex: “web_search.search_context_size is not supported”(K3 가이드)

확인되는 증상: Moonshot의 Codex 가이드에서 인용한 400 web_search.search_context_size is not supported 오류입니다. 이 가이드는 K3용으로 작성됐습니다. AIHubMix의 코딩 채널에서는 10월 24일 해당 필드를 포함한 Responses 요청이 200을 반환했으므로, 이 오류는 Moonshot 자체 엔드포인트에서 발생합니다.

해결 방법: Codex 설정이나 도구 정의에서 search_context_size를 제거하세요. Codex는 기본적으로 이 값을 보내지 않습니다.

조용히 발생하는 문제

이런 문제는 오류를 반환하지 않습니다. 나중에 요금 청구서나 요금제 할당량, 출력 품질에서 드러납니다.

Effort와 세션

• 기본값은 max이며, Kimi Code에서는 새로 바뀐 설정입니다. K3.1 Pro의 기본값은 max입니다. Kimi Code에서 K3의 기본값은 high였으므로, effort를 한 번도 설정하지 않은 세션은 이제 더 깊이 추론하고 토큰을 더 사용하며 할당량도 더 빨리 소모합니다. Moonshot API에서는 K3와 K3.1 Pro 모두 기본값이 max입니다. thinking은 출력 토큰으로 요금이 청구됩니다. AIHubMix의 7월 K3 단일 프롬프트 게임 제작 테스트에서 완료 토큰 74,994개 중 73%가 thinking 토큰이었습니다.
• 낮은 추론 강도에서도 사고 토큰이 수천 개 발생할 수 있습니다. 10월 24일 AIHubMix에서 진행한 간단한 점검에서 600단어 설명을 요청하는 프롬프트에 K3.1 Pro는 low 설정으로 답변하기 전에 5,561~7,356개의 토큰을 추론에 사용했고, 한 번은 8,192토큰 한도에 도달했습니다. 같은 프롬프트에서 K3는 3,013~7,051개의 토큰을 추론에 사용했습니다. 따라서 K3.1 Pro에서 새로 생긴 문제는 아니지만, 어느 모델에서든 low는 비용이 적게 드는 모드가 아닙니다. max_completion_tokens를 넉넉하게 설정하세요. AIHubMix의 기본 모델 ID로 모델당 프롬프트 하나를 세 번 실행한 결과이므로, 실제 작업 부하에서도 직접 측정해 보세요.
• 기존 세션에서 K3.1 Pro로 전환하면 품질이 떨어집니다. Moonshot의 Kimi Code 문서는 "기존 K3 시리즈, K2.8 Preview 또는 K2.7 Code Highspeed 세션에서" 새 모델로 전환하지 말라고 권고합니다. 출력 품질이 저하되고 캐시 적중률도 낮아지기 때문입니다. 새 세션을 시작하세요.
• 모델이나 추론 강도를 변경하면 캐시가 무효화됩니다. Moonshot의 Kimi Code 문서는 두 가지 모두에 대해 이렇게 안내하며, K3 문서에서도 추론 강도를 전환하면 "프리픽스 캐시 적중이 무효화된다"고 설명했습니다. 세션을 시작할 때 모델과 추론 강도를 선택하세요.

Highspeed

• Highspeed ID를 잘못 입력하면 더 느린 모델이 실행됩니다. Kimi Code에서는 Highspeed ID를 잘못 입력하면 "알림 없이 K2.8 Preview로 대체되며 사고 기능도 없습니다. 속도 향상도 없습니다." ID를 정확하게 복사하고 로그에 어떤 모델이 표시되는지 확인하세요.
• Highspeed는 모델 출력만 더 빠르게 합니다. Moonshot에 따르면 K3.1 Pro Highspeed는 K3.1 Pro와 기능은 동일하고 속도는 약 2~3배 빠릅니다. AIHubMix의 간단한 점검에서는 출력 속도가 Pro보다 약 1.6~1.8배 빨랐습니다. 도구 호출과 스크립트 실행은 전혀 빨라지지 않으므로, 파일을 읽고 테스트를 실행하는 작업이 대부분인 턴에서는 이점이 작습니다. 반면 Kimi Code 플랜에서는 할당량을 약 두 배로 사용합니다.

프로토콜

• 프록시가 동작을 바꿀 수 있습니다. Moonshot의 Kimi Code 문서는 "프록시 도구를 통한 프로토콜 변환으로 모델 동작이 달라질 수 있다"고 경고합니다. 각 도구에 해당 도구가 사용하는 프로토콜을 지정하세요. Claude Code에는 Messages, Codex에는 Responses를 사용합니다. 10월 24일 AIHubMix에서는 네 가지 K3.1 Pro ID 모두 Chat Completions와 Messages 요청에 추론 내용이 포함된 응답을 반환했습니다. 각각 reasoning_content와 thinking 블록으로 제공됐습니다. Responses는 코딩 채널에서 reasoning 항목을 포함해 정상 작동했고, 기본 ID에서는 앞서 설명한 404 오류를 반환했습니다.
• Messages API의 구조화된 출력이 개선됐습니다. AIHubMix에서 7월에 K3를 테스트했을 때 /v1/messages는 스키마를 무시하고 일반 텍스트를 반환했습니다. 10월 24일에는 JSON을 요청하지 않는 프롬프트와 output_config.format의 JSON 스키마를 사용해 K3.1 Pro에 같은 종류의 요청을 보냈고, 네 가지 ID 모두 {"city":"Paris"}를 반환했습니다. 필드가 하나뿐인 스키마이므로 JSON 처리를 다시 Messages로 옮기기 전에 출력을 검증하세요. 7월에 발견된 또 다른 Messages 관련 동작, 즉 중지 시퀀스에 도달했을 때 end_turn과 stop_sequence: null을 반환하는 현상은 다시 테스트하지 않았습니다.

긴 요청

• 타임아웃을 짧게 설정하면 그다지 크지 않은 요청도 실패합니다. 간단한 점검에서 K3.1 Pro는 low 설정으로 완전한 답변을 생성하는 데 80~99초가 걸렸습니다. 타임아웃이 60초인 비스트리밍 클라이언트라면 모든 실행이 실패하고, 재시도하면 같은 추론에 다시 비용을 지불하게 됩니다. Moonshot API에서 K3.1 Pro의 기본 출력 한도는 131,072토큰이며 최대 1,048,576토큰입니다. AIHubMix의 7월 K3 게임 빌드 요청은 한 번의 요청에 2,541초가 걸렸습니다. 스트리밍을 사용하고 타임아웃은 분 단위로 설정하세요.

K3 가이드에서 이어지는 내용

다음 내용은 K3 가이드에 나와 있습니다.

• reasoning_content를 제외하면 멀티턴 품질이 저하됩니다. reasoning_content와 tool_calls를 포함한 전체 assistant 메시지를 변경 없이 다시 전달해야 합니다. content만 보존하는 코드도 실행은 되지만, Moonshot은 출력 품질이 불안정해질 수 있다고 경고합니다.
• 도구 메시지를 누락하면 동적 도구가 사라집니다. K3에서는 내용이 없는 시스템 메시지를 통해 대화 중간에 도구를 불러올 수 있습니다. 서버가 이 메시지를 보관하지 않으므로 요청할 때마다 다시 보내야 합니다. AIHubMix에서는 Chat Completions를 통해 이 기능이 작동합니다. 10월 24일에는 이런 방식으로 주입한 도구를 kimi-k3.1-pro가 호출했습니다. AIHubMix에서 7월에 진행한 K3 테스트에서는 Messages API가 주입된 도구를 무시했습니다.

놓치기 쉬운 결제 규칙

아래 가격은 AIHubMix 모델 페이지의 가격이며, 토큰 100만 개당 요금입니다.

AIHubMix에서 K3.1 Pro는 K3보다 입력 및 캐시된 입력이 30%, 출력이 26% 저렴합니다. Highspeed는 입력과 출력 요금이 Pro의 두 배이며 캐시 요금은 같습니다. 코딩 채널 ID는 별도 요금이 적용되어 입력 $0.88, 출력 $3.23, 캐시 $0.132입니다.

요금이 낮다고 해서 청구액도 반드시 줄어드는 것은 아닙니다. AIHubMix에서 7월에 K3로 실행한 게임 빌드 요청 하나를 살펴보세요. 출력 토큰은 74,994개였고 입력 토큰은 5,000개로 가정했습니다. 토큰 수가 같다면 비용은 K3에서 약 $1.08, K3.1 Pro에서 약 $0.80(5,000 × $2.00 + 74,994 × $10.50, 토큰 100만 개당), Highspeed에서 약 $1.59입니다. 토큰 수는 프롬프트에 따라 달라집니다(간단한 점검에서 K3.1 Pro와 K3는 low 설정으로 비슷한 범위였습니다). 예산을 세우기 전에 직접 측정하세요.

Moonshot API 문서에 따르면 K3.1 Pro의 캐시 쓰기 요금은 K3와 마찬가지로 TTL이 5분인지 1시간인지에 따라 달라집니다. 요금 구조는 Moonshot의 컨텍스트 캐싱 가이드에 나온 K3의 공개 요금에서 확인할 수 있습니다.

Moonshot에 따르면 캐시 쓰기 요금을 별도 항목으로 분리해도 K3의 총요금은 오르지 않았습니다. 쓰기 비용은 이미 입력 요금에 포함되어 있어 기본 TTL 5분을 사용하는 요청의 비용은 이전과 같습니다.

이 요금은 Moonshot을 직접 사용할 때 적용됩니다. AIHubMix 모델 페이지에는 입력, 출력, 캐시된 입력 요금만 나와 있고 별도의 캐시 쓰기 요금은 없으며, TTL 1시간의 쓰기가 어떻게 청구되는지도 설명되어 있지 않습니다. AIHubMix는 TTL 값을 전달하기는 합니다. 10월 24일에 최상위 수준의 cache_control TTL을 1h로 지정한 Messages 요청은 쓰기 항목을 1시간 캐시 토큰으로 보고했고, prompt_cache_options를 사용한 Chat Completions 요청도 수락됐습니다.

• 캐싱은 자동으로 적용됩니다. K3의 기본 TTL은 5분입니다. 10월 24일 AIHubMix 점검에서는 토큰 93개로 이루어진 프롬프트를 반복 전송했을 때 코딩 채널에서는 전체가 캐시된 것으로 응답했지만 기본 ID에서는 그렇지 않았습니다. 토큰 7,658개로 이루어진 프롬프트의 경우 kimi-k3.1-pro에 두 번째 요청을 보내자 Chat Completions와 Messages 모두 캐시된 토큰 7,424개를 반환했습니다.
• Moonshot API에서 TTL 1시간 설정은 K3 요금 기준으로 토큰 100만 개당 쓰기 비용이 $3.00 더 듭니다. 캐시 적중 한 번마다 $2.70을 절약하므로 Moonshot의 계산에 따르면 두 번째 적중부터 비용을 회수할 수 있습니다.
• TTL은 최초 쓰기 시점에 고정됩니다(K3). 캐시 항목의 TTL을 5분에서 1시간으로 늘릴 수 없습니다. 먼저 만료될 때까지 기다려야 합니다.
• 비용 대시보드에 새 필드가 필요합니다(K3). 캐시 쓰기는 Chat Completions에서 prompt_tokens_details.cache_write_tokens, Responses에서 input_tokens_details.cache_write_tokens, Messages에서 cache_creation_input_tokens로 표시됩니다.
• 추론 토큰은 출력으로 계산됩니다. K3에서는 모든 추론 강도 설정에서 사고 토큰에 출력 요금이 부과됩니다. AIHubMix는 K3.1 Pro의 추론 요금을 별도로 표시하지 않습니다.

비용을 낮추는 방법:

1. 기본값인 max를 그대로 사용하지 말고 작업에 따라 reasoning_effort를 설정하세요. 정보 조회와 분류에는 low를, 일반적인 코딩에는 high를 사용해 보세요.
2. 세션마다 모델과 추론 강도를 고정하고, 둘 중 하나를 변경하면 새 세션을 시작하세요.
3. 변하지 않는 내용을 먼저 배치하세요. 시스템 프롬프트, 도구 정의, 저장소 컨텍스트를 앞에 두고 그다음에 바뀌는 턴을 넣으세요.
4. 모델 출력 대기 시간이 병목인 경우에 Highspeed를 사용하고, 도구 호출이 대부분인 반복 작업에는 사용하지 마세요.
5. 완료 토큰 중 사고 토큰이 차지하는 비율을 살펴보세요. 간단한 작업에서도 절반을 넘는다면 추론 강도를 낮추세요.

실제 권한을 가진 에이전트

Hermes Agent 이슈는 마이그레이션 버그가 어떻게 안전성 버그로 이어지는지 보여줍니다. 이 도구의 "스마트 승인" 분류기는 온도를 지정해 k3를 호출했고, 호출할 때마다 400 오류가 발생했습니다. 제보자의 표현에 따르면 분류기는 "매 호출마다 상위 단계로 에스컬레이션합니다(fail-open)." 안전 검사가 제 역할을 하지 못했지만 기본 채팅에서는 이상이 드러나지 않았습니다.

K3.1 Pro에서도 같은 문제가 발생할 수 있으며 한 가지 문제가 더 있습니다. 분류기 호출은 낮은 온도를 설정하거나 사고 기능을 끄는 방식으로 빠르고 저렴하게 처리하는 경우가 많은데, K3.1 Pro에서는 두 방식 모두 작동하지 않습니다. 온도를 지정하면 매번 400 오류가 발생할 수 있고, AIHubMix에서는 사고 기능을 끈 요청이 추론 내용 없이 돌아왔습니다. K3.1 Pro에서 안전 검사를 실행한다면 속도를 위해 reasoning_effort: "low"를 사용하고, API 오류 발생 시 어떤 동작을 할지 정한 다음 fail-closed 방식으로 처리하세요.

스스로 동작하는 에이전트에서는 몇 가지를 더 고려해야 합니다.

• 강제 도구 호출이 작동합니다. K3.1 Pro는 K2.x에서 거부했던 tool_choice: "required"를 지원하므로, 도구 호출을 강제하기 위해 K2.x에서 사용하던 우회 방법을 더 이상 쓸 필요가 없습니다.
• 내장 웹 검색은 프로덕션용으로 준비되지 않았습니다(K3). Moonshot의 K3 가이드는 웹 검색 기능이 "업데이트 중이며 당분간 프로덕션 워크플로에서는 권장하지 않는다"고 설명합니다. Moonshot이 달리 안내할 때까지 K3.1 Pro에서도 마찬가지로 취급하세요. AIHubMix에서는 10월 24일 K3.1 Pro 검색 루프가 완료되지 않았습니다. 모델이 $web_search를 요청했고 결과를 다시 전송하자 400 Invalid request: tokenization failed를 반환했습니다.
• 이미지를 입력하려면 base64가 필요합니다. K3는 공개 이미지 URL을 가져오지 못합니다. 10월 24일 AIHubMix의 kimi-k3.1-pro도 이미지 URL 하나를 400 Invalid request: unsupported image url 오류로 거부했습니다. 따라서 스크린샷 링크를 전달하는 에이전트에서는 오류가 발생합니다. Moonshot에서 제공하는 또 다른 방법인 자체 파일 업로드의 파일 ID는 AIHubMix에서 지원되지 않습니다. ms:// 참조를 사용하자 404가 반환됐습니다. base64 이미지는 정상적으로 처리됐습니다. K3.1 Pro는 Kimi Code에서 비디오 입력도 지원합니다.

코딩 도구: Claude Code와 Codex

Claude Code는 Anthropic Messages API를 사용하며, 10월 24일 AIHubMix의 기본 ID에서 응답을 받았습니다. Codex는 Responses API를 사용하며, 코딩 채널에서만 응답을 받았습니다. 설치와 기본 설정은 AIHubMix의 상시 제공 가이드에 설명되어 있습니다. 아래에서는 K3.1 Pro에서 달라지는 내용만 다룹니다.

Codex 열은 Responses API에서 기본 ID가 응답할 때까지 코딩 채널 ID를 사용합니다. 도구가 이 세 가지 외의 effort 값을 보내면 위 effort 표에 따라 매핑됩니다.

Claude Code

Claude Code settings.json 설정 가이드를 따르세요. 그런 다음 기본 모델뿐 아니라 모든 모델 티어를 설정하세요:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-aihubmix-key",
    "ANTHROPIC_MODEL": "kimi-k3.1-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "kimi-k3.1-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-k3.1-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "kimi-k3.1-pro",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "kimi-k3.1-pro",
    "CLAUDE_CODE_SUBAGENT_MODEL": "kimi-k3.1-pro"
  }
}

Moonshot의 Kimi Code 문서와 K3용으로 작성된 Claude Code 가이드, 그리고 AIHubMix 테스트에서 확인된 알려진 문제는 다음과 같습니다:

• 새 세션을 시작하세요. 실행 중인 K3 세션을 K3.1 Pro로 전환하지 마세요. 새 세션을 열어 캐시와 출력 품질을 처음부터 새로 시작하세요.
• 설정하지 않은 티어는 아무 알림 없이 실패합니다. Claude Code는 기본 채팅, 요약, 하위 에이전트에 서로 다른 티어를 사용합니다. Moonshot은 일부 티어만 설정하면 나머지는 "아무 알림 없이 실패"한다고 경고합니다. 백그라운드 작업에는 Haiku 티어를 더 저렴한 모델로 지정할 수 있습니다.
• 오래된 설정이 우선 적용됩니다. env 블록의 ~/.claude/settings.json에 있는 이전 값이 셸에서 내보낸 변수를 덮어씁니다.
• 1M 컨텍스트. Moonshot의 K3 가이드에서는 Claude Code가 컨텍스트 창을 1M으로 인식하도록 kimi-k3[1m]을 사용합니다. AIHubMix에서도 kimi-k3.1-pro[1m]을 같은 방식으로 사용할 수 있습니다. Claude Code는 요청을 보내기 전에 접미사를 제거하며, AIHubMix는 10월 24일 1M 컨텍스트 헤더가 포함된 요청에 응답했습니다. 이 접미사를 인식하는 것은 Claude Code뿐입니다. 다른 클라이언트에서 모델 ID로 보내면 kimi-k3.1-pro[1m]은 400을 반환합니다.
• Effort. K3.1 Pro의 기본값은 이미 max이며, Moonshot의 K3 가이드에서 CLAUDE_CODE_EFFORT_LEVEL=max와 함께 권장한 수준입니다. 일상적인 작업에는 high를 사용하면 토큰을 덜 소비합니다. Claude Code가 어떤 수준을 보내든 effort 표에 따라 매핑되며, AIHubMix는 테스트한 다섯 가지 값 모두를 허용했습니다.
• Highspeed 티어. 티어를 kimi-k3.1-pro-highspeed로 지정한다면 ID를 정확히 복사하세요. Kimi Code에서는 오타가 나도 아무 알림 없이 기본값으로 돌아가지만, AIHubMix에서는 ID를 잘못 입력하면 400을 반환합니다.

Codex

Codex는 Responses API만 지원하므로 wire_api = "responses"가 필요합니다. 나머지 설정은 Codex config.toml 설정 가이드를 참고하세요. K3.1 Pro를 사용할 때는 다음 사항을 따르세요:

# At launch (24 October 2026), the main ID kimi-k3.1-pro returned 404 on the Responses API.
# Use the coding-channel ID until AIHubMix adds it. AIHubMix labels the
# coding channel an evaluation preview, not for production.
model = "coding-kimi-k3.1-pro"
model_provider = "aihubmix"
model_context_window = 1048576
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
env_key = "AIHUBMIX_API_KEY"
wire_api = "responses"

• 컨텍스트 창을 선언하세요. model_context_window가 없으면 Codex는 자신이 알지 못하는 모델에 기본 메타데이터를 사용합니다. K3용으로 작성된 Moonshot의 Codex 가이드에 따르면, 그 결과 표시되는 Model metadata for kimi-k3 not found 경고는 예상된 것이며 무해합니다.
• Effort. Codex 자체 수준에는 medium과 xhigh가 있습니다. Kimi Code 매핑에 따르면 각각 high와 max로 실행되며, AIHubMix는 10월 24일 두 값 모두를 허용했습니다. 어떤 수준에 비용을 지불하는지 명확히 알 수 있도록 low, high 또는 max를 설정하세요.
• 채널마다 다릅니다. 코딩 채널에서는 기본 ID가 거부한 temperature 값이 허용되었습니다. 기본 ID가 Responses에서 응답하기 시작하면 전환하기 전에 스모크 테스트를 다시 실행하세요.
• search_context_size는 지원되지 않습니다. 설정에 이 항목이 있다면 삭제하세요(심각한 오류 항목 참고).
• 수정 후 재시작하세요. Codex는 시작할 때만 config.toml을 읽습니다. CC Switch가 Codex 설정을 관리한다면 수정 사항을 덮어쓸 수 있습니다.

15분 스모크 테스트

테스트 스위트가 있는 작은 저장소에서 도구마다 한 번씩 실행하세요:

1. K3.1 Pro에서 새 세션을 시작하세요. K3나 다른 모델에서 사용하던 세션을 이어서 사용하지 마세요.
2. 다음과 같이 요청하세요: "이 저장소의 함수 하나에 대한 단위 테스트를 추가하고, 테스트를 실행한 다음 실패하는 항목을 수정해 주세요."
3. 성공 기준은 다음과 같습니다: 모델이 파일을 읽고 테스트를 실행합니다(도구 호출이 작동함). 결과를 확인한 뒤에도 계속 진행하는데, 이는 추론과 도구 결과가 다시 모델에 전달되고 있음을 보여줍니다. 테스트가 모두 통과한 상태로 끝나며, 세션 어디에도 400이나 404가 없습니다.
4. AIHubMix 사용량 로그에서 설정한 모델 ID가 사용되었는지, 이후 요청에 안정적인 접두사의 캐시 입력 토큰이 표시되는지 확인하세요. 끝내 표시되지 않는다면 매 턴마다 접두사의 일부가 바뀌고 있는 것입니다.
5. 턴에 걸린 시간과 완료 토큰 수를 기록하세요. 이를 기준으로 effort 수준을 선택하고 Highspeed가 비용을 들일 만한지 판단할 수 있습니다.

마이그레이션 체크리스트

• K3.1 Pro ID를 사용하세요. Moonshot API와 AIHubMix에서는 kimi-k3.1-pro, Kimi Code에서는 k3.1-pro를 사용하고, AIHubMix를 통한 Codex에는 현재 coding-kimi-k3.1-pro를 사용하세요.
• Moonshot이 2026년 12월 말에 K2 시리즈를 종료하기 전에 K2.x 코드를 옮기세요. 신규 Moonshot 계정은 10월 31일부터 K2를 사용할 수 없습니다.
• 기존 세션을 전환하지 말고 K3.1 Pro용 새 세션을 시작하세요.
• 헬퍼 호출을 포함한 모든 호출 경로에서 temperature, top_p, n, 그리고 두 가지 페널티를 제거하세요.
• effort 값 off, none, disabled를 포함해 thinking을 끄는 모든 설정을 제거하고, 남아 있는 K2.x thinking 블록도 삭제하세요.
• effort는 low, high 또는 max로 보내세요. medium은 high로, xhigh는 max로 실행됩니다.
• 세션 내내 모델과 effort를 고정하세요.
• Highspeed ID를 정확히 복사하고 사용량 로그에서 모델을 확인하세요.
• stop 목록은 32바이트 이하인 항목 다섯 개로 제한하세요.
• reasoning_content와 tool_calls를 포함한 전체 어시스턴트 메시지를 반환하고, 동적 도구 메시지를 다시 보내세요.
• 요청이 길면 스트리밍을 사용하고 제한 시간을 분 단위로 설정하세요.
• JSON을 Messages API로 옮기기 전에 구조화된 출력을 검증하세요.
• 별도의 캐시 쓰기 필드에 맞게 비용 추적을 업데이트하세요.
• 안전성 검사에서 API 오류가 발생하면 기본적으로 차단되도록 설정하세요.
• 각 코딩 도구에서 스모크 테스트를 실행하세요.

자주 묻는 질문

K3.1 Pro가 HTTP 400을 반환하는 이유는 무엇인가요?
흔한 원인은 1이 아닌 temperature, thinking 비활성화, 또는 off, none, disabled나 알 수 없는 effort 값입니다. 첫 번째는 K3의 고정 샘플링 규칙에서 비롯되며 K3.1 Pro에도 그대로 적용됩니다. 나머지는 Moonshot의 Kimi Code 문서에 명시되어 있습니다. 10월 24일 AIHubMix 기본 ID에서는 temperature만 400을 반환했습니다. 나머지는 200을 반환했고, thinking을 끄거나 none으로 설정하면 추론 없이 응답했습니다.

thinking을 끌 수 있나요?
아니요. K3.1 Pro는 thinking 모드로만 실행됩니다. thinking을 짧게 유지하려면 reasoning_effort를 low로 설정하세요.

temperature는 여전히 거부되나요?
네. Moonshot API와 AIHubMix 기본 ID에서는 2026년 10월 24일 "invalid temperature: only 1 is allowed for this model"을 반환했습니다. 같은 테스트에서 AIHubMix 코딩 채널은 temperature 0.2를 허용했습니다. 모든 경로에서 temperature를 생략하세요.

K2 모델은 언제 사라지나요?
2026년 10월 31일부터 신규 가입한 Moonshot 사용자는 K2 시리즈 모델을 사용할 수 없으며, Moonshot은 2026년 12월 말까지 모든 모델을 종료할 계획입니다. 10월 24일 기준 AIHubMix에는 K2.6과 K2.7 Code가 여전히 등록되어 있었고, 종료 일정은 공지되지 않았습니다.

Kimi Code 할당량이 왜 더 빨리 소진되나요?
K3.1 Pro는 기본값이 max effort입니다. Kimi Code에서 K3의 기본값이 high였던 것과 다릅니다. 또한 Highspeed는 일반 모델보다 할당량을 약 두 배 사용합니다. 일상적인 작업에는 더 낮은 effort를 설정하고 세션 내내 고정하세요.

Highspeed가 더 빠르지 않은 이유는 무엇인가요?
ID를 잘못 입력했을 수 있습니다. Kimi Code에서는 thinking 기능이 없는 K2.8 Preview로 아무 알림 없이 전환됩니다. 또는 턴의 대부분을 도구 호출이 차지할 수도 있습니다. Highspeed는 모델 출력을 더 빠르게 할 뿐입니다.

Codex에는 어떤 AIHubMix 모델 ID를 사용해야 하나요?
현재는 aihubmix.com/v1의 Responses API에서 coding-kimi-k3.1-pro를 사용하고 wire_api를 responses로 설정하세요. 10월 24일 기준 기본 ID는 Responses API에서 404를 반환했습니다. AIHubMix는 코딩 채널을 프로덕션용이 아닌 평가용 프리뷰로 표시합니다.

계속 읽기: Kimi K3.1 Pro 시리즈

• 마이그레이션 전에 업그레이드가 정말 그만한 가치가 있는지, 변경 사항부터 실제 작업 하나의 비용까지 확인해 보세요: Kimi K3.1 Pro vs K3: 달라진 점, 비용, 전환해야 할 사용자
• 마이그레이션을 고민하며 대안을 비교하고 있다면 K3.1 Pro와 Qwen 4, Claude Fable 5.5를 비교하고, 각 모델에서 프런트엔드 빌드 하나에 드는 비용을 확인해 보세요: Kimi K3.1 Pro vs Qwen 4 vs Claude Fable 5.5: 프런트엔드 품질, 작업당 비용, 과장된 기대 점검
• Highspeed의 할당량과 가격을 보고 빠른 버전이 제값을 하는지 궁금하다면, 속도와 가격의 상관관계를 다룬 별도 글을 확인하세요: Kimi K3.1 Pro vs K3.1 Pro Highspeed: 속도가 2–3배 빨라지는데 가격도 2배라면 그만한 가치가 있을까?

출처

• Kimi Code: 모델 설정
• Moonshot AI: 모델 매개변수 참고 자료
• AIHubMix: Kimi K3.1 Pro 모델 페이지
• AIHubMix: Kimi K3 실전 가이드
• Hermes Agent 이슈 #142365: Kimi Code 엔드포인트 프로필 불일치