Kimi K3.1 Pro API: Endpoint, gọi công cụ, bộ nhớ đệm và lỗi

API Kimi K3.1 Pro chạy tại https://api.moonshot.ai/v1 với các model ID kimi-k3.1-pro và kimi-k3.1-pro-highspeed. Nó hỗ trợ ba định dạng truyền tải: OpenAI Chat Completions, Responses API và Anthropic Messages, nên các SDK bạn đang dùng vẫn hoạt động chỉ với việc thay đổi base URL. Model sẽ được mở khóa sau khi nạp tối thiểu 1 đô la.

Đây là tài liệu tham khảo cho mã production. Đối với lần gọi đầu tiên, streaming và các thiết lập Codex hay Claude Code, hãy đọc cách sử dụng Kimi K3.1 Pro; về chi phí, xem bảng giá Kimi K3.1 Pro. Các thông tin được lấy từ hướng dẫn nhanh K3.1 Pro của Moonshot và các tài liệu được liên kết, đọc ngày 24 tháng 10 năm 2026.

Kimi K3.1 Pro Responses API, Anthropic API và Chat Completions

Moonshot cung cấp K3.1 Pro thông qua ba bề mặt API. Hãy chọn bề mặt mà thư viện client hoặc agent của bạn đã hỗ trợ; model, key và việc tính phí đều giống nhau trên cả ba.

Chúng khác nhau ở cách bạn đặt TTL của cache và nơi thông tin usage được ghi nhận (xem phần caching bên dưới). Đang chuyển từ K3? Hướng dẫn API Kimi K3 của chúng tôi vẫn còn áp dụng; K3.1 Pro là phiên bản K3 được huấn luyện hậu kỳ với cùng ngữ cảnh 1.048.576 token.

API key Kimi K3.1 Pro: mở khóa và kiểm tra quyền truy cập

Bạn cần một tài khoản đã nạp tiền và một key từ đúng sản phẩm. Bốn bước:

1. Nạp tối thiểu 1 đô la trên nền tảng Kimi API. K3.1 Pro là model chủ lực và chỉ được mở khóa sau khi nạp tiền thành công.
2. Tạo một key trong bảng điều khiển API keys và export nó thành MOONSHOT_API_KEY.
3. Xác nhận model hiển thị với key đó bằng GET /v1/models.
4. Gọi kimi-k3.1-pro từ mã nguồn.

curl https://api.moonshot.ai/v1/models \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" | grep -o '"kimi-k3.1-pro[^"]*"'

Nếu model không được liệt kê, hãy xử lý điều đó trước. Kimi API, Kimi Code và Kimi Membership là những sản phẩm riêng biệt: key của Kimi Code sẽ không hoạt động trên endpoint API, và membership không trở thành số dư API.

Các tham số request quan trọng đối với K3.1 Pro

Hầu hết các tham số OpenAI đều hoạt động như bạn mong đợi. Đây là những tham số khác biệt hoặc dễ khiến người dùng nhầm lẫn:

Các token suy luận được tính vào usage của bạn, vì vậy hãy dùng "low" cho phân loại và trích xuất. Preserved Thinking luôn được bật, nên mọi tin nhắn assistant đều được trả về với reasoning_content còn nguyên vẹn (hướng dẫn về các model suy luận).

Gọi công cụ Kimi K3.1 Pro: một vòng lặp hoàn chỉnh bằng Python

Một vòng lặp công cụ production trên K3.1 Pro tuân theo bốn quy tắc từ tài liệu của Moonshot:

• Buộc gọi công cụ ở lượt đầu tiên bằng tool_choice="required", sau đó chuyển sang "auto".
• Thêm toàn bộ tin nhắn assistant, bao gồm cả reasoning_content và tool_calls.
• Gửi một tin nhắn tool cho mỗi tool_call_id.
• Giới hạn số lượt để một model bị rối không thể lặp vô hạn.

import json, os
from openai import OpenAI

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

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up an order's shipping status by ID",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]}}}]

def get_order_status(order_id):
    return {"order_id": order_id, "status": "shipped"}

messages = [{"role": "user", "content": "Where is order A-1042?"}]
tool_choice = "required"
for _ in range(8):  # hard cap on turns
    resp = client.chat.completions.create(
        model="kimi-k3.1-pro", reasoning_effort="high",
        messages=messages, tools=TOOLS, tool_choice=tool_choice)
    msg = resp.choices[0].message
    messages.append(msg)  # whole message, not msg.content
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        result = get_order_status(**json.loads(call.function.arguments))
        messages.append({"role": "tool", "tool_call_id": call.id,
                         "content": json.dumps(result)})
    tool_choice = "auto"

Lỗi kinh điển là thêm msg.content thay vì msg, điều này làm mất tool_calls và reasoning_content.

Gọi công cụ ở quy mô lớn với search_tools

Khi agent của bạn có hàng chục hoặc hàng trăm công cụ, đừng gửi mọi định nghĩa trong mỗi request. Thực hành tốt nhất về gọi công cụ của K3 từ Moonshot khuyến nghị luồng sau:

1. Khai báo một hàm search_tools (backend của bạn triển khai nó) cùng một vài công cụ cốt lõi.
2. Đặt tool_choice: "required" ở lượt đầu tiên để model truy xuất trước khi trả lời.
3. Chèn các định nghĩa công cụ khớp thông qua một tin nhắn system mang trường tools.
4. Để model gọi các công cụ đã nạp ở các lượt sau, với tool_choice quay lại "auto".

# after search_tools returns ["create_github_pr"]
messages.append({"role": "system",
                 "tools": [CATALOG["create_github_pr"]]})

Các định nghĩa được chèn sử dụng định dạng tools cấp cao nhất và có hiệu lực từ tin nhắn đó trở đi. Server không lưu giữ chúng, vì vậy hãy giữ tin nhắn đó trong các request sau. Việc thay đổi tool_choice hay thêm một định nghĩa đều không làm hỏng prefix cache.

Đầu vào hình ảnh và video

K3.1 Pro chấp nhận hình ảnh và video cùng với văn bản và trả về văn bản. Hãy đặt content thành một mảng các phần: một phần image_url (ví dụ trong hướng dẫn nhanh gửi một data URL base64, và lưu ý rằng URL hình ảnh công khai không được hỗ trợ) hoặc một phần video_url trỏ đến một tệp đã tải lên với ID ms://.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")
content = [{"type": "video_url", "video_url": {"url": f"ms://{video.id}"}},
           {"type": "text", "text": "Summarize this video."}]

Truyền content làm tin nhắn user, và xóa tệp bằng client.files.delete(video.id) khi bạn hoàn tất.

Cache ngữ cảnh trong mã nguồn

Việc caching diễn ra tự động đối với các tiền tố lặp lại với TTL mặc định là 5 phút. Các lần trúng cache được tính phí 0,20 đô la cho mỗi triệu token so với 2,00 đô la cho đầu vào không được cache, và một lần ghi với TTL 1 giờ tốn 4,00 đô la so với 2,00 đô la cho 5 phút. Với tiền tố 1M token, TTL 1 giờ sẽ hoàn vốn sau hai lần trúng cache.

Hãy đặt nội dung ổn định lên trước (system prompt, định nghĩa công cụ, tài liệu), nội dung thay đổi ở cuối, và không có timestamp trong tiền tố. Với SDK openai, truyền TTL qua extra_body:

resp = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "system", "content": DOCS},
              {"role": "user", "content": question}],
    extra_body={"prompt_cache_options": {"mode": "implicit", "ttl": "1h"}},
)
d = resp.usage.prompt_tokens_details
print(resp.usage.prompt_tokens, d.cached_tokens,
      getattr(d, "cache_write_tokens", 0))

API Anthropic đặt TTL bằng trường cache_control cấp cao nhất; các marker bên trong tin nhắn sẽ bị bỏ qua:

curl https://api.moonshot.ai/anthropic/v1/messages \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $MOONSHOT_API_KEY" \
  --data '{"model": "kimi-k3.1-pro", "max_tokens": 256,
    "cache_control": {"type": "ephemeral", "ttl": "1h"},
    "messages": [{"role": "user", "content": "Hello"}]}'

Việc sử dụng cache hiển thị ở đâu phụ thuộc vào bề mặt:

Khi streaming Chat Completions, hãy đặt stream_options.include_usage=true để nhận usage trong chunk cuối cùng. Mỗi lần trúng cache sẽ gia hạn TTL, vốn được cố định ở lần ghi đầu tiên. Quy tắc đầy đủ: hướng dẫn cache ngữ cảnh.

Lỗi API Kimi K3.1 Pro và cách khắc phục

Hầu hết các lỗi rơi vào sáu dạng. Hãy kiểm tra error.type trên mọi lỗi 429, vì cách khắc phục phụ thuộc vào nó.

Hãy chú ý đến việc thử lại. SDK OpenAI mặc định thử lại 2 lần với lỗi kết nối, 408, 409, 429 và 5xx, nên một lệnh gọi có thể biến thành ba request đối với RPM của bạn. Ở tier thấp, hãy giảm max_retries của client và tự backoff theo error.type. Các request bị gián đoạn bởi 429 sẽ không bị tính phí.

Nếu một agent của bên thứ ba thất bại, hãy gọi API trực tiếp với cùng key, endpoint và model. Nếu cách đó hoạt động, thì công cụ chính là vấn đề. Xem trang khắc phục sự cố và mã lỗi.

Giới hạn tốc độ Kimi K3.1 Pro theo tier

Tổng số tiền nạp tích lũy của bạn quyết định tier của bạn trên trang giới hạn:

Tier0 cho phép 3 request mỗi phút, và mỗi lượt của một vòng lặp công cụ là một request. Một lần chạy agent gồm năm lượt đã vượt quá một phút ở tier đó, vì vậy hãy dự trù 10 đô la tích lũy trước khi bạn kiểm thử agent một cách nghiêm túc.

Kiểm thử hợp đồng Kimi API với Apidog CLI

Một bài kiểm thử hợp đồng sẽ phát hiện ngày mà vòng lặp công cụ của bạn ngừng nhận lại tool_calls. Hãy để agent lập trình của bạn xây dựng nó với Apidog CLI. Cài đặt và đăng nhập một lần:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
apidog skill install

Sau đó gợi ý cho Claude Code, Codex hoặc bất kỳ agent nào bạn dùng:

In Apidog project <projectId>, create an environment for https://api.moonshot.ai/v1
and an endpoint for POST /chat/completions. Add a test case that sends model
kimi-k3.1-pro, reasoning_effort "low", one get_order_status tool and
tool_choice "required". Assert status 200 and that choices[0].message.tool_calls
is non-empty. Run it and report failures.

Agent sẽ đọc schema, xác thực payload của nó và chạy test case:

apidog environment create kimi-prod --project <projectId> --base-url https://api.moonshot.ai/v1
apidog endpoint create --project <projectId> --file ./endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

Các test case cần một category hợp lệ; apidog test-case category --project <projectId> sẽ liệt kê chúng. Khi lần chạy đã đạt, hãy thay -r cli,json bằng -r junit cùng --out-dir và kiểm tra tương tự sẽ gác cổng CI của bạn, như hướng dẫn CI/CD của Apidog CLI của chúng tôi trình bày. Thiết lập agent nằm trong Apidog CLI trong Claude Code. Gói Miễn phí của Apidog hỗ trợ tối đa 4 người dùng.

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

Base URL cho API Kimi K3.1 Pro là gì?

https://api.moonshot.ai/v1 cho Chat Completions và Responses API, và https://api.moonshot.ai/anthropic cho Messages API tương thích với Anthropic.

API Kimi K3.1 Pro có hỗ trợ tham số thinking không?

Không. Suy luận luôn được bật. Hãy kiểm soát nó bằng trường reasoning_effort cấp cao nhất ("low", "high" hoặc "max").

Tại sao tôi nhận lỗi 429 ngay sau khi nạp tiền?

Hãy đọc error.type. engine_overloaded_error là năng lực của server và việc nạp tiền sẽ không khắc phục được. rate_limit_reached_error nghĩa là các giới hạn của tier bạn, và Tier0 chỉ cho phép 3 RPM.

Làm sao để biết caching có hoạt động không?

Một trường đọc cache khác không trong usage nghĩa là có trúng cache: prompt_tokens_details.cached_tokens trên Chat Completions hoặc cache_read_input_tokens trên Messages.

Có tier miễn phí cho API Kimi K3.1 Pro không?

Không. API cần nạp tối thiểu 1 đô la. Chat miễn phí trong ứng dụng Kimi là con đường 0 đô la, được đề cập trong cách sử dụng Kimi K3.1 Pro miễn phí. Để biết thông tin nền về model, xem Kimi K3.1 Pro là gì.