Kimi K3 API Kılavuzu: Python, Vizyon, Araçlar ve 1M Bağlamı

Kimi K3 API geliştirici kılavuzu

Kimi K3, kimi-k3 model kimliğine sahip Moonshot AI'ın OpenAI uyumlu Chat Completions API'si aracılığıyla edinilebilir. API her zaman açık akıl yürütmeyi, akışı, görüntüleri, yüklenen videoyu, katı JSON Şemasını, özel araçları, dinamik araç yüklemeyi ve 1 milyon tokenlık bağlam penceresini destekler.

Uyumluluk aynı davranış anlamına gelmez. K3'ün sabit örnekleme değerleri vardır, daha sonraki araç ve konuşma turlarında tam yardımcı durumu gerektirir ve muhakemeyi nihai içerikten ayrı olarak ele alır. Bu kılavuz bu ayrıntılara odaklanmaktadır.

Kullanılabilirlik ve fiyatlar 22 Temmuz 2026'da güncellendi. Kimi K3, Poyo.ai üzerinde, OpenAI uyumlu Chat Completions API'si aracılığıyla kimi-k3 olarak mevcuttur. Fiyatlandırma 1M giriş tokenı başına $2.28 ve 1M çıkış tokenı başına $11.40'dur — resmi fiyatlandırmadan %24 daha düşüktür.

Gereksinimler

İhtiyacınız var:

Python 3.9 veya daha yenisi;
openai Python paket sürümü 1.0 veya daha yenisi;
kaynak kontrolü dışında saklanan bir Moonshot API anahtarı;
https://api.moonshot.ai/v1 temel URL'si;
model kimliği kimi-k3.

SDK'yu yükleyin:

python -m pip install --upgrade "openai>=1.0"

Anahtarı kabuğunuzda ayarlayın:

export MOONSHOT_API_KEY="your-key"

PowerShell'de:

$env:MOONSHOT_API_KEY="your-key"

Üretim anahtarını asla bir kod örneğine, istemci tarafı paketine, günlüğe veya repository'ye yerleştirmeyin.

İlk Kimi K3 isteğinizi yapın

Python

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Review this migration plan and list its three highest risks."}
    ],
)

print(response.choices[0].message.content)

cURL

curl https://api.moonshot.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain Kimi Delta Attention in plain language."}
    ]
  }'

Akıl yürütme çabasını yapılandırın

K3 her zaman düşünme modunu kullanır. Çabasını üst düzey reasoning_effort alanı aracılığıyla yapılandırın:

response = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="high",
    messages=[
        {"role": "user", "content": "Find the flaw in this distributed lock design."}
    ],
)

Desteklenen değerler şunlardır:

Değer	Kullanım alanı
`low`	Gecikme ve çıktının önemli olduğu daha kolay görevler
`high`	Zor kodlama, analiz ve araç planlama
`max`	En zor görevler ve kıyaslama tarzı değerlendirme

Belgelenen varsayılan max'dur. Bunun en ucuz üretim ortamı olduğunu varsaymayın. Her çabada başarı oranını, gecikmeyi ve oluşturulan tokenları değerlendirin.

Akıl yürütme ve son içerik akışı

Akış yanıtları, farklı delta alanları aracılığıyla muhakemeyi ve son metni ortaya çıkarır.

stream = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Review this architecture for race conditions."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        # Store or process according to your product and provider policies.
        pass
    if delta.content:
        print(delta.content, end="", flush=True)

Kullanıcıya yönelik nihai içeriği dahili işlemlerden ayrı tutun. reasoning_content'dan yapılandırılmış çıktıyı ayrıştırmayın.

Kimi K3'e bir resim gönder

K3 vizyon mesajları bir dizi içerik nesnesini kullanır. Genel resim URL'leri bu akışta desteklenmez; yerel bir görüntüyü base64 olarak kodlayın.

import base64
from pathlib import Path

image_data = base64.b64encode(Path("interface.png").read_bytes()).decode()

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/png;base64,{image_data}"},
                },
                {
                    "type": "text",
                    "text": "Identify the three largest accessibility problems in this interface.",
                },
            ],
        }
    ],
)

Kullanıcı yüklemelerini kodlamadan önce dosya türünü ve boyutunu doğrulayın. Base64 yüklerini günlüğe kaydetmekten kaçının.

Kimi K3'e bir video gönderin

API Dosyaları aracılığıyla videoyu yükleyin, döndürülen kimliğe ms:// şemasıyla başvurun ve artık gerekmediğinde dosyayı silin.

from pathlib import Path

video = client.files.create(file=Path("demo.mp4"), purpose="video")

try:
    response = client.chat.completions.create(
        model="kimi-k3",
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "video_url",
                        "video_url": {"url": f"ms://{video.id}"},
                    },
                    {"type": "text", "text": "Summarize the workflow and identify failed steps."},
                ],
            }
        ],
    )
finally:
    client.files.delete(video.id)

Kesin JSON Şema çıktısını döndür

Aşağı akış kodunun öngörülebilir bir şekle ihtiyacı olduğunda strict: true seçeneğini kullanın.

import json

response = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Extract the risk, severity, and owner from this incident note."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "incident_risk",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "risk": {"type": "string"},
                    "severity": {"type": "string", "enum": ["low", "medium", "high"]},
                    "owner": {"type": ["string", "null"]},
                },
                "required": ["risk", "severity", "owner"],
                "additionalProperties": False,
            },
        },
    },
)

result = json.loads(response.choices[0].message.content or "{}")

Yalnızca son message.content alanını ayrıştırın, ardından bunu uygulama kodunda yeniden doğrulayın.

Özel araçları çağırın

İlk yanıt bir veya daha fazla araç talep edebilir. İzin verilen her çağrıyı yürütün, asistan mesajının tamamını ekleyin, ardından her tool_call_id için bir eşleşen bir araç sonucu ekleyin.

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_build_status",
            "description": "Return the current build status for an allowed project.",
            "parameters": {
                "type": "object",
                "properties": {"project": {"type": "string"}},
                "required": ["project"],
                "additionalProperties": False,
            },
        },
    }
]

messages = [{"role": "user", "content": "Check the web build and summarize any failure."}]

first = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
    tool_choice="required",
)

assistant_message = first.choices[0].message
messages.append(assistant_message)

for call in assistant_message.tool_calls or []:
    arguments = json.loads(call.function.arguments)
    # Authorize and validate before executing a real tool.
    tool_result = {"project": arguments["project"], "status": "passed"}
    messages.append(
        {
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(tool_result),
        }
    )

final = client.chat.completions.create(
    model="kimi-k3",
    messages=messages,
    tools=tools,
)

İzin sınırı, giriş doğrulama, kapsamlı ortam ve denetim izi olmadan, model tarafından oluşturulan rastgele kabuk komutlarını asla çalıştırmayın.

Araçları dinamik olarak yükleyin

K3, kullanılabilir olduğu noktada bir system mesajına eksiksiz bir araç tanımının yerleştirilmesini destekler. Sunucu bu mesajı sizin için saklamadığından bu mesajı daha sonraki bir geçmişte saklayın.

Dinamik yükleme, büyük ajan sistemlerinin her turda her araç şemasını göndermekten kaçınmasına yardımcı olur. Aynı zamanda yeni durum yönetimi gereksinimleri de yaratır: Model, daha sonraki araç sonuçlarını yorumlarken tam beyanı görmelidir.

1M tokenlık bağlam penceresini kullanın

Geniş bağlamlar, uzak kanıtların birlikte gerekçelendirilmesi gerektiğinde en değerlidir. Bunları bilinçli olarak kullanın:

Başlangıçta sabit repository'leri veya belge derlemlerini tutun.
Öneki yeniden yazmak yerine soruları ve sonuçları ekleyin.
Önbelleğe alınmış ve önbelleğe alınmamış girişi ayrı ayrı izleyin.
Tüm derlemin gerekli olmadığı durumlarda daha küçük bir alt kümeyi alın.
Nihai yanıtın doğrulanabilmesi için kaynak tanımlayıcıları oluşturun.
Yalnızca istemciniz K3'ün gerektirdiği tüm durumu koruduğunda sıkıştırın.

Otomatik önbelleğe almanın önbellek kimliği veya sıradan TTL parametresi yoktur. Kararlı önekler, hizmete önbelleği vurmak için en iyi fırsatı verir.

Çok turlu durumun tamamını koruyun

Bu, K3'e özgü en önemli entegrasyon kuralıdır.

Bir konuşmaya devam ederken veya araç sonuçlarını döndürürken, API tarafından döndürülen asistan mesajının tamamını ekleyin. Yalnızca content alanını saklamayın. Moonshot, K3'ün korunmuş düşünme geçmişiyle eğitildiğini ve ajan çalışma sisteminin gerekli geçmişi bırakması veya seansın ortasında K3'e geçmesi durumunda kararsız hale gelebileceği konusunda uyarıyor.

Konuşma durumunu güvenli bir şekilde saklayın, saklama sınırları uygulayın ve gizli durumu görmemesi gereken kullanıcılara göstermekten kaçının.

Önemli Kimi K3 API sınırları

K3'te düşünme her zaman etkindir.
reasoning_effort, low, high ve max değerlerini destekler.
max_completion_tokens varsayılan olarak 131,072'ye ayarlanır ve 1,048,576'ya ayarlanabilir.
temperature=1.0, top_p=0.95, n=1, presence_penalty=0 ve frequency_penalty=0 sabittir; onları atla.
Genel resim URL'leri vizyon mesajları için desteklenmez.
Çoklu dönüş ve araç istekleri, asistan mesajının tamamını korumalıdır.
Moonshot, web arama aracının güncellendiğini ve şu anda üretim için önerilmediğini söylüyor.

Üretim kontrol listesi

API anahtarlarını sunucu tarafında tutun.
İstek zaman aşımları ve sınırlı yeniden denemeler ekleyin.
Araç argümanlarını doğrulayın ve her eylemi yetkilendirin.
Araç kullanım turlarını ve tamamlama uzunluğunu sınırlayın.
K3 asistanının tam durumunu koruyun.
Oluşturulduktan sonra JSON'u sıkı bir şekilde doğrulayın.
Girişi, önbelleğe alınmış girişi, çıkışı, gecikmeyi ve hataları kaydedin.
K3 oturumunun ortasında model değiştirmekten kaçının.
Aşırı proaktifliği azaltmak için açık davranışsal sınırlar ekleyin.
Kırık araçlarla, kısmi yanıtlarla ve uzun geçmişlerle test edin.

Bağlam ve çıktı sınırlarını seçmeden önce Kimi K3 API Fiyatlandırması bölümünü okuyun. Poyo.ai'nin kullanılabilirliği için Kimi K3 model sayfasını takip edin.

Sıkça sorulan sorular

Kimi K3 API OpenAI uyumlu mu?

Evet. Moonshot, OpenAI uyumlu bir Sohbet Tamamlama uç noktasını ortaya çıkarır. K3'e özgü durum, muhakeme, örnekleme ve medya kuralları hâlâ geçerlidir.

Kimi K3 model kimliği nedir?

Resmi Moonshot API model kimliği kimi-k3'dur.

Kimi K3 işlev çağrısını destekliyor mu?

Evet. Özel araçları, zorunlu araç seçimini, eşleşen araç sonuçlarını ve dinamik araç yüklemeyi destekler.

Kimi K3 videoyu işleyebilir mi?

Evet. Videoyu API Dosyaları aracılığıyla yükleyin ve bir video içeriği nesnesinde ms:// dosya kimliğine başvurun.

1M bağlam penceresini nasıl kullanırım?

Standart model isteği aracılığıyla gerekli mesajları ve içeriği gönderin, otomatik önbelleğe alma için kararlı önekleri değiştirmeden tutun ve sınırlı tamamlama sınırlarını ayarlayın.