Kimi K3.1 Pro API: Endpoint'ler, Araç Çağırma, Önbellekleme ve Hatalar

Kimi K3.1 Pro API'si https://api.moonshot.ai/v1 adresinde, kimi-k3.1-pro ve kimi-k3.1-pro-highspeed model kimlikleriyle çalışır. Üç tel formatını konuşur: OpenAI Chat Completions, Responses API ve Anthropic Messages; böylece zaten kullandığınız SDK'lar değiştirilmiş bir base URL ile çalışır. Model, minimum 1 $ yükleme yapıldıktan sonra açılır.

Bu, üretim kodu için referanstır. İlk çağrınız, streaming ve Codex ya da Claude Code kurulumları için Kimi K3.1 Pro nasıl kullanılır yazısını okuyun; maliyetler için Kimi K3.1 Pro fiyatlandırması sayfasına bakın. Bilgiler Moonshot'ın K3.1 Pro hızlı başlangıç ve bağlantılı dokümanlarından alınmıştır; okunma tarihi 24 Ekim 2026.

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

Moonshot, K3.1 Pro'yu üç API yüzeyi üzerinden sunar. İstemci kütüphanenizin veya ajanınızın zaten konuştuğu olanı seçin; model, anahtar ve faturalandırma üçünde de aynıdır.

Önbellek TTL'ini nasıl ayarladığınız ve kullanımın nereye düştüğü konusunda farklılık gösterirler (aşağıdaki önbellekleme bölümüne bakın). K3'ten mi geliyorsunuz? Kimi K3 API rehberimiz hâlâ geçerlidir; K3.1 Pro, aynı 1.048.576 token'lık bağlama sahip, sonradan eğitilmiş bir K3'tür.

Kimi K3.1 Pro API anahtarı: erişimi açma ve kontrol etme

Bakiyesi olan bir hesaba ve doğru üründen alınmış bir anahtara ihtiyacınız var. Dört adım:

1. Kimi API platformunda en az 1 $ yükleyin. K3.1 Pro amiral gemisi bir modeldir ve yalnızca başarılı bir yükleme sonrasında açılır.
2. API anahtarları konsolunda bir anahtar oluşturun ve onu MOONSHOT_API_KEY olarak export edin.
3. Modelin o anahtar tarafından görülebildiğini GET /v1/models ile doğrulayın.
4. Koddan kimi-k3.1-pro'yu çağırın.

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

Model listede yoksa önce bunu düzeltin. Kimi API, Kimi Code ve Kimi Membership ayrı ürünlerdir: bir Kimi Code anahtarı API uç noktasında çalışmaz ve bir üyelik API bakiyesine dönüşmez.

K3.1 Pro için önem taşıyan istek parametreleri

Çoğu OpenAI parametresi beklediğiniz gibi davranır. Farklı olan ya da insanları yanıltan parametreler şunlardır:

Reasoning token'ları kullanımınıza sayılır, bu yüzden sınıflandırma ve çıkarım için "low" kullanın. Preserved Thinking her zaman açıktır, bu yüzden her assistant mesajı reasoning_content'i bozulmadan geri gönderilir (thinking modelleri rehberi).

Kimi K3.1 Pro araç çağırma: Python'da eksiksiz bir döngü

K3.1 Pro üzerinde üretim amaçlı bir araç döngüsü, Moonshot'ın dokümanlarındaki dört kuralı izler:

• İlk turda tool_choice="required" ile bir araç çağrısını zorlayın, sonra "auto"ya geçin.
• Assistant mesajının tamamını, reasoning_content ve tool_calls dahil, ekleyin.
• Her tool_call_id için bir tool mesajı gönderin.
• Kafası karışan bir modelin sonsuza dek döngüde kalmaması için tur sayısına bir üst sınır koyun.

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"

Klasik hata, msg yerine msg.content eklemektir; bu, tool_calls ve reasoning_content'i düşürür.

search_tools ile ölçekli araç çağırma

Ajanınızda düzinelerce ya da yüzlerce araç olduğunda, her istekte her tanımı göndermeyin. Moonshot'ın K3 araç çağırma en iyi uygulamaları şu akışı önerir:

1. Bir search_tools fonksiyonu (bunu arka ucunuz uygular) artı birkaç temel araç tanımlayın.
2. İlk turda tool_choice: "required" ayarlayın ki model yanıtlamadan önce araçları getirsin.
3. Eşleşen araç tanımlarını, bir tools alanı taşıyan bir system mesajı aracılığıyla enjekte edin.
4. Sonraki turlarda modelin yüklenen araçları çağırmasına izin verin; tool_choice yeniden "auto" olsun.

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

Enjekte edilen tanımlar üst düzey tools biçimini kullanır ve o mesajdan itibaren geçerli olur. Sunucu bunları saklamaz, bu yüzden mesajı sonraki isteklerde tutun. Ne tool_choice'ı değiştirmek ne de bir tanım eklemek önek önbelleğini bozar.

Görüntü ve video girdisi

K3.1 Pro, metnin yanı sıra görüntü ve video kabul eder ve metin döndürür. content'i bir parça dizisi yapın: bir image_url parçası (hızlı başlangıç örneği bir base64 data URL gönderir ve herkese açık görüntü URL'lerinin desteklenmediğini belirtir) ya da ms:// kimliğiyle yüklenmiş bir dosyaya işaret eden bir video_url parçası.

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'i kullanıcı mesajı olarak geçirin ve işiniz bittiğinde dosyayı client.files.delete(video.id) ile silin.

Kodda bağlam önbellekleme

Önbellekleme, tekrarlanan önekler için otomatik olarak ve varsayılan 5 dakikalık TTL ile çalışır. Önbellek isabetleri milyon token başına 0,20 $ olarak faturalandırılır; önbelleğe alınmamış girdi ise 2,00 $'dır ve 1 saatlik yazma 4,00 $ iken 5 dakikalık yazma 2,00 $'dır. 1M token'lık bir önekte, 1 saatlik TTL iki isabetten sonra kendini amorti eder.

Sabit içeriği başa koyun (system prompt, araç tanımları, dokümanlar), değişen içeriği sona koyun ve önekte zaman damgası bulundurmayın. openai SDK'sıyla TTL'i extra_body üzerinden geçirin:

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'de TTL, üst düzey bir cache_control alanıyla ayarlanır; mesajların içindeki işaretleyiciler yok sayılır:

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

Önbellek kullanımının nerede göründüğü yüzeye bağlıdır:

Chat Completions'ı stream ederken, son parçada kullanım bilgisini almak için stream_options.include_usage=true ayarlayın. Her isabet TTL'i yeniler; TTL ilk yazmada sabitlenir. Tüm kurallar: bağlam önbellekleme rehberi.

Kimi K3.1 Pro API hataları ve çözümleri

Çoğu hata altı kalıba girer. Her 429'da error.type alanını kontrol edin, çünkü çözüm buna bağlıdır.

Yeniden denemelere dikkat edin. OpenAI SDK'sı varsayılan olarak bağlantı hatalarında, 408, 409, 429 ve 5xx durumlarında 2 kez yeniden dener; böylece tek bir çağrı, RPM'inize karşı üç isteğe dönüşebilir. Düşük bir kademedeyseniz istemcinin max_retries değerini düşürün ve error.type değerine göre kendiniz geri çekilin. 429 ile kesilen istekler ücretlendirilmez.

Üçüncü taraf bir ajan başarısız olursa, API'yi aynı anahtar, uç nokta ve modelle doğrudan çağırın. Bu çalışıyorsa sorun araçtadır. sorun giderme sayfasına ve hata kodlarına bakın.

Kademeye göre Kimi K3.1 Pro hız limitleri

Kümülatif yüklemeniz, limitler sayfasında kademenizi belirler:

Tier0 dakikada 3 isteğe izin verir ve bir araç döngüsünün her turu bir istektir. Beş turluk bir ajan çalışması bu kademede bile bir dakikayı aşar, bu yüzden ajanları ciddi şekilde test etmeden önce kümülatif 10 $ bütçeleyin.

Kimi API'sini Apidog CLI ile sözleşme testinden geçirin

Bir sözleşme testi, araç döngünüzün artık tool_calls almadığı günü yakalar. Kodlama ajanınızın bunu Apidog CLI ile oluşturmasına izin verin. Bir kez kurun ve giriş yapın:

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

Sonra Claude Code'a, Codex'e ya da kullandığınız ajana şu prompt'u verin:

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.

Ajan şemayı okur, payload'ını doğrular ve test durumunu çalıştırır:

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 durumlarının geçerli bir kategoriye ihtiyacı vardır; apidog test-case category --project <projectId> bunları listeler. Çalıştırma geçtikten sonra, -r cli,json yerine --out-dir ile -r junit koyun; aynı kontrol CI'ınızı da denetler, Apidog CLI CI/CD rehberimizin gösterdiği gibi. Ajan kurulumu Claude Code'da Apidog CLI yazısında yer alır. Apidog'un Free planı 4 kullanıcıya kadar kapsar.

SSS

Kimi K3.1 Pro API'sinin base URL'i nedir?

Chat Completions ve Responses API için https://api.moonshot.ai/v1, Anthropic uyumlu Messages API için https://api.moonshot.ai/anthropic.

Kimi K3.1 Pro API'si thinking parametresini destekliyor mu?

Hayır. Düşünme her zaman açıktır. Bunu üst düzey reasoning_effort alanıyla ("low", "high" ya da "max") kontrol edin.

Neden yükleme yaptıktan hemen sonra 429 alıyorum?

error.type değerini okuyun. engine_overloaded_error sunucu kapasitesidir ve bir yükleme bunu düzeltmez. rate_limit_reached_error kademenizin limitleri anlamına gelir ve Tier0 yalnızca 3 RPM'e izin verir.

Önbelleklemenin çalışıp çalışmadığını nasıl anlarım?

usage içinde sıfırdan farklı bir önbellek okuma alanı bir isabet anlamına gelir: Chat Completions'da prompt_tokens_details.cached_tokens ya da Messages'da cache_read_input_tokens.

Ücretsiz bir Kimi K3.1 Pro API kademesi var mı?

Hayır. API, minimum 1 $ yükleme gerektirir. Kimi uygulamasındaki ücretsiz sohbet 0 $ yoludur ve Kimi K3.1 Pro nasıl ücretsiz kullanılır yazısında ele alınmıştır. Model arka planı için Kimi K3.1 Pro nedir yazısına bakın.