Hướng dẫn tích hợp Kimi API: Base URL, mô hình và lần gọi đầu (2026)

Kimi API tương thích giao diện OpenAI; khi di chuyển thường chỉ đổi ba chỗ: Base URL, API Key và tên mô hình. Nhưng chi tiết giao diện năm 2026 có vài điểm dễ sai: mô hình cũ đã ngừng cung cấp, max_tokens đã bị loại bỏ, K3 mặc định dùng cường độ suy luận cao nhất, và mức dùng của yêu cầu truyền phát chỉ trả về ở khối cuối.

Bài viết đi từ đầu: xác nhận site và giao thức trước, chọn mô hình, hoàn thành lần gọi curl và Python đầu tiên, cuối cùng đưa ra danh sách di chuyển và bảng đối chiếu lỗi. Mô hình và giá căn cứ theo bảng giá mô hình trên site.

Lưu ý: Moonshot và Kimi là nhãn hiệu của chủ sở hữu tương ứng; bài viết chỉ nhằm giải thích kỹ thuật tích hợp. Danh sách mô hình, độ dài ngữ cảnh và quy tắc tham số có thể điều chỉnh; vui lòng căn cứ phiên bản hiện tại của tài liệu chính thức.

1. Xác nhận ba việc trước khi tích hợp

Site: site Trung Quốc dùng platform.kimi.com, site quốc tế dùng platform.kimi.ai. Tài khoản, số dư và khóa của hai site hoàn toàn độc lập.
Giao thức: phần lớn dự án dùng Chat Completions tương thích OpenAI; dự án đã có SDK Anthropic có thể dùng điểm vào tương thích Messages.
Mô hình: trước hết xác nhận tài khoản thấy được những mô hình nào rồi mới ghi vào mã. Đừng sao chép hướng dẫn từ vài tháng trước.

Tên miền yêu cầu của site Trung Quốc là https://api.moonshot.cn, site quốc tế là https://api.moonshot.ai. Tên miền và khóa phải đi thành cặp; đây là một trong những nguyên nhân phổ biến nhất gây 401.

2. Base URL và đường dẫn giao diện

Giao thức	Base URL	Đường dẫn giao diện
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`
Danh sách mô hình	`https://api.moonshot.cn/v1`	`/models`
Truy vấn số dư	`https://api.moonshot.cn/v1`	`/users/me/balance`

Site quốc tế đổi tên miền thành api.moonshot.ai, đường dẫn giữ nguyên. base_url của SDK OpenAI điền đến /v1 là dừng; SDK tự ghép /chat/completions; còn curl phải ghi đầy đủ đường dẫn. Trộn hai cách sẽ tạo thêm hoặc thiếu một lớp /v1, biểu hiện là 404.

Base URL của điểm vào tương thích Anthropic không có /v1; điểm này khác điểm vào OpenAI. Khi dùng Claude Code hoặc SDK Anthropic khác để tích hợp, hãy điền https://api.moonshot.cn/anthropic theo ví dụ chính thức.

3. Chọn tên mô hình

Tên mô hình	Ngữ cảnh	Nhiệm vụ phù hợp	Lưu ý
`kimi-k3`	1M	Suy luận phức tạp, kỹ nghệ phần mềm, công việc tri thức, tài liệu siêu dài	`reasoning_effort` mặc định là `max`
`kimi-k2.7-code`	256K	Sinh mã, hỏi đáp kho mã, Agent	Tuân thủ chỉ dẫn với ngữ cảnh dài tốt hơn
`kimi-k2.7-code-highspeed`	256K	Hoàn thành độ trễ thấp, lập trình tương tác	Cùng mô hình với bản chuẩn, tốc độ nhanh hơn
`kimi-k2.6`	256K	Hội thoại phổ thông, trích xuất, đầu vào hình ảnh và văn bản	Hỗ trợ chế độ suy nghĩ và không suy nghĩ

Các dòng cũ đã ngừng cung cấp: toàn bộ moonshot-v1 và kimi-k2.5 dừng hỗ trợ ngày 31 tháng 8 năm 2026; dòng kimi-k2 dừng hỗ trợ ngày 25 tháng 5 năm 2026; kimi-latest còn sớm hơn. Dự án vẫn dùng các tên này khi nâng cấp nên chuyển thẳng sang kimi-k3 hoặc dòng K2, đừng tiếp tục tìm tài liệu cũ.

Nhiệm vụ phổ thông không nhất thiết mặc định dùng K3. K3 có năng lực cao nhưng cường độ suy luận mặc định cao, độ trễ và Token đầu ra đều tăng; phân loại đơn giản, trích xuất định dạng cố định thường phù hợp hơn với kimi-k2.6. Nhiệm vụ mã mới cân nhắc dòng K2.7 Code.

4. Lần gọi đầu tiên: curl

export MOONSHOT_API_KEY="khoa-cua-ban"

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": "Chỉ trả lời: tích hợp thành công"}
    ],
    "max_completion_tokens": 64
  }'

Trả về 200 và nội dung đúng kỳ vọng nghĩa là khóa, site, tên mô hình và đường dẫn đều đúng. Nếu trả về 401, trước hết kiểm tra site và khóa có khớp không; nếu 404, kiểm tra tên mô hình và /v1; nếu 400, xem thông báo lỗi có nhắc đến ngữ cảnh hoặc giới hạn đầu ra không.

5. SDK Python và truyền phát

Cài SDK OpenAI phiên bản 1.0 trở lên, đổi base_url và khóa là được:

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": "Nêu ba điểm về đội nào phù hợp với API gateway"}],
    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("\nMức dùng: ", chunk.usage)

Phản hồi truyền phát là SSE, mỗi dòng bắt đầu bằng data:, kết thúc bằng data: [DONE]. Khi bật include_usage, trước khi kết thúc sẽ trả thêm một khối có choices rỗng, chỉ chứa usage. Nếu kết nối đứt giữa chừng, khối này có thể không nhận được, vì vậy đừng phụ thuộc hoàn toàn vào client để thống kê mức dùng.

6. max_completion_tokens và cường độ suy luận

max_tokens đã bị loại bỏ; mã mới thống nhất dùng max_completion_tokens. Nó biểu thị độ dài đầu ra mong muốn, không phải tổng độ dài đầu vào cộng đầu ra. Giá trị mặc định của K3 là 131072, có thể đặt tối đa 1048576; nếu đầu vào cộng giá trị này vượt cửa sổ ngữ cảnh, yêu cầu sẽ trả về invalid_request_error.

Hai quy tắc thực dụng:

Nhiệm vụ kiểm thử và định dạng cố định nên đặt giá trị nhỏ, ví dụ 256 đến 1024, tránh mô hình viết dài.
Khi đạt giới hạn, finish_reason là length; kết thúc bình thường là stop. Thấy length đừng thử lại ngay; trước hết xác định đầu ra thật sự cần dài hơn hay lời nhắc quá mở.

K3 còn có tham số cấp cao nhất reasoning_effort, chọn low, high, max, mặc định max. Nhiệm vụ đơn giản hạ xuống low có thể giảm độ trễ và tiêu hao Token; suy luận phức tạp mới nâng lên. Khi dùng SDK OpenAI, nếu phiên bản đó chưa có tham số này, truyền qua extra_body. Nội dung suy nghĩ của K3 nằm trong reasoning_content; khi hội thoại nhiều lượt và gọi công cụ phải mang lại nguyên vẹn.

7. Di chuyển từ OpenAI hoặc Moonshot cũ

Kiểm kê toàn bộ tên mô hình cũ trong mã và cấu hình, lập bảng thay thế.
Sửa base_url: site Trung Quốc https://api.moonshot.cn/v1, site quốc tế https://api.moonshot.ai/v1.
Đổi sang khóa của site tương ứng, không dùng chéo giữa các site.
Thay tên mô hình, ưu tiên kimi-k3 hoặc dòng K2 hiện hành.
Đổi max_tokens thành max_completion_tokens.
Đổi thiết lập thinking của K2.x sang reasoning_effort của K3, không gửi đồng thời cả hai.
Bổ sung stream_options={"include_usage": True} cho yêu cầu truyền phát.
Chạy hồi quy bằng cùng một bộ nhiệm vụ thật, ghi lại chất lượng, độ trễ, finish_reason và mức dùng.
Giữ cấu hình cũ thêm một chu kỳ phát hành, xác nhận không lỗi rồi mới xóa.

Di chuyển không nên chuyển toàn bộ một lần. Trước hết chuyển môi trường kiểm thử, sau đó nghiệp vụ rủi ro thấp, cuối cùng là chuỗi chính; mỗi bước đều giữ công tắc quay lui.

8. Bảng đối chiếu lỗi thường gặp

Mã trạng thái	Loại lỗi	Nguyên nhân thường gặp	Xử lý
400	`invalid_request_error`	Sai tham số, ngữ cảnh quá dài, vượt giới hạn đầu ra	Sửa yêu cầu
400	`content_filter`	Đầu vào hoặc đầu ra kích hoạt an toàn nội dung	Điều chỉnh lời nhắc
401	`invalid_authentication_error`	Khóa không hợp lệ, không khớp site	Đổi khóa hoặc đổi tên miền
404	`resource_not_found_error`	Sai tên mô hình hoặc đường dẫn	Xem danh sách mô hình
429	`rate_limit_reached_error`	Vượt đồng thời, RPM, TPM hoặc TPD	Giảm tốc độ hoặc nâng bậc
429	`exceeded_current_quota_error`	Chậm thanh toán hoặc không đủ số dư	Nạp tiền
504	`Gateway Time-out`	Yêu cầu dài không truyền phát chờ quá lâu	Chuyển sang truyền phát

Yêu cầu không truyền phát chờ phía máy chủ quá 900 giây có thể trả về 504. Sinh văn bản dài, phân tích tài liệu dài và Agent mã nên dùng truyền phát, vừa để client nhận dữ liệu liên tục, vừa giảm lãng phí “chờ đến quá thời gian rồi thử lại”.

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

Base URL nên điền đến lớp nào?

SDK OpenAI điền https://api.moonshot.cn/v1, không kèm /chat/completions. Curl phải ghi đầy đủ https://api.moonshot.cn/v1/chat/completions. SDK Anthropic điền https://api.moonshot.cn/anthropic.

Vì sao max_tokens không có hiệu lực?

Tham số này đã bị loại bỏ; một số dòng mô hình sẽ bỏ qua hoặc báo lỗi. Hãy đổi sang max_completion_tokens, lưu ý đây là giới hạn đầu ra, không phải giới hạn đầu vào cộng thêm.

Vì sao phản hồi K3 chậm hơn kỳ vọng?

K3 mặc định reasoning_effort là max, sẽ suy luận khá sâu. Nhiệm vụ đơn giản hạ xuống low hoặc high và giới hạn độ dài đầu ra thường cải thiện rõ độ trễ.

Vì sao truyền phát kết thúc mà không có usage?

Cần đặt rõ stream_options={"include_usage": True}. Kể cả đã đặt, khi kết nối đứt vẫn có thể không nhận được khối cuối; môi trường sản xuất nên ghi sổ riêng phía máy chủ.

Di chuyển từ OpenAI còn phải sửa gì?

Phần lớn mã chỉ đổi Base URL, khóa và tên mô hình. Còn phải kiểm tra max_tokens, mức dùng truyền phát, ánh xạ loại lỗi và chiến lược thử lại, đặc biệt là phân loại 429.

Bước tiếp theo

Trước hết tạo khóa thử nghiệm tại ZSQH AI Gateway, dùng kimi-k3 và kimi-k2.6 mỗi mô hình chạy một nhiệm vụ thật, xác nhận đường truyền rồi mới tích hợp sản xuất. Mô hình khả dụng và cách tính phí căn cứ theo bảng giá mô hình.

Đọc thêm: