Kimi API 연동 튜토리얼: Base URL, 모델명, 첫 호출 (2026)

Kimi API는 OpenAI 인터페이스와 호환되므로 이전할 때 보통 세 곳만 바꾸면 됩니다. Base URL, API 키, 모델명입니다. 하지만 2026년 인터페이스에는 놓치기 쉬운 세부 사항이 몇 가지 있습니다. 구형 모델은 종료되었고, max_tokens는 폐기되었으며, K3는 기본적으로 최고 추론 강도를 사용하고, 스트리밍 요청의 사용량은 마지막 블록에서만 반환됩니다.

이 글은 처음부터 연동을 진행합니다. 먼저 사이트와 프로토콜을 확인하고, 모델을 고른 뒤 curl과 Python 첫 호출을 완료하고, 마지막으로 이전 체크리스트와 오류 대조표를 제공합니다. 모델과 가격은 사이트 내 모델 가격을 기준으로 합니다.

안내: Moonshot과 Kimi는 해당 권리자의 상표이며 이 글은 기술 연동 설명만 제공합니다. 모델 목록, 컨텍스트 길이, 파라미터 규칙은 조정될 수 있으므로 공식 문서의 현재 버전을 기준으로 하세요.

1. 연동 전에 확인할 세 가지

사이트: 중국 사이트는 platform.kimi.com, 국제 사이트는 platform.kimi.ai를 씁니다. 두 사이트의 계정, 잔액, 키는 완전히 독립적입니다.
프로토콜: 대부분의 프로젝트는 OpenAI 호환 Chat Completions를 씁니다. 이미 Anthropic SDK를 쓰는 프로젝트는 Messages 호환 진입점을 사용할 수 있습니다.
모델: 계정에서 어떤 모델을 볼 수 있는지 먼저 확인하고 코드에 적으세요. 몇 달 전 튜토리얼을 그대로 복사하지 마세요.

중국 사이트의 요청 도메인은 https://api.moonshot.cn, 국제 사이트는 https://api.moonshot.ai입니다. 도메인과 키는 반드시 함께 맞아야 하며 이것이 401의 가장 흔한 원인 중 하나입니다.

2. Base URL과 인터페이스 경로

프로토콜	Base URL	인터페이스 경로
OpenAI Chat Completions	`https://api.moonshot.cn/v1`	`/chat/completions`
OpenAI Responses	`https://api.moonshot.cn/v1`	`/responses`
Anthropic Messages	`https://api.moonshot.cn/anthropic`	`/v1/messages`
모델 목록	`https://api.moonshot.cn/v1`	`/models`
잔액 조회	`https://api.moonshot.cn/v1`	`/users/me/balance`

국제 사이트는 도메인을 api.moonshot.ai로 바꾸고 경로는 그대로 둡니다. OpenAI SDK의 base_url은 /v1까지만 적으면 SDK가 /chat/completions를 스스로 붙입니다. curl은 전체 경로를 적어야 합니다. 둘을 섞으면 /v1이 한 겹 더 붙거나 빠져 404가 납니다.

Anthropic 호환 진입점의 Base URL에는 /v1이 붙지 않는다는 점이 OpenAI 진입점과 다릅니다. Claude Code나 다른 Anthropic SDK로 연동할 때는 공식 예시대로 https://api.moonshot.cn/anthropic을 적으세요.

3. 모델명 선택

모델명	컨텍스트	적합한 작업	주의
`kimi-k3`	1M	복잡한 추론, 소프트웨어 공학, 지식 작업, 초장문 문서	기본 `reasoning_effort`가 `max`
`kimi-k2.7-code`	256K	코드 생성, 저장소 질의응답, Agent	긴 컨텍스트 지시 준수가 더 좋음
`kimi-k2.7-code-highspeed`	256K	저지연 완성, 대화형 코딩	표준판과 같은 모델, 속도가 더 빠름
`kimi-k2.6`	256K	범용 대화, 추출, 비전·텍스트 입력	사고·비사고 모드 지원

구형 모델은 종료되었습니다. moonshot-v1 전 시리즈와 kimi-k2.5는 2026년 8월 31일 지원이 중단되었고, kimi-k2 시리즈는 2026년 5월 25일 중단되었으며 kimi-latest는 더 이릅니다. 아직 이 이름을 쓰는 프로젝트는 업그레이드 시 kimi-k3나 K2 시리즈로 바로 옮기고 오래된 문서를 계속 찾지 마세요.

범용 작업에 무조건 K3를 쓸 필요는 없습니다. K3는 능력이 강하지만 기본 추론 강도가 높아 지연과 출력 토큰이 늘어납니다. 단순 분류, 고정 형식 추출에는 kimi-k2.6이 더 적합한 경우가 많습니다. 코드 작업에서 K2.7 Code 시리즈를 고려하세요.

4. 첫 호출: curl

export MOONSHOT_API_KEY="여기의-키"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "연동 성공이라고만 답하세요"}
    ],
    "max_completion_tokens": 64
  }'

200이 반환되고 내용이 예상과 같으면 키, 사이트, 모델명, 경로 네 가지가 모두 통과한 것입니다. 401이면 사이트와 키가 짝이 맞는지, 404면 모델명과 /v1을, 400이면 오류 메시지에 컨텍스트나 출력 상한 언급이 있는지 먼저 확인하세요.

5. Python SDK와 스트리밍 출력

OpenAI SDK 1.0 이상을 설치하고 base_url과 키만 바꾸면 됩니다.

import os
from openai import OpenAI

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

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "API 게이트웨이가 어떤 팀에 적합한지 세 가지로 설명하세요"}],
    max_completion_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:
        print("\n사용량: ", chunk.usage)

스트리밍 응답은 SSE이며 각 줄이 data:로 시작하고 data: [DONE]으로 끝납니다. include_usage를 켜면 종료 전에 choices가 비어 있고 usage만 담은 블록이 한 번 더 반환됩니다. 연결이 중간에 끊기면 이 블록을 받지 못할 수 있으므로 사용량 집계를 전적으로 클라이언트에 의존하지 마세요.

6. max_completion_tokens와 추론 강도

max_tokens는 폐기되었고 새 코드는 max_completion_tokens를 씁니다. 이는 입력과 출력을 합친 총길이가 아니라 생성하려는 출력 길이를 뜻합니다. K3의 기본값은 131072이고 최대 1048576까지 설정할 수 있습니다. 입력에 이 값을 더한 길이가 컨텍스트 창을 넘으면 요청이 invalid_request_error를 반환합니다.

실용적인 규칙 두 가지입니다.

테스트와 고정 형식 작업은 256에서 1024처럼 작게 설정해 장문 출력을 막습니다.
상한에 도달하면 finish_reason이 length이고 정상 종료는 stop입니다. length를 보면 곧바로 재시도하지 말고 출력이 정말 더 필요한지, 프롬프트가 너무 열려 있는지 먼저 판단하세요.

K3에는 최상위 파라미터 reasoning_effort가 있고 low, high, max를 선택할 수 있으며 기본은 max입니다. 단순 작업은 low로 낮춰 지연과 토큰 소비를 줄이고 복잡한 추론은 올리세요. OpenAI SDK 버전에 이 파라미터가 내장되어 있지 않다면 extra_body로 전달합니다. K3의 사고 내용은 reasoning_content에 있으며 멀티턴 대화와 도구 호출에서는 그대로 되돌려 보내야 합니다.

7. OpenAI 또는 구형 Moonshot에서 이전

코드와 설정의 모든 구형 모델명을 찾아 교체 표를 만듭니다.
base_url을 수정합니다. 중국 사이트는 https://api.moonshot.cn/v1, 국제 사이트는 https://api.moonshot.ai/v1입니다.
해당 사이트의 키로 교체하고 사이트 간에 재사용하지 않습니다.
모델명을 교체하고 kimi-k3 또는 K2 시리즈의 현재 모델을 우선 사용합니다.
max_tokens를 max_completion_tokens로 바꿉니다.
K2.x의 thinking 설정을 K3의 reasoning_effort로 바꾸고 둘을 동시에 보내지 않습니다.
스트리밍 요청에 stream_options={"include_usage": True}를 추가합니다.
같은 실제 작업 세트로 회귀 테스트를 실행해 품질, 지연, finish_reason, 사용량을 기록합니다.
구형 설정을 한 번의 릴리스 주기 동안 남겨 두고 이상이 없으면 삭제합니다.

한 번에 전면 전환하지 마세요. 테스트 환경, 저위험 업무, 핵심 경로 순으로 옮기고 각 단계에 롤백 스위치를 두세요.

8. 자주 발생하는 오류 대조표

상태 코드	오류 유형	흔한 원인	처리
400	`invalid_request_error`	파라미터 오류, 컨텍스트 초과, 출력 상한 초과	요청 수정
400	`content_filter`	입력 또는 출력이 콘텐츠 안전 정책에 걸림	프롬프트 조정
401	`invalid_authentication_error`	키 무효, 사이트 불일치	키 교체 또는 도메인 수정
404	`resource_not_found_error`	모델명 또는 경로 오류	모델 목록 확인
429	`rate_limit_reached_error`	동시성, RPM, TPM, TPD 초과	속도 낮추기 또는 등급 상향
429	`exceeded_current_quota_error`	연체 또는 잔액 부족	충전
504	`Gateway Time-out`	비스트리밍 장기 요청 대기 초과	스트리밍으로 전환

비스트리밍 요청이 서버에서 900초를 넘겨 대기하면 504가 반환될 수 있습니다. 장문 생성, 긴 문서 분석, 코드 Agent는 가능하면 스트리밍을 써서 클라이언트가 계속 데이터를 받게 하고 "타임아웃까지 기다린 뒤 재시도"하는 낭비를 줄이세요.

자주 묻는 질문

Base URL은 어느 계층까지 적어야 하나요?

OpenAI SDK는 https://api.moonshot.cn/v1까지만 적고 /chat/completions를 붙이지 않습니다. curl은 https://api.moonshot.cn/v1/chat/completions 전체를 적어야 합니다. Anthropic SDK는 https://api.moonshot.cn/anthropic을 씁니다.

max_tokens가 적용되지 않는 이유는 무엇인가요?

이 파라미터는 폐기되어 일부 모델이 무시하거나 오류를 냅니다. max_completion_tokens로 바꾸고 이것이 입력을 포함한 상한이 아니라 출력 상한임을 기억하세요.

K3 응답이 예상보다 느린 이유는 무엇인가요?

K3의 기본 reasoning_effort가 max라 추론을 깊게 수행합니다. 단순 작업은 low나 high로 낮추고 출력 길이를 제한하면 지연이 보통 눈에 띄게 개선됩니다.

스트리밍이 끝났는데 usage가 없는 이유는 무엇인가요?

stream_options={"include_usage": True}를 명시해야 합니다. 설정해도 연결이 끊기면 마지막 블록을 받지 못할 수 있으므로 운영 환경에서는 서버 측에서 별도로 사용량을 기록하세요.

OpenAI에서 이전할 때 또 무엇을 바꿔야 하나요?

대부분의 코드는 Base URL, 키, 모델명만 바꿉니다. 추가로 max_tokens, 스트리밍 사용량, 오류 유형 매핑, 재시도 전략, 특히 429 분류 처리를 확인하세요.

다음 단계

먼저 ZSQH AI 게이트웨이에서 테스트 키를 만들고 kimi-k3와 kimi-k2.6으로 각각 실제 작업을 하나씩 실행해 경로를 확인한 뒤 운영에 연동하세요. 사용 가능 모델과 과금은 모델 가격을 기준으로 합니다.