DEV Community

Cover image for Cách sử dụng API Kimi K3
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Cách sử dụng API Kimi K3

Moonshot AI đã ra mắt Kimi K3 vào ngày 16 tháng 7 năm 2026 và gọi đây là mô hình có khả năng nhất của họ cho đến nay: mô hình 3T-class mã nguồn mở đầu tiên trên thế giới, với thiết kế Mixture-of-Experts (MoE) 2.8T tham số và cửa sổ ngữ cảnh 1.048.576 token. Điều đáng quan tâm với nhà phát triển không chỉ là kích thước, mà là API: Kimi K3 sử dụng định dạng tương thích OpenAI SDK. Nếu bạn đã gọi GPT hoặc endpoint tương thích OpenAI, bạn chỉ cần trỏ client sang kimi-k3 để nhận phản hồi streaming trong vài phút. Hướng dẫn này trình bày cách lấy khóa API, gọi API bằng Python, JavaScript và cURL, xử lý streaming, tool calls, JSON mode, reasoning_effort, context caching và gỡ lỗi yêu cầu thô bằng Apidog.

Dùng thử Apidog ngay hôm nay

Tóm tắt

  • ID mô hình API là kimi-k3. Trên OpenRouter, slug là moonshotai/kimi-k3.
  • Endpoint tương thích OpenAI SDK: cấu hình base_url, api_key và model="kimi-k3". Xác nhận URL cơ sở trong console tại platform.kimi.ai; Kimi trước đây đã sử dụng https://api.moonshot.ai/v1.
  • Cửa sổ ngữ cảnh là 1M token. Giá: $0.30 cho mỗi triệu token đầu vào cache-hit, $3.00 cho mỗi triệu token đầu vào cache-miss và $15.00 cho mỗi triệu token đầu ra.
  • Streaming, tool calls, JSON mode, structured output và reasoning_effort (max hiện có sẵn) hoạt động theo định dạng chat completions tiêu chuẩn.
  • Với tác vụ lập trình thông thường hoặc ngân sách hạn chế, dòng K2.7 có thể phù hợp hơn.
  • Dùng Apidog để kiểm tra streaming, gỡ lỗi tool calls, lưu khóa API dưới dạng biến môi trường và so sánh A/B kimi-k3 với kimi-k2-7-code.

Bạn nên gọi mô hình Kimi nào?

Hãy chọn mô hình theo loại workload trước khi viết code. Kimi K3 là mô hình tiên tiến nhất trong dòng sản phẩm: một MoE lớn hướng đến lập trình phức tạp, tác vụ agentic dài hạn và công việc kiến thức trên ngữ cảnh dài. Tuy nhiên, chi phí token đầu ra của nó cao nhất trong dòng sản phẩm. Bài đăng ra mắt của Moonshot cũng nêu rằng K3 xếp sau Claude Fable 5 và GPT-5.6 Sol trong các so sánh nội bộ của họ.

So sánh Kimi K3

Nếu workload của bạn là trợ lý mã hóa lưu lượng cao, trình tạo kiểm thử CI hoặc tác vụ cần gọi API ở quy mô lớn, dòng K2.7 Code cũ hơn thường tối ưu chi phí hơn. Bắt đầu với hướng dẫn API Kimi K2.7 Code và bài viết Kimi K2.7 Code là gì.

Dùng kimi-k3 khi bạn cần:

  • Suy luận sâu hơn.
  • Ngữ cảnh đầy đủ 1M token.
  • Điều phối công cụ cho tác nhân.

Chuyển sang K2.7 khi tác vụ thông thường và có khối lượng lớn. Để so sánh trực tiếp, xem Kimi K3 vs Kimi K2.7 Code. Nếu cần hiểu thêm về kiến trúc, xem Kimi K3 là gì.

Lấy khóa API trên nền tảng Kimi

Truy cập platform.kimi.ai và đăng nhập. Console là nơi tạo khóa API, theo dõi mức sử dụng và xác nhận URL cơ sở cho tài khoản.

Kimi platform console

  1. Mở phần API keys trong console và tạo khóa mới.
  2. Sao chép khóa ngay khi được hiển thị và lưu ở nơi an toàn. Bạn sẽ không thể xem lại toàn bộ giá trị này.
  3. Thêm tín dụng hoặc xác nhận gói thanh toán để lệnh gọi kimi-k3 không bị từ chối do số dư không đủ.
  4. Ghi lại URL cơ sở trong console. Kimi trước đây đã sử dụng https://api.moonshot.ai/v1, nhưng console là nguồn thông tin chính xác cho tài khoản của bạn.

Xuất khóa thành biến môi trường thay vì ghi trực tiếp vào mã nguồn:

export KIMI_API_KEY="sk-your-key-here"
export KIMI_BASE_URL="https://api.moonshot.ai/v1"
Enter fullscreen mode Exit fullscreen mode

Cách này giúp tránh lộ khóa trong Git history, log hoặc ảnh chụp màn hình. Khi kiểm tra bằng Apidog, hãy lưu cùng khóa đó trong environment thay vì dán vào request body.

Để xem chi tiết chi phí cache-hit và cache-miss, đọc hướng dẫn định giá Kimi K3.

Bắt đầu nhanh: lệnh gọi kimi-k3 đầu tiên

Kimi API tuân theo hợp đồng OpenAI chat completions. Với OpenAI SDK, bạn chỉ cần thay đổi base_url, api_key và model.

Python 

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    # Xác nhận URL cơ sở chính xác trong console tại platform.kimi.ai.
    base_url=os.environ["KIMI_BASE_URL"],
)

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)
Enter fullscreen mode Exit fullscreen mode

JavaScript / TypeScript 

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KIMI_API_KEY,
  // Xác nhận URL cơ sở trong console tại platform.kimi.ai.
  baseURL: process.env.KIMI_BASE_URL,
});

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);
Enter fullscreen mode Exit fullscreen mode

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Nếu nhận lỗi:

  • 401: kiểm tra KIMI_API_KEY, biến môi trường hoặc quyền truy cập của khóa.
  • 404: kiểm tra KIMI_BASE_URL và đường dẫn /chat/completions; thường đây là lỗi URL cơ sở, không phải lỗi model.

Tài liệu OpenAI Python SDK có thêm tùy chọn client. Các tùy chọn tương thích với định dạng OpenAI đều có thể áp dụng ở đây.

Phản hồi streaming

Với chat UI hoặc agent chạy lâu, hãy bật streaming để nhận token ngay khi chúng được tạo thay vì chờ toàn bộ phản hồi.

Python 

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)
Enter fullscreen mode Exit fullscreen mode

Luồng này sử dụng server-sent events (SSE). Mỗi khung thường có tiền tố data: chứa JSON, và luồng kết thúc bằng:

data: [DONE]
Enter fullscreen mode Exit fullscreen mode

SDK giúp bạn không phải tự parse SSE, nhưng khi stream lỗi giữa chừng, xem khung SSE thô sẽ hữu ích để xác định lỗi ở client, proxy hay endpoint.

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 ?? "");
}
Enter fullscreen mode Exit fullscreen mode

Gọi công cụ (function calling)

Kimi K3 hỗ trợ tool calls, ràng buộc lựa chọn công cụ và tải công cụ động. Bạn khai báo công cụ bằng JSON Schema, mô hình trả về tên hàm cùng đối số JSON, còn ứng dụng của bạn thực thi hành động thực tế.

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"}
Enter fullscreen mode Exit fullscreen mode

Mô hình không chạy hàm get_weather. Bạn cần thực hiện lệnh gọi API hoặc logic nghiệp vụ trong ứng dụng, rồi gửi kết quả trở lại model.

import json

# Thêm message của assistant yêu cầu tool call.
messages.append(first.choices[0].message)

# Thêm kết quả do ứng dụng của bạn thực thi.
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)
Enter fullscreen mode Exit fullscreen mode

Các chế độ tool_choice hữu ích:

# Ép model phải gọi một tool.
tool_choice = "required"

# Ép model gọi đúng một hàm.
tool_choice = {
    "type": "function",
    "function": {"name": "get_weather"},
}
Enter fullscreen mode Exit fullscreen mode

Với agent đa lượt, hãy giữ toàn bộ lịch sử tin nhắn, bao gồm các lượt tool call và phản hồi tool. Nếu cắt bỏ các lượt nội bộ của assistant, chất lượng sinh có thể không ổn định.

Chế độ JSON và đầu ra có cấu trúc

Khi ứng dụng cần dữ liệu có thể parse bằng máy, yêu cầu JSON trực tiếp thay vì parse văn bản tự do.

JSON object 

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"}
Enter fullscreen mode Exit fullscreen mode

JSON Schema

Nếu SDK và tài khoản của bạn hỗ trợ json_schema, khai báo schema để ràng buộc cấu trúc đầu ra:

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"],
            },
        },
    },
)
Enter fullscreen mode Exit fullscreen mode

Xác nhận hỗ trợ json_schema trong console trước khi dùng ở production. Nếu không chắc chắn, dùng json_object và validate dữ liệu ở phía ứng dụng là phương án dự phòng an toàn.

Kimi cũng cung cấp partial mode và tìm kiếm internet, hữu ích khi cần điền trước phản hồi hoặc dựa vào dữ liệu mới.

Nỗ lực suy luận có thể cấu hình

Kimi K3 có tham số reasoning_effort để kiểm soát mức độ suy nghĩ trước khi trả lời. Hiện tại, cấp độ sẵn có là max, cũng là giá trị mặc định. Suy luận sâu hơn có thể tăng token đầu ra và độ trễ, nên chỉ dùng cho tác vụ thực sự cần thiết.

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",
)
Enter fullscreen mode Exit fullscreen mode

Nếu phiên bản OpenAI SDK chưa hỗ trợ trường này, truyền qua extra_body:

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

extra_body phù hợp cho các trường dành riêng cho nhà cung cấp mà SDK gốc chưa mô hình hóa.

Kiểm tra và gỡ lỗi kimi-k3 trong Apidog

SDK che giấu chi tiết HTTP và SSE, điều này tiện lợi cho đến khi tool call trả về dữ liệu sai định dạng hoặc streaming bị ngắt. Khi đó, hãy kiểm tra request thô bằng Apidog: gửi đúng request kimi-k3, xem SSE theo từng khung và giữ API key ngoài request body.

Nếu bạn muốn kiểm tra API không phụ thuộc vào terminal, xem hướng dẫn kiểm thử API không dùng Postman.

Gỡ lỗi Kimi K3 bằng Apidog

Thiết lập request trong Apidog theo các bước sau:

  1. Tạo một HTTP request mới.
  2. Đặt phương thức là POST.
  3. Đặt URL thành: 
   {{KIMI_BASE_URL}}/chat/completions
Enter fullscreen mode Exit fullscreen mode
  1. Trong environment, thêm:
    • KIMI_API_KEY
    • KIMI_BASE_URL
  2. Thêm headers: 
   Authorization: Bearer {{KIMI_API_KEY}}
   Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode
  1. Dùng request body cơ bản: 
   {
     "model": "kimi-k3",
     "messages": [
       {
         "role": "user",
         "content": "Explain what a token bucket rate limiter does in one paragraph."
       }
     ]
   }
Enter fullscreen mode Exit fullscreen mode
  1. Gửi request và kiểm tra:
    • Nội dung phản hồi.
    • Usage token.
    • Thông tin cache-hit và cache-miss nếu được trả về.
    • HTTP status và response headers.

Để kiểm tra streaming, thêm:

{
  "stream": true
}
Enter fullscreen mode Exit fullscreen mode

hoặc gộp vào request body hiện có:

{
  "model": "kimi-k3",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Write a 6-line poem about flaky tests."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Kiểm tra các khung data: để xác định stream có bị dừng trước [DONE] hay không.

Để gỡ lỗi tool calls:

  1. Gửi request có trường tools.
  2. Kiểm tra mảng tool_calls trong phản hồi assistant.
  3. Xác minh function.name có đúng với tool đã khai báo.
  4. Parse và validate function.arguments trước khi chạy logic nghiệp vụ.
  5. Nếu arguments không hợp lệ, cải thiện description, parameters và danh sách required trong JSON Schema.

Bạn cũng nên chạy A/B test giữa K3 và K2.7:

  1. Sao chép request trong Apidog.
  2. Chỉ đổi trường model từ kimi-k3 sang kimi-k2-7-code.
  3. Gửi cùng prompt.
  4. So sánh độ trễ, chất lượng đầu ra và chi phí.

Apidog có thể nhập trực tiếp request tương thích OpenAI từ lệnh cURL, giúp biến request thủ công thành test case có thể chạy lại. Nếu agent của bạn giao tiếp qua MCP, xem hướng dẫn gỡ lỗi trực quan với client Apidog MCP. Bạn có thể tải xuống Apidog để thực hiện quy trình này với API key của mình.

Các trường hợp sử dụng thực tế

kimi-k3 phù hợp với các workload sau:

  • Agent mã hóa quy mô repository: Ngữ cảnh 1M token và tool orchestration giúp model đọc cơ sở mã lớn, chạy kiểm thử, đọc log và lặp lại. Giữ bản tóm tắt repository ở phần đầu prompt để tăng cache hit.
  • Công việc kiến thức với tài liệu dài: Đưa toàn bộ đặc tả, hợp đồng hoặc tài liệu nghiên cứu vào ngữ cảnh và yêu cầu trích xuất bằng json_schema. Đặt tài liệu dùng chung ở đầu prompt để tái sử dụng cache.
  • Lập kế hoạch di chuyển và tái cấu trúc: Dùng reasoning_effort="max" trong bước lập kế hoạch, sau đó chuyển sang model rẻ hơn cho các thay đổi cơ học.
  • Trả lời nghiên cứu có căn cứ: Kết hợp tìm kiếm internet và tool calls để lấy dữ liệu mới, phù hợp với trợ lý không thể chỉ dựa vào kiến thức huấn luyện cũ.

Quy trình nên là:

  1. Xây dựng request bằng SDK.
  2. Xác minh request và phản hồi thô trong Apidog.
  3. Đo chi phí, độ trễ và chất lượng với prompt thực tế.
  4. Chỉ tích hợp vào production sau khi đã có test case lặp lại được.

Tổng kết

Để gọi Kimi K3, bạn chỉ cần cấu hình ba giá trị trong client tương thích OpenAI:

  • URL cơ sở từ Kimi console.
  • API key.
  • model="kimi-k3".

Sau đó, bạn có thể dùng streaming, tool calls, JSON mode, structured output và reasoning_effort theo hợp đồng chat completions quen thuộc.

Hai điểm quan trọng cần theo dõi:

  1. Context caching: Giữ system prompt và ngữ cảnh dùng chung ổn định ở đầu request để biến chi phí đầu vào cache-miss $3.00 thành cache-hit $0.30 trên mỗi triệu token.
  2. Chi phí so với năng lực: K3 phù hợp cho suy luận sâu và ngữ cảnh dài; với tác vụ mã hóa thông thường, lưu lượng cao, K2.7 thường kinh tế hơn.

Xây dựng request trong mã, kiểm chứng bằng Apidog và đo lường trên workload thực tế trước khi triển khai.

Câu hỏi thường gặp

ID mô hình API cho Kimi K3 là gì?

Đó là kimi-k3 trên nền tảng Kimi. Nếu gọi qua OpenRouter, slug là moonshotai/kimi-k3. Xem danh sách model tại openrouter.ai/moonshotai/kimi-k3.

Tôi sử dụng URL cơ sở nào?

Xác nhận trong console tại platform.kimi.ai. Kimi trước đây đã sử dụng https://api.moonshot.ai/v1, nhưng bạn nên lưu URL này dưới dạng biến KIMI_BASE_URL thay vì hard-code.

Kimi K3 có tương thích OpenAI SDK không?

Có. API tuân theo định dạng OpenAI chat completions, nên OpenAI SDK cho Python và JavaScript hoạt động sau khi đổi base_url và model. Các trường riêng của nhà cung cấp có thể truyền qua extra_body.

API Kimi K3 có giá bao nhiêu?

$0.30 cho mỗi triệu token đầu vào cache-hit, $3.00 cho mỗi triệu token đầu vào cache-miss và $15.00 cho mỗi triệu token đầu ra. Xem hướng dẫn định giá Kimi K3 để biết chi tiết.

Context caching thực sự làm gì?

Khi token ở phần đầu request trùng với request trước đó, endpoint có thể tái sử dụng trạng thái đã tính toán thay vì tính lại. Điều này giảm chi phí phần đầu vào đó từ $3.00 xuống $0.30 cho mỗi triệu token. Hãy giữ system prompt và ngữ cảnh chia sẻ ở đầu prompt, ổn định giữa các lần gọi.

Tôi có thể kiểm soát mức độ mô hình suy nghĩ không?

Có, bằng reasoning_effort. Cấp độ hiện có là max, cũng là mặc định. Nỗ lực cao hơn có thể dùng nhiều token đầu ra hơn và tăng độ trễ.

Tôi nên dùng Kimi K3 hay Kimi K2.7 Code?

Dùng kimi-k3 khi cần suy luận sâu, ngữ cảnh 1M token hoặc agentic tool orchestration. Với tác vụ mã hóa thông thường, lưu lượng cao, K2.7 thường rẻ hơn. Xem Kimi K3 vs Kimi K2.7 Code và hướng dẫn API Kimi K2.7 Code.

Làm cách nào để gỡ lỗi streaming hoặc tool call lỗi?

Gửi request thô trong Apidog với "stream": true để đọc từng khung SSE, hoặc kiểm tra mảng tool_calls để xem model có trả về JSON sai định dạng không. Lưu API key trong environment để tránh đưa bí mật vào request body.

Top comments (0)