Kimi K2.6 API 호출법: Moonshot에서 모델 ID 헷갈리지 않기

안전한 호출 순서

1. Moonshot API 키를 준비합니다. Kimi API 예시는 Authorization: Bearer ... 헤더를 사용하고, TypingMind 문서도 Moonshot API 계정 생성, 잔액 충전, API 키 발급 흐름을 설명합니다.
2. 클라이언트를 OpenAI 호환 방식으로 설정합니다. OpenAI SDK를 쓴다면 base_url만 https://api.moonshot.ai/v1로 바꾸는 것이 핵심입니다.
3. 실제 요청 전에 /models를 호출합니다. List Models 엔드포인트는 현재 모델 목록과 id를 반환하므로, 여기서 받은 값을 model 파라미터로 쓰는 것이 안전합니다.
4. 채팅 요청은 model과 messages로 보냅니다. Kimi의 Chat API 문서는 model과 messages를 포함한 요청 형태를 보여주고, API Overview는 /chat/completions 경로를 안내합니다.
5. 결제나 대량 처리도 미리 점검합니다. 잔액 확인은 /users/me/balance, 배치 생성은 /batches 엔드포인트를 사용할 수 있습니다.

Python: OpenAI SDK로 호출하기

아래 예시는 Kimi 문서가 안내한 Moonshot base_url을 사용합니다. KIMI_MODEL_ID에는 GET /models 응답에서 확인한 id를 넣어야 하며, 제품명이나 다른 서비스의 모델명을 임의로 넣지 않는 것이 좋습니다.

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model=os.environ['KIMI_MODEL_ID'],
    messages=[
        {'role': 'user', 'content': '안녕하세요. 짧게 자기소개해 주세요.'}
    ],
)

print(response)

cURL: 모델 ID 확인 후 채팅 요청

먼저 인증한 계정에서 모델 목록을 조회합니다. 이 엔드포인트는 모델 목록과 각 모델의 id를 반환합니다.

curl -sS https://api.moonshot.ai/v1/models -H 'Authorization: Bearer $MOONSHOT_API_KEY'

응답에서 Kimi K2.6에 해당하는 id를 확인한 뒤, 그 값을 Chat Completions 요청의 model에 넣습니다. /chat/completions 전체 경로와 model + messages 요청 구조는 Kimi 문서에서 확인됩니다.

curl -sS -X POST https://api.moonshot.ai/v1/chat/completions -H 'Authorization: Bearer $MOONSHOT_API_KEY' -H 'Content-Type: application/json' -d '{"model":"PASTE_MODEL_ID_FROM_MODELS","messages":[{"role":"user","content":"Kimi K2.6을 한 문단으로 소개해 주세요."}]}'

잔액 확인

요청이 결제 문제로 실패하거나 연동 전에 계정 상태를 확인하려면 /users/me/balance를 호출하면 됩니다. Kimi의 잔액 확인 문서는 Bearer 토큰을 사용하는 예시를 제공합니다.

curl -sS https://api.moonshot.ai/v1/users/me/balance -H 'Authorization: Bearer $MOONSHOT_API_KEY'

AIMLAPI·OpenRouter의 모델 ID를 그대로 가져오지 말 것

Kimi K2.6을 제공하는 중개 게이트웨이는 각자 다른 모델 ID를 쓸 수 있습니다. AIMLAPI 문서는 https://api.aimlapi.com/v1/chat/completions에서 moonshot/kimi-k2-6을 model로 쓰는 예시를 제공합니다. OpenRouter의 Kimi K2.6 API 페이지에는 moonshotai/kimi-k2.6 모델명이 표시됩니다.

이 값들은 해당 게이트웨이를 통해 호출할 때의 ID입니다. 공식 Moonshot 엔드포인트인 https://api.moonshot.ai/v1/chat/completions로 호출할 때는 GET https://api.moonshot.ai/v1/models를 실행해 Moonshot이 반환한 id를 사용하는 것이 가장 덜 위험합니다.

결론

실무 흐름은 간단합니다. Moonshot API 키를 준비하고, OpenAI SDK의 base_url을 https://api.moonshot.ai/v1로 맞춘 뒤, 먼저 /models에서 Kimi K2.6의 실제 id를 확인합니다. 그다음 /chat/completions에 model과 messages를 담아 보내면 됩니다. 이 과정을 따르면 Kimi의 OpenAI 호환 문서에 맞춰 구현하면서도 AIMLAPI나 OpenRouter의 게이트웨이 전용 모델 ID를 공식 Moonshot API에 잘못 넣는 실수를 줄일 수 있습니다.