Blog

키미 K3 API 사용법?

OpenAI SDK를 이용한 Kimi K3 API 호출: 파이썬, 자바스크립트, cURL 빠른 시작 가이드와 스트리밍, 도구 호출, JSON 모드, 추론 노력, 캐싱 지원.

Ashley Innocent

Ashley Innocent

17 July 2026

키미 K3 API 사용법?

Apidog 엔터프라이즈

온프레미스 배포

SSO & RBAC

SOC 2 준수

Apidog Enterprise 살펴보기

Moonshot AI는 2026년 7월 16일 Kimi K3를 출시했으며, 이를 현재까지 가장 강력한 모델이라고 설명했습니다. Kimi K3는 2.8T 매개변수 MoE(Mixture-of-Experts) 설계와 1,048,576 토큰 컨텍스트 창을 갖춘 세계 최초의 개방형 3T급 모델입니다. 개발자에게 흥미로운 부분은 모델의 크기가 아니라 API입니다. Kimi K3는 OpenAI SDK 방언을 사용하므로, 이미 GPT 또는 OpenAI 호환 엔드포인트를 호출하고 있다면 동일한 클라이언트를 kimi-k3로 연결하여 몇 분 안에 응답 스트리밍을 시작할 수 있습니다. 이 가이드에서는 키를 얻는 방법, Python, JavaScript 및 cURL을 사용한 빠른 시작, 스트리밍, 도구 호출, JSON 모드, 구성 가능한 추론 노력(reasoning-effort) 매개변수, 캐시 히트 입력 비용이 캐시 미스보다 약 10배 저렴하게 만드는 컨텍스트 캐싱에 대해 설명합니다. 그런 다음 Apidog에서 이러한 호출을 테스트하고 디버깅하여 추측하는 대신 원시 요청과 서버 전송 이벤트를 확인할 수 있습니다.

요약 (TL;DR)

어떤 Kimi 모델을 호출해야 할까요?

코드를 작성하기 전에 올바른 대상을 선택하세요. Kimi K3는 제품군의 최전선 모델입니다. 복잡한 코딩, 장기적인 에이전트 작업, 긴 컨텍스트에 걸친 지식 작업을 목표로 하는 대규모 MoE입니다. 라인업에서 토큰당 출력 비용이 가장 높으며, Moonshot 자체 출시 게시물에서도 K3가 내부 비교에서 Claude Fable 5 및 GPT-5.6 Sol에 뒤처진다고 솔직하게 언급합니다. 강력하지만 확실한 최전선 승자는 아니며, 그에 따라 가격이 책정됩니다.

작업량이 고볼륨 코딩 어시스턴트, CI 테스트 작성기 또는 대규모 호출당 비용을 지불하는 경우라면, 이전 K2.7 코드 라인이 비용 면에서 더 나은 선택인 경우가 많습니다. Kimi K2.7 코드 API 가이드와 Kimi K2.7 코드는 무엇인가 개요를 통해 해당 계층이 사용자의 사례에 적합한지 확인하세요. 기능 및 가격을 나란히 비교하려면 Kimi K3 대 Kimi K2.7 코드 비교에서 각 모델이 우위를 점하는 부분을 설명합니다. 추가적인 추론 깊이, 전체 1M 컨텍스트 또는 에이전트 도구 오케스트레이션이 필요할 때 kimi-k3를 사용하세요. 작업이 일상적이고 볼륨이 높을 때는 K2.7로 낮추세요. 전체 기능 요약이 먼저 필요한 경우, Kimi K3는 무엇인가 설명에서 아키텍처와 모델의 위치를 다룹니다.

Kimi 플랫폼에서 API 키 얻기

platform.kimi.ai로 이동하여 로그인하세요. 새 콘솔은 키를 생성하고, 사용량을 확인하고, 계정의 기본 URL을 확인하는 곳입니다.

  1. 콘솔의 API 키 섹션을 열고 새 키를 생성합니다.
  2. 한 번 복사하여 안전한 곳에 저장합니다. 전체 값을 다시 볼 수 없습니다.
  3. 크레딧을 추가하거나 결제 등급을 확인하여 kimi-k3 호출이 잔액 부족으로 거부되지 않도록 합니다.
  4. 콘솔에 표시된 기본 URL을 기록합니다. Kimi는 역사적으로 https://api.moonshot.ai/v1을 사용했습니다. 콘솔은 계정의 진실의 원천입니다.

키가 소스 코드에 들어가지 않도록 환경 변수로 내보내세요.

export KIMI_API_KEY="sk-your-key-here"

이 하나의 습관으로 Git 기록과 스크린샷에서 비밀을 보호할 수 있습니다. 나중에 Apidog에서 테스트할 때 동일한 값을 환경 변수로 저장하므로 키는 사용자가 제어하는 두 곳에만 존재합니다.

캐시 히트 대 캐시 미스 계산과 실제 월별 청구서에 어떻게 반영되는지에 대한 자세한 내용은 Kimi K3 가격 가이드를 참조하세요.

빠른 시작: 첫 번째 kimi-k3 호출

Kimi의 API는 OpenAI 채팅 완료 계약을 따르므로 공식 OpenAI SDK는 base_url과 model이라는 두 가지 변경 사항으로 작동합니다. 선호하는 SDK를 설치한 다음 아래 스니펫 중 하나를 실행하세요.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    # Kimi는 OpenAI-SDK와 호환됩니다.
    # platform.kimi.ai 콘솔에서 정확한 기본 URL을 확인하세요.
    # Kimi는 역사적으로 아래 값을 사용했습니다.
    base_url="https://api.moonshot.ai/v1",
)

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "You are a precise coding assistant."},
        {"role": "user", "content": "Explain what a token bucket rate limiter does in one paragraph."},
    ],
)

print(response.choices[0].message.content)

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KIMI_API_KEY,
  // platform.kimi.ai 콘솔에서 기본 URL을 확인하세요.
  baseURL: "https://api.moonshot.ai/v1",
});

const response = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [
    { role: "system", content: "You are a precise coding assistant." },
    { role: "user", content: "Explain what a token bucket rate limiter does in one paragraph." },
  ],
});

console.log(response.choices[0].message.content);

cURL

curl "$KIMI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KIMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain what a token bucket rate limiter does in one paragraph."}
    ]
  }'

KIMI_BASE_URL을 콘솔에 표시된 값으로 설정하세요(예: https://api.moonshot.ai/v1). 이 중 어느 것이든 401을 반환하면 키가 잘못되었거나 설정되지 않은 것입니다. 경로에서 404가 발생하면 일반적으로 모델이 없다는 의미가 아니라 기본 URL이 잘못되었다는 의미입니다. OpenAI Python SDK 문서는 클라이언트 옵션을 더 자세히 다루며, 와이어 형식이 동일하므로 여기의 모든 옵션이 적용됩니다.

응답 스트리밍

채팅 UI 및 긴 에이전트 턴의 경우 전체 완료를 기다리지 않고 토큰이 도착하는 대로 받아보고 싶을 것입니다. stream=True를 설정하고 델타를 반복합니다.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Write a 6-line poem about flaky tests."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

내부적으로 이것은 서버 전송 이벤트(SSE) 스트림입니다. 각 줄은 작은 JSON 조각을 운반하는 data: 프레임이며, 스트림은 data: [DONE]으로 끝납니다. SDK는 이 프레임을 숨기므로 편리하지만, 스트림 중간에 문제가 발생하여 원시 프레임을 봐야 할 때 문제가 될 수 있습니다. 이는 아래 Apidog 섹션이 유용하게 사용되는 한 가지 예입니다.

동일한 플래그는 JavaScript에서도 작동합니다.

const stream = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [{ role: "user", content: "Write a 6-line poem about flaky tests." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

도구 호출 (함수 호출)

Kimi K3는 도구 호출, 도구 선택 제약 조건 및 동적 도구 로딩을 지원하므로, 파일을 읽거나, API를 호출하거나, 터미널 명령을 실행하는 에이전트에 연결할 수 있습니다. JSON 스키마로 함수를 설명하면, 모델은 언제 함수를 호출할지 결정하고, 당신은 tool 메시지에 결과를 반환합니다.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name, e.g. Singapore"},
                },
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "What's the weather in Singapore right now?"}]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = first.choices[0].message.tool_calls[0]
print(tool_call.function.name)       # get_weather
print(tool_call.function.arguments)  # {"city": "Singapore"}

모델은 함수를 실행하지 않고, 이름과 JSON 인수를 전달합니다. 실제 작업을 실행한 다음, 모델이 최종 답변을 작성할 수 있도록 출력을 다시 전달합니다.

import json

# 도구를 요청한 어시스턴트 턴과 도구 결과를 추가합니다.
messages.append(first.choices[0].message)
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps({"city": "Singapore", "temp_c": 31, "sky": "humid"}),
})

final = client.chat.completions.create(model="kimi-k3", messages=messages, tools=tools)
print(final.choices[0].message.content)

tool_choice="required"를 설정하여 도구 호출을 강제하거나, 특정 {"type": "function", "function": {"name": "get_weather"}} 객체를 전달하여 하나의 함수를 고정할 수 있습니다. 이러한 제약 조건은 어떤 도구가 실행되어야 하는지 이미 알고 있을 때 에이전트가 통제된 상태를 유지하도록 합니다.

초기에 알아두면 좋은 K3 관련 함정 한 가지: 이 모델은 사고 이력 보존 모드로 훈련되었습니다. 에이전트 하네스가 턴 사이에 모델의 이전 추론을 삭제하면 생성 품질이 불안정해질 수 있습니다. 다중 턴 에이전트 루프를 구축할 때 어시스턴트의 내부 턴을 잘라내지 않고 전체 메시지 이력을 다시 전달하세요.

JSON 모드 및 구조화된 출력

기계가 읽을 수 있는 출력이 필요할 때는 산문 구문을 분석하는 대신 직접 JSON을 요청하세요. response_format을 json_object로 설정하고 모델에게 JSON을 반환하도록 지시합니다.

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "Return only valid JSON. No prose, no markdown."},
        {"role": "user", "content": "Extract name and role from: 'Ada Lovelace, mathematician'."},
    ],
    response_format={"type": "json_object"},
)

print(response.choices[0].message.content)  # {"name": "Ada Lovelace", "role": "mathematician"}

더 엄격한 보장을 위해 Kimi는 스키마에 대한 구조화된 출력을 지원합니다. SDK 버전이 이를 허용한다면, 모델이 당신의 형태에 따르도록 json_schema 응답 형식을 전달하세요.

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Extract name and role from: 'Ada Lovelace, mathematician'."}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "role": {"type": "string"},
                },
                "required": ["name", "role"],
            },
        },
    },
)

배포하기 전에 콘솔에서 계정의 json_schema 지원 여부를 확인하세요. 의심스러울 때는 json_object와 사용자 측의 유효성 검사 단계를 사용하는 것이 안전한 대체 방법입니다. Kimi는 또한 부분 모드와 인터넷 검색을 제공하여 어시스턴트 응답을 미리 채우거나 최신 데이터에 기반한 답변을 제공할 때 유용합니다.

구성 가능한 추론 노력

Kimi K3는 모델이 답변하기 전에 얼마나 많이 생각하는지를 제어하는 reasoning_effort 매개변수를 노출합니다. 현재 사용 가능한 수준은 max이며, 이는 기본값이기도 합니다. Moonshot은 더 낮은 수준과 더 높은 수준이 계획되어 있다고 말했습니다. 더 깊은 사고는 더 많은 출력 토큰 비용을 발생시키고 지연 시간을 추가하므로, 이는 작업별로 조정하는 레버입니다.

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Plan a migration from REST to GraphQL for a 40-endpoint API."}],
    reasoning_effort="max",
)

OpenAI SDK 버전이 해당 필드를 알 수 없는 필드로 거부하는 경우, 대신 예외 처리 구문을 통해 전달하세요.

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Plan a migration from REST to GraphQL."}],
    extra_body={"reasoning_effort": "max"},
)

extra_body 패턴은 기본 SDK가 아직 모델링하지 않은 공급자별 필드를 보내는 방법이며, 이는 호환 가능한 엔드포인트가 클라이언트 라이브러리보다 빠르게 발전할 때 흔히 발생합니다.

Apidog에서 kimi-k3 테스트 및 디버그

SDK 코드는 와이어 형식을 숨기는데, 이는 도구 호출이 잘못된 형태로 반환되거나 스트림이 끊어졌을 때 누구의 잘못인지 알 수 없을 때까지는 괜찮습니다. 이때 원시 HTTP를 사용하는 API 클라이언트가 빛을 발합니다. Apidog를 사용하면 정확한 kimi-k3 요청을 보내고, SSE 스트림을 프레임별로 확인하며, 요청 본문에서 키를 제외할 수 있습니다. 터미널에서 작업하지 않고 API 호출을 테스트하고 싶다면, 이것은 curl-and-squint보다 더 깔끔한 루프입니다. Postman 없이 API 테스트하기 가이드에서는 일반적인 워크플로를 다룹니다.

다음은 kimi-k3에 대한 집중적인 루프입니다.

  1. Apidog에서 새 HTTP 요청을 생성합니다. 메서드를 POST로 설정하고 URL을 기본 URL + /chat/completions로 설정합니다.
  2. 키를 환경 변수로 저장합니다. Apidog의 환경 설정에서 KIMI_API_KEY를 추가한 다음, Authorization 헤더를 Bearer {{KIMI_API_KEY}}로 설정합니다. 이제 비밀이 붙여넣기 대신 참조되며, 환경을 전환하여 테스트 및 프로덕션 키를 전환할 수 있습니다.
  3. "model": "kimi-k3"와 messages 배열이 포함된 JSON 본문을 붙여넣습니다. 이를 보내고 토큰 사용량을 포함한 전체 응답을 읽어 실제 호출에서 캐시 히트 대 캐시 미스 수를 확인할 수 있습니다.
  4. "stream": true로 전환하고 서버 전송 이벤트가 개별 프레임으로 도착하는 것을 확인합니다. 원시 data: 조각을 보면 SDK의 깔끔한 반복자가 보여주지 않는 스트리밍 버그를 명확하게 알 수 있습니다.
  5. 응답의 tool_calls 배열을 검사하여 도구 호출을 디버그합니다. 인수가 잘못된 형식으로 돌아오면 모델이 잘못된 JSON을 생성했는지 스키마가 모호했는지 확인할 수 있으며, 그 자리에서 설명을 수정할 수 있습니다.
  6. kimi-k2-7-code와 A/B 테스트를 합니다. 요청을 복제하고 model 필드만 변경한 다음, 동일한 프롬프트에서 지연 시간, 출력 품질 및 비용을 비교합니다. 이는 K3의 추가 추론이 작업에 대한 가격 상승만큼 가치가 있는지 결정하는 가장 빠르고 정직한 방법입니다.

Apidog는 OpenAI 호환 요청을 직접 가져오기 때문에 cURL 명령을 붙여넣으면 헤더와 본문이 이미 채워진 저장 및 재생 가능한 요청을 얻을 수 있습니다. 그 다음부터는 Kimi가 업데이트를 출시할 때마다 팀이 다시 실행할 수 있는 공유 테스트 케이스가 됩니다. 에이전트가 MCP를 통해 모델과 통신하는 경우, Apidog MCP 클라이언트를 사용한 시각적 디버깅 가이드에서 해당 호출을 추적하는 방법도 보여줍니다. 자신만의 키로 이 루프를 따라가고 싶다면 Apidog를 다운로드하세요.

실제 사용 사례

kimi-k3에 적합한 몇 가지 패턴은 다음과 같습니다.

이 모든 경우에 워크플로는 동일합니다. SDK로 요청을 구축하고, Apidog에서 원시 동작을 확인한 다음, 형태를 신뢰하면 앱에 연결합니다.

마무리

Kimi K3를 호출하는 것은 OpenAI 호환 클라이언트의 세 가지 설정으로 귀결됩니다. 콘솔의 기본 URL, API 키, 그리고 model="kimi-k3"입니다. 그 다음부터 스트리밍, 도구 호출, JSON 모드, 구조화된 출력 및 reasoning_effort는 모두 이미 알고 있는 채팅 완료 계약을 따릅니다. 중요한 두 가지는 캐싱 경제성으로, 안정적인 접두사를 유지하면 $3.00 입력이 $0.30 입력으로 바뀌고, K3가 추론 깊이를 실제 가격으로 구매하는 정직한 절충안이므로, 일상적인 대량 작업은 K2.7 라인으로 라우팅해야 한다는 점입니다. 코드로 요청을 구축하고 Apidog에서 검증하면 놀라움 없이 kimi-k3를 배포할 수 있습니다.

FAQ

Kimi K3의 API 모델 ID는 무엇인가요? Kimi 자체 플랫폼에서는 kimi-k3입니다. OpenRouter를 통해 호출하는 경우 슬러그는 moonshotai/kimi-k3입니다. 모델의 OpenRouter 목록은 openrouter.ai/moonshotai/kimi-k3에서 읽을 수 있습니다.

어떤 기본 URL을 사용해야 하나요? 계정의 진실의 원천이므로 platform.kimi.ai 콘솔에서 확인하세요. Kimi는 역사적으로 https://api.moonshot.ai/v1을 사용했습니다. 코드에서는 하드코딩하는 대신 콘솔에서 설정한 base_url 변수로 유지하세요.

Kimi K3는 OpenAI SDK와 호환되나요? 네. API는 OpenAI 채팅 완료 형식을 따르므로, base_url 및 model을 변경한 후 공식 OpenAI Python 및 JavaScript SDK가 작동합니다. 공급자별 필드는 extra_body를 통해 전달됩니다.

Kimi K3 API 비용은 얼마인가요? 캐시 히트 입력 토큰 백만 개당 $0.30, 캐시 미스 입력 토큰 백만 개당 $3.00, 출력 토큰 백만 개당 $15.00입니다. 캐시 재사용을 위한 프롬프트 구조화가 청구서에 가장 큰 영향을 미칩니다. Kimi K3 가격 가이드에서 숫자를 확인하세요.

컨텍스트 캐싱은 실제로 무엇을 하나요? 요청의 선행 토큰이 이전 요청과 일치할 때, 엔드포인트는 계산된 상태를 다시 계산하는 대신 재사용하여 해당 부분의 입력 비용을 백만 개당 $3.00에서 $0.30으로 낮춥니다. 시스템 프롬프트와 공유 컨텍스트를 프롬프트 앞에 배치하고 호출 간에 동일하게 유지하여 히트율을 최대화하세요.

모델이 얼마나 많이 생각하는지 제어할 수 있나요? 네, reasoning_effort를 통해 가능합니다. 현재 사용 가능한 수준은 max이며, 이는 기본값이기도 합니다. Moonshot은 다른 수준이 계획되어 있다고 말했습니다. 높은 노력은 더 많은 출력 토큰 비용을 발생시키고 지연 시간을 추가합니다.

Kimi K3 또는 Kimi K2.7 코드를 사용해야 하나요? 깊은 추론, 전체 1M 컨텍스트 또는 에이전트 도구 오케스트레이션이 필요할 때 kimi-k3를 사용하세요. 대량의 일상적인 코딩 작업에는 더 저렴한 K2.7 라인이 더 나은 선택인 경우가 많습니다. Kimi K3 대 Kimi K2.7 코드 비교 및 Kimi K2.7 코드 API 가이드가 결정에 도움이 될 것입니다.

오류가 있는 스트리밍 또는 도구 호출 응답을 어떻게 디버그하나요? Apidog에서 "stream": true로 원시 요청을 보내고 서버 전송 이벤트를 프레임별로 읽거나, tool_calls 배열을 검사하여 모델이 잘못된 형식의 JSON을 반환했는지 확인하세요. 키를 환경 변수로 저장하면 테스트하는 동안 요청 본문에 포함되지 않습니다.

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드