API Kimi K3.1 Pro: Endpoint, Pemanggilan Tool, Caching, dan Error

API Kimi K3.1 Pro berjalan di https://api.moonshot.ai/v1 dengan ID model kimi-k3.1-pro dan kimi-k3.1-pro-highspeed. API ini mendukung tiga format komunikasi: OpenAI Chat Completions, Responses API, dan Anthropic Messages, sehingga SDK yang sudah Anda gunakan tetap berfungsi hanya dengan mengubah base URL. Model ini terbuka setelah top-up minimal $1.

Ini adalah referensi untuk kode produksi. Untuk panggilan pertama Anda, streaming, serta penyiapan Codex atau Claude Code, baca cara menggunakan Kimi K3.1 Pro; untuk biaya, lihat harga Kimi K3.1 Pro. Fakta bersumber dari quickstart K3.1 Pro milik Moonshot dan dokumen terkait, dibaca 24 Oktober 2026.

Kimi K3.1 Pro Responses API, Anthropic API dan Chat Completions

Moonshot menyediakan K3.1 Pro melalui tiga permukaan API. Pilih yang sudah didukung oleh pustaka klien atau agen Anda; model, kunci, dan penagihannya sama di ketiganya.

Ketiganya berbeda dalam cara Anda menetapkan TTL cache dan di mana penggunaan tercatat (lihat caching di bawah). Baru beralih dari K3? Panduan API Kimi K3 kami masih berlaku; K3.1 Pro adalah K3 yang di-post-training dengan konteks 1.048.576 token yang sama.

Kunci API Kimi K3.1 Pro: buka akses dan periksa ketersediaan

Anda memerlukan akun yang sudah diisi saldonya dan kunci dari produk yang tepat. Empat langkah:

1. Top-up minimal $1 di platform Kimi API. K3.1 Pro adalah model unggulan dan hanya terbuka setelah top-up berhasil.
2. Buat kunci di konsol kunci API dan ekspor sebagai MOONSHOT_API_KEY.
3. Pastikan model terlihat oleh kunci tersebut dengan GET /v1/models.
4. Panggil kimi-k3.1-pro dari kode.

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

Jika model tidak tercantum, bereskan itu dulu. Kimi API, Kimi Code, dan Kimi Membership adalah produk terpisah: kunci Kimi Code tidak akan berfungsi di endpoint API, dan keanggotaan tidak berubah menjadi saldo API.

Parameter permintaan yang penting untuk K3.1 Pro

Sebagian besar parameter OpenAI berperilaku seperti yang Anda harapkan. Berikut yang berbeda atau sering menjebak:

Token penalaran dihitung dalam penggunaan Anda, jadi gunakan "low" untuk klasifikasi dan ekstraksi. Preserved Thinking selalu aktif, sehingga setiap pesan assistant dikembalikan dengan reasoning_content-nya utuh (panduan model thinking).

Tool calling Kimi K3.1 Pro: loop lengkap dalam Python

Loop tool untuk produksi di K3.1 Pro mengikuti empat aturan dari dokumen Moonshot:

• Paksa pemanggilan tool pada giliran pertama dengan tool_choice="required", lalu beralih ke "auto".
• Tambahkan pesan assistant secara lengkap, termasuk reasoning_content dan tool_calls.
• Kirim satu pesan tool per tool_call_id.
• Batasi jumlah giliran agar model yang bingung tidak bisa berputar tanpa henti.

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"

Bug klasiknya adalah menambahkan msg.content alih-alih msg, yang menghilangkan tool_calls dan reasoning_content.

Tool calling dalam skala besar dengan search_tools

Ketika agen Anda memiliki puluhan atau ratusan tool, jangan kirim setiap definisi pada setiap permintaan. Praktik terbaik tool calling K3 dari Moonshot merekomendasikan alur ini:

1. Deklarasikan satu fungsi search_tools (backend Anda yang mengimplementasikannya) plus beberapa tool inti.
2. Tetapkan tool_choice: "required" pada giliran pertama agar model mengambil data sebelum menjawab.
3. Suntikkan definisi tool yang cocok melalui pesan system yang membawa field tools.
4. Biarkan model memanggil tool yang telah dimuat pada giliran berikutnya, dengan tool_choice kembali ke "auto".

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

Definisi yang disuntikkan menggunakan format tools tingkat atas dan berlaku sejak pesan itu dan seterusnya. Server tidak menyimpannya, jadi pertahankan pesan tersebut di permintaan berikutnya. Mengubah tool_choice maupun menambahkan definisi tidak merusak cache prefiks.

Input gambar dan video

K3.1 Pro menerima gambar dan video bersama teks dan mengembalikan teks. Buat content menjadi array bagian: bagian image_url (contoh di quickstart mengirim data URL base64, dan dicatat bahwa URL gambar publik tidak didukung) atau bagian video_url yang menunjuk ke file yang diunggah dengan 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."}]

Kirimkan content sebagai pesan user, dan hapus file dengan client.files.delete(video.id) setelah selesai.

Caching konteks dalam kode

Caching otomatis untuk prefiks yang berulang dengan TTL default 5 menit. Cache hit ditagih $0,20 per juta token dibandingkan $2,00 untuk input tanpa cache, dan penulisan 1 jam berbiaya $4,00 dibandingkan $2,00 untuk 5 menit. Pada prefiks 1 juta token, TTL 1 jam sudah balik modal setelah dua kali hit.

Letakkan konten stabil di awal (system prompt, definisi tool, dokumen), konten yang berubah di akhir, dan jangan ada timestamp di dalam prefiks. Dengan SDK openai, kirim TTL melalui 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 menetapkan TTL dengan field cache_control tingkat atas; penanda di dalam pesan akan diabaikan:

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

Di mana penggunaan cache muncul bergantung pada permukaannya:

Saat melakukan streaming Chat Completions, tetapkan stream_options.include_usage=true untuk mendapatkan penggunaan di chunk terakhir. Setiap hit memperbarui TTL, yang terkunci pada penulisan pertama. Aturan lengkapnya: panduan caching konteks.

Error API Kimi K3.1 Pro dan solusinya

Sebagian besar kegagalan masuk ke dalam enam pola. Periksa error.type pada setiap 429, karena solusinya bergantung pada itu.

Perhatikan retry. SDK OpenAI melakukan retry 2 kali secara default pada error koneksi, 408, 409, 429, dan 5xx, sehingga satu panggilan bisa menjadi tiga permintaan terhadap RPM Anda. Pada tier rendah, turunkan max_retries klien dan lakukan back off sendiri berdasarkan error.type. Permintaan yang terputus karena 429 tidak dikenakan biaya.

Jika agen pihak ketiga gagal, panggil API secara langsung dengan kunci, endpoint, dan model yang sama. Jika berhasil, berarti masalahnya ada di tool tersebut. Lihat halaman troubleshooting dan kode error.

Batas laju Kimi K3.1 Pro per tier

Total top-up kumulatif Anda menentukan tier Anda di halaman batas:

Tier0 mengizinkan 3 permintaan per menit, dan setiap giliran dalam loop tool adalah satu permintaan. Satu kali menjalankan agen dengan lima giliran saja sudah melewati satu menit pada tier tersebut, jadi anggarkan $10 kumulatif sebelum Anda menguji agen secara serius.

Uji kontrak API Kimi dengan Apidog CLI

Uji kontrak akan menangkap hari ketika loop tool Anda berhenti menerima tool_calls kembali. Biarkan agen coding Anda membangunnya dengan Apidog CLI. Instal dan masuk sekali:

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

Lalu beri prompt ke Claude Code, Codex, atau agen apa pun yang Anda gunakan:

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.

Agen tersebut membaca skema, memvalidasi payload-nya, dan menjalankan 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

Test case memerlukan kategori yang valid; apidog test-case category --project <projectId> akan menampilkannya. Setelah run berhasil, ganti -r cli,json dengan -r junit beserta --out-dir dan pemeriksaan yang sama akan menjaga CI Anda, seperti yang ditunjukkan panduan CI/CD Apidog CLI kami. Penyiapan agen ada di Apidog CLI di Claude Code. Paket Free Apidog mencakup hingga 4 pengguna.

FAQ

Apa base URL untuk API Kimi K3.1 Pro?

https://api.moonshot.ai/v1 untuk Chat Completions dan Responses API, serta https://api.moonshot.ai/anthropic untuk Messages API yang kompatibel dengan Anthropic.

Apakah API Kimi K3.1 Pro mendukung parameter thinking?

Tidak. Proses berpikir selalu aktif. Kendalikan dengan field reasoning_effort tingkat atas ("low", "high", atau "max").

Mengapa saya mendapat 429 tepat setelah top-up?

Baca error.type. engine_overloaded_error berarti kapasitas server dan top-up tidak akan memperbaikinya. rate_limit_reached_error berarti batas tier Anda, dan Tier0 hanya mengizinkan 3 RPM.

Bagaimana saya tahu apakah caching berfungsi?

Field baca cache yang tidak nol di usage berarti terjadi hit: prompt_tokens_details.cached_tokens pada Chat Completions atau cache_read_input_tokens pada Messages.

Apakah ada tier gratis untuk API Kimi K3.1 Pro?

Tidak ada. API memerlukan top-up minimal $1. Chat gratis di aplikasi Kimi adalah jalur $0, dibahas dalam cara menggunakan Kimi K3.1 Pro secara gratis. Untuk latar belakang model, lihat apa itu Kimi K3.1 Pro.