Kimi K3.1 Pro API: จุดเชื่อมต่อ การเรียกใช้เครื่องมือ แคช และข้อผิดพลาด

Kimi K3.1 Pro API ทำงานที่ https://api.moonshot.ai/v1 โดยใช้รหัสโมเดล kimi-k3.1-pro และ kimi-k3.1-pro-highspeed รองรับรูปแบบการสื่อสารสามแบบ ได้แก่ OpenAI Chat Completions, Responses API และ Anthropic Messages ดังนั้น SDK ที่คุณใช้อยู่แล้วก็ใช้งานได้เพียงเปลี่ยน base URL เท่านั้น โมเดลนี้จะปลดล็อกหลังการเติมเงินขั้นต่ำ $1

นี่คือเอกสารอ้างอิงสำหรับโค้ดในโปรดักชัน สำหรับการเรียกใช้งานครั้งแรก การสตรีม และการตั้งค่า Codex หรือ Claude Code โปรดอ่าน วิธีใช้ Kimi K3.1 Pro; สำหรับค่าใช้จ่าย ดูได้ที่ ราคาของ Kimi K3.1 Pro ข้อมูลต่างๆ มาจาก คู่มือเริ่มต้นอย่างรวดเร็วของ K3.1 Pro ของ Moonshot และเอกสารที่เชื่อมโยงไว้ ซึ่งอ่านเมื่อวันที่ 24 ตุลาคม 2026

Responses API, Anthropic API และ Chat Completions ของ Kimi K3.1 Pro

Moonshot เปิดให้เข้าถึง K3.1 Pro ผ่านช่องทาง API สามแบบ เลือกแบบที่ไลบรารีไคลเอนต์หรือเอเจนต์ของคุณรองรับอยู่แล้ว โมเดล คีย์ และการเรียกเก็บเงินเหมือนกันทั้งสามแบบ

ทั้งสามแบบแตกต่างกันในวิธีกำหนดอายุแคช (cache TTL) และตำแหน่งที่ข้อมูลการใช้งานปรากฏ (ดูหัวข้อแคชด้านล่าง) ย้ายมาจาก K3? คู่มือ Kimi K3 API ของเรายังใช้ได้อยู่ K3.1 Pro คือ K3 ที่ผ่านการฝึกเพิ่มเติม (post-trained) โดยมีหน้าต่างบริบท 1,048,576 โทเคนเท่ากัน

API key ของ Kimi K3.1 Pro: ปลดล็อกและตรวจสอบสิทธิ์การเข้าถึง

คุณต้องมีบัญชีที่เติมเงินแล้วและคีย์ที่มาจากผลิตภัณฑ์ที่ถูกต้อง มีสี่ขั้นตอน:

1. เติมเงินอย่างน้อย $1 บนแพลตฟอร์ม Kimi API K3.1 Pro เป็นโมเดลเรือธงและจะปลดล็อกหลังการเติมเงินสำเร็จเท่านั้น
2. สร้างคีย์ในคอนโซล API keys แล้วกำหนดให้เป็นตัวแปรสภาพแวดล้อม MOONSHOT_API_KEY
3. ยืนยันว่าโมเดลนั้นมองเห็นได้จากคีย์ดังกล่าวด้วย GET /v1/models
4. เรียก kimi-k3.1-pro จากโค้ดของคุณ

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

หากโมเดลไม่ปรากฏในรายการ ให้แก้ปัญหานั้นก่อน Kimi API, Kimi Code และ Kimi Membership เป็นผลิตภัณฑ์ที่แยกจากกัน คีย์ของ Kimi Code ใช้กับ endpoint ของ API ไม่ได้ และสมาชิกภาพก็ไม่กลายเป็นยอดคงเหลือใน API

พารามิเตอร์ของคำขอที่สำคัญสำหรับ K3.1 Pro

พารามิเตอร์ของ OpenAI ส่วนใหญ่ทำงานตามที่คุณคาดไว้ ต่อไปนี้คือพารามิเตอร์ที่แตกต่างหรือมักทำให้ผู้ใช้สับสน:

โทเคนสำหรับการคิดวิเคราะห์จะถูกนับรวมในการใช้งานของคุณ ดังนั้นให้ใช้ "low" สำหรับงานจำแนกประเภทและงานสกัดข้อมูล Preserved Thinking เปิดอยู่เสมอ ดังนั้นข้อความของ assistant ทุกข้อความจะถูกส่งกลับไปพร้อม reasoning_content ที่ครบถ้วน (คู่มือโมเดลที่คิดวิเคราะห์)

การเรียกใช้เครื่องมือของ Kimi K3.1 Pro: ลูปที่สมบูรณ์ใน Python

ลูปการเรียกใช้เครื่องมือในโปรดักชันบน K3.1 Pro ทำตามสี่กฎจากเอกสารของ Moonshot:

• บังคับให้เรียกเครื่องมือในเทิร์นแรกด้วย tool_choice="required" แล้วเปลี่ยนเป็น "auto"
• ต่อท้ายข้อความของ assistant ทั้งข้อความ รวมทั้ง reasoning_content และ tool_calls
• ส่งข้อความ tool หนึ่งข้อความต่อ tool_call_id หนึ่งรายการ
• จำกัดจำนวนเทิร์นเพื่อไม่ให้โมเดลที่สับสนวนซ้ำไม่รู้จบ

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"

บั๊กคลาสสิกคือการต่อท้ายด้วย msg.content แทนที่จะเป็น msg ซึ่งจะทำให้ tool_calls และ reasoning_content หายไป

การเรียกใช้เครื่องมือในระดับใหญ่ด้วย search_tools

เมื่อเอเจนต์ของคุณมีเครื่องมือหลายสิบหรือหลายร้อยรายการ อย่าส่งคำนิยามทั้งหมดในทุกคำขอ แนวปฏิบัติที่ดีที่สุดในการเรียกใช้เครื่องมือของ K3 ของ Moonshot แนะนำขั้นตอนดังนี้:

1. ประกาศฟังก์ชัน search_tools หนึ่งฟังก์ชัน (แบ็กเอนด์ของคุณเป็นผู้ทำงานนี้) พร้อมเครื่องมือหลักอีกสองสามรายการ
2. ตั้ง tool_choice: "required" ในเทิร์นแรก เพื่อให้โมเดลดึงข้อมูลก่อนตอบ
3. แทรกคำนิยามเครื่องมือที่ตรงกันผ่านข้อความ system ที่มีฟิลด์ tools
4. ปล่อยให้โมเดลเรียกเครื่องมือที่โหลดมาในเทิร์นถัดๆ ไป โดยตั้ง tool_choice กลับเป็น "auto"

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

คำนิยามที่แทรกเข้ามาใช้รูปแบบ tools ระดับบนสุด และมีผลตั้งแต่ข้อความนั้นเป็นต้นไป เซิร์ฟเวอร์ไม่ได้เก็บคำนิยามเหล่านั้นไว้ ดังนั้นต้องคงข้อความนั้นไว้ในคำขอถัดๆ ไป การเปลี่ยน tool_choice หรือการต่อท้ายคำนิยามใหม่ไม่ทำให้แคชพรีฟิกซ์เสียหาย

อินพุตรูปภาพและวิดีโอ

K3.1 Pro รับรูปภาพและวิดีโอควบคู่กับข้อความ และส่งคืนข้อความ ให้กำหนด content เป็นอาร์เรย์ของส่วนประกอบ ได้แก่ ส่วน image_url (ตัวอย่างในคู่มือเริ่มต้นอย่างรวดเร็วส่งเป็น data URL แบบ base64 และระบุว่าไม่รองรับ URL รูปภาพสาธารณะ) หรือส่วน video_url ที่ชี้ไปยังไฟล์ที่อัปโหลดแล้วด้วย 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."}]

ส่ง content เป็นข้อความของผู้ใช้ และลบไฟล์ด้วย client.files.delete(video.id) เมื่อเสร็จแล้ว

การแคชบริบทในโค้ด

ระบบจะแคชอัตโนมัติสำหรับพรีฟิกซ์ที่ซ้ำกัน โดยมี TTL เริ่มต้น 5 นาที แคชที่ถูกเรียกซ้ำจะคิดราคา $0.20 ต่อหนึ่งล้านโทเคน เทียบกับ $2.00 สำหรับอินพุตที่ไม่ได้แคช และการเขียนแคชแบบ 1 ชั่วโมงมีค่าใช้จ่าย $4.00 เทียบกับ $2.00 สำหรับ 5 นาที หากมีพรีฟิกซ์ขนาด 1 ล้านโทเคน TTL แบบ 1 ชั่วโมงจะคุ้มทุนหลังการเรียกซ้ำเพียงสองครั้ง

ให้วางเนื้อหาที่คงที่ไว้ข้างหน้า (system prompt, คำนิยามเครื่องมือ, เอกสาร) เนื้อหาที่เปลี่ยนแปลงไว้ข้างหลัง และอย่าใส่ timestamp ในพรีฟิกซ์ เมื่อใช้ SDK openai ให้ส่ง TTL ผ่าน 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))

Anthropic API กำหนด TTL ด้วยฟิลด์ cache_control ระดับบนสุด ส่วนเครื่องหมายที่วางไว้ในข้อความจะถูกละเว้น:

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"}]}'

ตำแหน่งที่ข้อมูลการใช้งานแคชปรากฏจะขึ้นอยู่กับช่องทาง API:

เมื่อสตรีม Chat Completions ให้ตั้ง stream_options.include_usage=true เพื่อให้ได้ข้อมูลการใช้งานในชังก์สุดท้าย การเรียกซ้ำแต่ละครั้งจะต่ออายุ TTL ซึ่งถูกล็อกไว้ตั้งแต่การเขียนครั้งแรก กฎแบบเต็มอยู่ในคู่มือการแคชบริบท

ข้อผิดพลาดของ Kimi K3.1 Pro API และวิธีแก้ไข

ความล้มเหลวส่วนใหญ่จัดอยู่ในหกรูปแบบ ให้ตรวจสอบ error.type ทุกครั้งที่เจอ 429 เพราะวิธีแก้ไขขึ้นอยู่กับค่านั้น

ระวังเรื่องการลองใหม่ (retry) OpenAI SDK จะลองใหม่ 2 ครั้งโดยค่าเริ่มต้นเมื่อเกิดข้อผิดพลาดการเชื่อมต่อ 408, 409, 429 และ 5xx ดังนั้นการเรียกหนึ่งครั้งอาจกลายเป็นสามคำขอที่กิน RPM ของคุณ หากอยู่ในระดับต่ำ ให้ลด max_retries ของไคลเอนต์และหน่วงเวลากลับตาม error.type ด้วยตัวเอง คำขอที่ถูกขัดจังหวะด้วย 429 จะไม่ถูกคิดเงิน

หากเอเจนต์ของบุคคลที่สามล้มเหลว ให้เรียก API โดยตรงด้วยคีย์, endpoint และโมเดลเดียวกัน ถ้าใช้งานได้ แสดงว่าเครื่องมือนั้นคือปัญหา ดูหน้าแก้ไขปัญหาและรหัสข้อผิดพลาด

ขีดจำกัดอัตราการใช้งานของ Kimi K3.1 Pro ตามระดับ

ยอดเติมเงินสะสมของคุณเป็นตัวกำหนดระดับของคุณบนหน้าขีดจำกัด:

Tier0 อนุญาต 3 คำขอต่อนาที และทุกเทิร์นของลูปการเรียกใช้เครื่องมือนับเป็นหนึ่งคำขอ การรันเอเจนต์ห้าเทิร์นก็เกินหนึ่งนาทีที่ระดับนั้นแล้ว ดังนั้นควรกันงบประมาณไว้ $10 สะสมก่อนจะทดสอบเอเจนต์อย่างจริงจัง

ทดสอบสัญญา (contract test) ของ Kimi API ด้วย Apidog CLI

การทดสอบสัญญาจะช่วยจับปัญหาวันที่ลูปเครื่องมือของคุณไม่ได้รับ tool_calls กลับมาอีก ให้เอเจนต์เขียนโค้ดของคุณสร้างมันขึ้นมาด้วย Apidog CLI ติดตั้งและเข้าสู่ระบบหนึ่งครั้ง:

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

จากนั้นป้อนพรอมป์ให้ Claude Code, Codex หรือเอเจนต์ตัวไหนก็ตามที่คุณใช้:

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.

เอเจนต์จะอ่านสคีมา ตรวจสอบความถูกต้องของเพย์โหลด แล้วรันเคส:

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

เคสทดสอบต้องมีหมวดหมู่ที่ถูกต้อง คำสั่ง apidog test-case category --project <projectId> จะแสดงรายการหมวดหมู่ทั้งหมด เมื่อการรันผ่านแล้ว ให้เปลี่ยน -r cli,json เป็น -r junit พร้อม --out-dir และการตรวจสอบเดียวกันนี้จะกลายเป็นด่านกั้นใน CI ของคุณ ดังที่แสดงในคู่มือ Apidog CLI CI/CD ของเรา ส่วนการตั้งค่าเอเจนต์อยู่ในApidog CLI ใน Claude Code แผนฟรีของ Apidog รองรับผู้ใช้สูงสุด 4 คน

คำถามที่พบบ่อย

base URL ของ Kimi K3.1 Pro API คืออะไร?

https://api.moonshot.ai/v1 สำหรับ Chat Completions และ Responses API และ https://api.moonshot.ai/anthropic สำหรับ Messages API ที่เข้ากันได้กับ Anthropic

Kimi K3.1 Pro API รองรับพารามิเตอร์ thinking หรือไม่?

ไม่รองรับ การคิดวิเคราะห์เปิดอยู่เสมอ ให้ควบคุมด้วยฟิลด์ระดับบนสุด reasoning_effort ("low", "high" หรือ "max")

ทำไมฉันถึงเจอ 429 ทันทีหลังเติมเงิน?

ให้อ่าน error.type engine_overloaded_error คือกำลังความจุของเซิร์ฟเวอร์ และการเติมเงินจะไม่ช่วยแก้อะไร rate_limit_reached_error หมายถึงขีดจำกัดของระดับคุณ และ Tier0 อนุญาตเพียง 3 RPM

ฉันจะรู้ได้อย่างไรว่าแคชทำงานอยู่?

ฟิลด์การอ่านแคชใน usage ที่มีค่าไม่เป็นศูนย์หมายถึงมีแคชถูกเรียกซ้ำ ได้แก่ prompt_tokens_details.cached_tokens บน Chat Completions หรือ cache_read_input_tokens บน Messages

มีระดับการใช้งาน Kimi K3.1 Pro API แบบฟรีไหม?

ไม่มี API ต้องเติมเงินขั้นต่ำ $1 การแชทฟรีในแอป Kimi คือเส้นทางที่ไม่มีค่าใช้จ่าย ซึ่งอธิบายไว้ในวิธีใช้ Kimi K3.1 Pro แบบฟรี สำหรับความเป็นมาของโมเดล ดูได้ที่ Kimi K3.1 Pro คืออะไร