Blog

Cách sử dụng API Kimi K3

Gọi API Kimi K3 bằng OpenAI SDK: Hướng dẫn nhanh cho Python, JavaScript và cURL, cộng với tính năng truyền phát, gọi công cụ, chế độ JSON, nỗ lực suy luận và bộ nhớ đệm.

Ashley Innocent

Ashley Innocent

17 tháng 7 2026

Cách sử dụng API Kimi K3

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

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 thú vị đối với các nhà phát triển không phải là kích thước, mà là API. Kimi K3 sử dụng ngôn ngữ của OpenAI SDK, vì vậy nếu bạn đã gọi GPT hoặc bất kỳ endpoint tương thích OpenAI nào, bạn có thể trỏ cùng một client đến kimi-k3 và bắt đầu nhận phản hồi streaming trong vài phút. Hướng dẫn này sẽ chỉ cho bạn cách lấy khóa API, cách bắt đầu nhanh với Python, JavaScript và cURL, streaming, gọi công cụ (tool calls), chế độ JSON, tham số nỗ lực suy luận có thể cấu hình, và tính năng lưu trữ ngữ cảnh giúp đầu vào cache-hit rẻ hơn khoảng mười lần so với cache-miss. Sau đó, bạn sẽ kiểm tra và gỡ lỗi các lệnh gọi đó trong Apidog để bạn có thể xem yêu cầu thô và các sự kiện do máy chủ gửi (server-sent events) thay vì phải đoán.

Tóm tắt

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

Trước khi viết bất kỳ đoạn code nào, hãy chọn mục tiêu phù hợp. Kimi K3 là mô hình tiên tiến nhất trong dòng sản phẩm: một MoE lớn được thiết kế cho lập trình phức tạp, công việc tác nhân (agentic work) dài hạn và các tác vụ kiến thức trên ngữ cảnh dài. Nó có chi phí đầu ra trên mỗi token cao nhất trong dòng sản phẩm, và bài đăng ra mắt của Moonshot cũng thẳng thắn thừa nhận 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ọ. Nó mạnh mẽ, nhưng không phải là người chiến thắng tuyệt đối, và giá của nó cũng tương xứng.

Nếu khối lượng công việc của bạn là trợ lý mã hóa khối lượng lớn, trình viết kiểm thử CI, hoặc bất kỳ thứ gì mà bạn phải trả tiền cho mỗi lần gọi ở quy mô lớn, dòng K2.7 Code cũ hơn thường phù hợp hơn về chi phí. Bắt đầu với hướng dẫn API Kimi K2.7 Code và tổng quan Kimi K2.7 Code là gì để xem liệu cấp độ đó có phù hợp với trường hợp của bạn không. Để so sánh song song về khả năng và giá cả, bài so sánh Kimi K3 vs Kimi K2.7 Code sẽ trình bày điểm mạnh của từng mô hình. Hãy dùng kimi-k3 khi bạn cần độ sâu suy luận cao hơn, ngữ cảnh 1M đầy đủ, hoặc sự điều phối công cụ tác nhân (agentic tool orchestration); chuyển xuống K2.7 khi tác vụ là thông thường và khối lượng cao. Nếu bạn muốn có cái nhìn đầy đủ về khả năng trước, phần giải thích Kimi K3 là gì sẽ trình bày kiến trúc và vị trí của mô hình.

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

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

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

Xuất khóa dưới dạng biến môi trường để nó không bao giờ xuất hiện trong mã nguồn của bạn:

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

Thói quen đơn giản đó giúp giữ bí mật không lọt vào lịch sử Git và không xuất hiện trong ảnh chụp màn hình. Sau này, khi bạn kiểm tra trong Apidog, bạn cũng sẽ lưu trữ cùng giá trị đó dưới dạng biến môi trường ở đó, vì vậy khóa chỉ tồn tại ở hai nơi bạn kiểm soát.

Để biết phân tích chi tiết về phép toán cache-hit so với cache-miss và cách nó ánh xạ tới hóa đơn hàng tháng thực tế, hãy xem hướng dẫn định giá Kimi K3.

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

API của Kimi tuân theo hợp đồng chat-completions của OpenAI, vì vậy các OpenAI SDK chính thức hoạt động chỉ với hai thay đổi: base_url và model. Cài đặt SDK bạn ưu tiên, sau đó chạy một trong các đoạn mã dưới đây.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KIMI_API_KEY"],
    # Kimi is OpenAI-SDK compatible. Confirm the exact base URL in the
    # console at platform.kimi.ai; Kimi has historically used the value below.
    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,
  // Confirm the base URL in the platform.kimi.ai console.
  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."}
    ]
  }'

Đặt KIMI_BASE_URL thành giá trị hiển thị trong console (ví dụ https://api.moonshot.ai/v1). Nếu bất kỳ lệnh nào trong số này trả về 401, khóa API sai hoặc chưa được đặt. Lỗi 404 trên đường dẫn thường có nghĩa là URL cơ sở không chính xác, chứ không phải là mô hình bị thiếu. Tài liệu OpenAI Python SDK bao gồm các tùy chọn client chi tiết hơn, và mọi tùy chọn ở đó đều áp dụng ở đây vì định dạng giao tiếp là giống nhau.

Phản hồi streaming

Đối với giao diện người dùng trò chuyện (chat UIs) và các lượt tương tác dài của tác nhân, bạn muốn nhận token ngay khi chúng đến thay vì chờ đợi toàn bộ quá trình hoàn thành. Đặt stream=True và lặp qua các phần thay đổi (deltas).

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)

Về cơ bản, đây là một luồng sự kiện do máy chủ gửi (server-sent events - SSE): mỗi dòng là một khung data: mang một phần JSON nhỏ, và luồng kết thúc bằng data: [DONE]. SDK ẩn đi cấu trúc này khỏi bạn, điều này tiện lợi cho đến khi có lỗi xảy ra giữa luồng và bạn cần xem các khung dữ liệu thô. Đó là một trong những điểm mà phần Apidog bên dưới thể hiện giá trị của nó.

Cùng cờ này hoạt động trong 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 ?? "");
}

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

Kimi K3 hỗ trợ gọi công cụ (tool calls), ràng buộc lựa chọn công cụ (tool-choice constraints) và tải công cụ động, vì vậy bạn có thể tích hợp nó vào các tác nhân (agents) đọc tệp, gọi API hoặc chạy lệnh terminal. Bạn mô tả các hàm của mình bằng JSON Schema, mô hình sẽ quyết định khi nào gọi một hàm, và bạn trả về kết quả trong một tin nhắn 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"}

Mô hình không chạy hàm của bạn; nó cung cấp cho bạn tên và các đối số JSON. Bạn thực hiện công việc thực tế, sau đó đưa đầu ra trở lại để mô hình có thể viết câu trả lời cuối cùng:

import json

# Append the assistant turn that asked for the tool, then the tool result.
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)

Đặt tool_choice="required" để ép buộc gọi công cụ, hoặc truyền một đối tượng {"type": "function", "function": {"name": "get_weather"}} cụ thể để ghim một hàm. Những ràng buộc đó giúp tác nhân đi đúng hướng khi bạn đã biết công cụ nào nên được kích hoạt.

Một điều cần lưu ý sớm, đặc biệt đối với K3: mô hình được huấn luyện ở chế độ bảo toàn lịch sử suy nghĩ. Nếu hệ thống tác nhân của bạn bỏ qua lý do suy luận trước đó của mô hình giữa các lượt, chất lượng tạo ra có thể trở nên không ổn định. Khi bạn xây dựng một vòng lặp tác nhân đa lượt, hãy truyền lại toàn bộ lịch sử tin nhắn thay vì cắt bớt các lượt nội bộ của trợ lý.

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

Khi bạn cần đầu ra có thể đọc được bằng máy, hãy yêu cầu JSON trực tiếp thay vì phân tích văn xuôi. Đặt response_format thành json_object và hướng dẫn mô hình trả về 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"}

Để đảm bảo nghiêm ngặt hơn, Kimi hỗ trợ đầu ra có cấu trúc theo một schema. Nếu phiên bản SDK của bạn chấp nhận, hãy truyền định dạng phản hồi json_schema để mô hình tuân thủ cấu trúc bạn mong muốn:

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"],
            },
        },
    },
)

Xác nhận hỗ trợ json_schema cho tài khoản của bạn trong console trước khi bạn triển khai; khi còn nghi ngờ, json_object cộng với một bước xác thực phía bạn là lựa chọn dự phòng an toàn. Kimi cũng cung cấp chế độ một phần (partial mode) và tìm kiếm internet, giúp ích khi bạn muốn điền trước phản hồi của trợ lý hoặc dựa trên dữ liệu mới.

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

Kimi K3 cung cấp tham số reasoning_effort kiểm soát mức độ mô hình suy nghĩ trước khi trả lời. Hiện tại, cấp độ có sẵn là max, cũng là giá trị mặc định; Moonshot đã nói rằng các cấp độ thấp hơn và cao hơn đang được lên kế hoạch. Suy nghĩ sâu hơn tốn nhiều token đầu ra hơn và tăng độ trễ, vì vậy đây là một đòn bẩy bạn điều chỉnh cho từng tác vụ.

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",
)

Nếu phiên bản OpenAI SDK của bạn từ chối trường này vì không xác định, hãy truyền nó qua cơ chế thoát thay thế:

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

Mẫu extra_body là cách bạn gửi bất kỳ trường cụ thể nào của nhà cung cấp mà SDK cơ sở chưa mô hình hóa, điều này phổ biến khi một endpoint tương thích phát triển nhanh hơn thư viện client.

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

Mã SDK ẩn định dạng giao tiếp, điều này tốt cho đến khi một lệnh gọi công cụ trả về định dạng sai hoặc luồng bị ngắt và bạn không thể biết lỗi là do bạn hay do endpoint. Đây là lúc một client API giao tiếp bằng HTTP thô phát huy tác dụng. Apidog cho phép bạn gửi yêu cầu kimi-k3 chính xác, xem luồng SSE từng khung hình và giữ khóa API của bạn không nằm trong phần thân yêu cầu. Nếu bạn muốn kiểm tra các lệnh gọi API mà không cần phải làm việc trong terminal, đây là một quy trình sạch hơn so với việc dùng curl và dò lỗi; hướng dẫn kiểm thử API không dùng Postman bao gồm quy trình làm việc chung.

Dưới đây là quy trình tập trung cho kimi-k3:

  1. Tạo một yêu cầu HTTP mới trong Apidog. Đặt phương thức là POST và URL là URL cơ sở của bạn cộng với /chat/completions.
  2. Lưu khóa API của bạn dưới dạng biến môi trường. Trong cài đặt môi trường của Apidog, thêm KIMI_API_KEY, sau đó đặt tiêu đề Authorization thành Bearer {{KIMI_API_KEY}}. Giờ đây, bí mật được tham chiếu chứ không phải dán trực tiếp, và bạn có thể chuyển đổi giữa các khóa kiểm thử và sản xuất bằng cách chuyển đổi môi trường.
  3. Dán một phần thân JSON với "model": "kimi-k3" và mảng messages của bạn. Gửi nó và đọc toàn bộ phản hồi, bao gồm mức sử dụng token, để bạn có thể thấy số lượng cache-hit so với cache-miss trên các lệnh gọi thực tế.
  4. Bật "stream": true và xem các sự kiện server-sent đến dưới dạng các khung riêng biệt. Việc nhìn thấy các phần data: thô giúp làm rõ các lỗi streaming một cách mà trình lặp gọn gàng của SDK không thể.
  5. Gỡ lỗi tool calls bằng cách kiểm tra mảng tool_calls trong phản hồi. Khi các đối số trả về bị lỗi định dạng, bạn có thể xem liệu mô hình tạo ra JSON không hợp lệ hay schema của bạn không rõ ràng, và sửa mô tả ngay tại đó.
  6. So sánh A/B với kimi-k2-7-code. Sao chép yêu cầu, chỉ thay đổi trường model, và so sánh độ trễ, chất lượng đầu ra, và chi phí trên cùng một prompt. Đó là cách trung thực và nhanh nhất để quyết định liệu khả năng suy luận bổ sung của K3 có đáng với mức giá tăng thêm cho tác vụ của bạn hay không.

Vì Apidog nhập trực tiếp các yêu cầu tương thích với OpenAI, bạn có thể dán một lệnh cURL và nhận được một yêu cầu đã lưu, có thể chạy lại với các tiêu đề và phần thân đã được điền sẵn. Từ đó, nó trở thành một trường hợp kiểm thử chung mà nhóm của bạn có thể chạy lại bất cứ khi nào Kimi ra mắt bản cập nhật. Nếu tác nhân của bạn giao tiếp với mô hình thông qua MCP, hướng dẫn gỡ lỗi trực quan với client Apidog MCP cũng cho thấy cách theo dõi các lệnh gọi đó. Tải xuống Apidog nếu bạn muốn làm theo quy trình này bằng khóa API của riêng mình.

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

Một số mô hình phù hợp hoàn hảo với mục đích mà kimi-k3 được xây dựng:

Trong mỗi trường hợp này, quy trình làm việc đều giống nhau: xây dựng yêu cầu bằng SDK, xác minh hành vi thô trong Apidog, sau đó tích hợp vào ứng dụng của bạn sau khi bạn tin tưởng vào cấu trúc.

Tổng kết

Việc gọi Kimi K3 chỉ cần ba cài đặt trên một client tương thích OpenAI: URL cơ sở từ console của bạn, khóa API của bạn và model="kimi-k3". Từ đó, streaming, gọi công cụ (tool calls), chế độ JSON, đầu ra có cấu trúc (structured output) và reasoning_effort đều tuân theo hợp đồng chat-completions mà bạn đã biết. Hai điều đáng ghi nhớ là kinh tế học bộ nhớ đệm (caching economics), nơi việc giữ một tiền tố ổn định biến đầu vào $3.00 thành đầu vào $0.30, và sự đánh đổi trung thực rằng K3 mang lại độ sâu suy luận với một mức giá thực, vì vậy hãy chuyển các tác vụ thông thường khối lượng lớn sang dòng K2.7. Xây dựng yêu cầu trong mã, kiểm chứng nó trong Apidog, và bạn sẽ triển khai với kimi-k3 mà không gặp bất ngờ nào.

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 của Kimi. Nếu bạn gọi nó qua OpenRouter, slug là moonshotai/kimi-k3. Bạn có thể đọc danh sách mô hình trên OpenRouter tại openrouter.ai/moonshotai/kimi-k3.

Tôi sử dụng URL cơ sở nào? Xác nhận nó trong console tại platform.kimi.ai, vì đó là nguồn thông tin đáng tin cậy cho tài khoản của bạn. Kimi trước đây đã sử dụng https://api.moonshot.ai/v1. Trong mã, hãy giữ nó dưới dạng biến base_url mà bạn đặt từ console thay vì mã hóa cứng.

Kimi K3 có tương thích với OpenAI SDK không? Có. API tuân theo định dạng chat-completions của OpenAI, vì vậy các OpenAI SDK chính thức cho Python và JavaScript hoạt động sau khi bạn thay đổi base_url và model. Các trường dành riêng cho nhà cung cấp sẽ được 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. Cấu trúc prompt để tái sử dụng bộ nhớ đệm (cache reuse) là đòn bẩy lớn nhất để kiểm soát hóa đơn của bạn. Hướng dẫn định giá Kimi K3 sẽ phân tích các con số này.

Bộ nhớ đệm ngữ cảnh (context caching) thực sự làm gì? Khi các token dẫn đầu trong yêu cầu của bạn khớp với một yêu cầu trước đó, endpoint sẽ tái sử dụng trạng thái đã tính toán thay vì tính toán lại, điều này làm giảm chi phí đầu vào từ $3.00 xuống còn $0.30 cho mỗi triệu trên phần đó. Giữ prompt hệ thống và ngữ cảnh chia sẻ ở đầu và giống hệt nhau trong các lệnh gọi để tối đa hóa số lần khớp.

Tôi có thể kiểm soát mức độ mô hình suy nghĩ không? Có, thông qua reasoning_effort. Cấp độ hiện có sẵn là max, cũng là mặc định; Moonshot đã nói rằng các cấp độ khác đang được lên kế hoạch. Nỗ lực cao hơn tốn nhiều token đầu ra hơn và tăng độ trễ.

Tôi nên sử dụng Kimi K3 hay Kimi K2.7 Code? Sử dụng kimi-k3 khi bạn cần suy luận sâu, ngữ cảnh 1M đầy đủ hoặc điều phối công cụ tác nhân (agentic tool orchestration). Đối với công việc mã hóa thông thường, khối lượng lớn, dòng K2.7 rẻ hơn thường là lựa chọn tốt hơn. So sánh Kimi K3 vs Kimi K2.7 Code và hướng dẫn API Kimi K2.7 Code sẽ giúp bạn quyết định.

Làm cách nào để gỡ lỗi một phản hồi streaming hoặc tool-call bị lỗi? Gửi yêu cầu thô trong Apidog với "stream": true và đọc các sự kiện server-sent từng khung hình, hoặc kiểm tra mảng tool_calls để xem liệu mô hình có trả về JSON bị lỗi định dạng không. Lưu khóa API của bạn dưới dạng biến môi trường giúp nó không xuất hiện trong phần thân yêu cầu trong khi bạn kiểm tra.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống