Kimi K3 API-gids: Python, vision, tools en 1M context

Ontwikkelaarsgids voor de Kimi K3 API

Kimi K3 is beschikbaar via de OpenAI-compatibele Chat Completions API van Moonshot AI, onder de model-ID kimi-k3. De API ondersteunt altijd actief redeneren, streaming, afbeeldingen, geüploade video, strikt JSON Schema, eigen tools, dynamisch laden van tools en een contextvenster van 1 miljoen tokens.

Compatibel betekent niet dat het zich identiek gedraagt. K3 heeft vaste samplingwaarden, vereist de volledige assistentstatus in latere tool- en gespreksbeurten en behandelt redeneren los van de uiteindelijke content. Deze gids richt zich op die details.

Beschikbaarheid en prijzen bijgewerkt op 22 juli 2026. Kimi K3 is beschikbaar op Poyo.ai als kimi-k3 via de OpenAI-compatibele Chat Completions API. De prijs is $2.28 per 1M input-tokens en $11.40 per 1M output-tokens, 24% lager dan de officiële prijs.

Vereisten

Je hebt nodig:

Python 3.9 of nieuwer;
het Python-pakket openai vanaf versie 1.0;
een Moonshot API-sleutel die buiten je versiebeheer wordt bewaard;
de basis-URL https://api.moonshot.ai/v1;
model-ID kimi-k3.

Installeer de SDK:

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

Stel de sleutel in je shell in:

export MOONSHOT_API_KEY="your-key"

In PowerShell:

$env:MOONSHOT_API_KEY="your-key"

Zet nooit een productiesleutel in een codevoorbeeld, een client-side bundle, een log of een repository.

Je eerste Kimi K3-verzoek doen

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

Redeninspanning instellen

K3 gebruikt altijd de denkmodus. Stel de inspanning in via het reasoning_effort-veld op het hoogste niveau:

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

Ondersteunde waarden zijn:

Waarde	Gebruik het voor
`low`	Eenvoudigere taken waarbij latentie en output ertoe doen
`high`	Lastige codeer-, analyse- en toolplanningstaken
`max`	De moeilijkste taken en evaluaties in benchmarkstijl

De gedocumenteerde standaardwaarde is max. Ga er niet vanuit dat dit de goedkoopste instelling voor productie is. Beoordeel bij elk niveau het slagingspercentage, de latentie en het aantal gegenereerde tokens.

Redeneren en uiteindelijke content streamen

Streamingantwoorden leveren redeneren en eindtekst via verschillende delta-velden.

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)

Houd de uiteindelijke content voor gebruikers gescheiden van interne verwerking. Parseer gestructureerde output niet uit reasoning_content.

Een afbeelding naar Kimi K3 sturen

K3-vision-berichten gebruiken een array van contentobjecten. Openbare afbeeldings-URL's worden in deze flow niet ondersteund; codeer een lokale afbeelding als base64.

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.",
                },
            ],
        }
    ],
)

Controleer bestandstype en -grootte voordat je uploads van gebruikers codeert. Log geen base64-payloads.

Een video naar Kimi K3 sturen

Upload video via de Files API, verwijs met het schema ms:// naar de teruggegeven ID en verwijder het bestand zodra je het niet meer nodig hebt.

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)

Strikte JSON Schema-output teruggeven

Gebruik strict: true als code verderop in de keten een voorspelbare structuur nodig heeft.

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 "{}")

Parseer alleen de uiteindelijke message.content en valideer die daarna opnieuw in je applicatiecode.

Eigen tools aanroepen

Het eerste antwoord kan om een of meer tools vragen. Voer elke toegestane aanroep uit, voeg het volledige assistentbericht toe en voeg daarna voor elke tool_call_id één bijbehorend toolresultaat toe.

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,
)

Voer nooit willekeurige, door het model gegenereerde shellcommando's uit zonder een rechtengrens, invoervalidatie, een afgeschermde omgeving en een auditspoor.

Tools dynamisch laden

K3 ondersteunt het plaatsen van een volledige tooldefinitie in een system-bericht op het moment dat de tool beschikbaar komt. Houd dat bericht in de latere geschiedenis, want de server bewaart het niet voor je.

Dynamisch laden helpt grote agentsystemen om niet bij elke beurt alle toolschema's mee te sturen. Het brengt ook nieuwe eisen voor statusbeheer met zich mee: het model moet de exacte declaratie zien om latere toolresultaten te kunnen interpreteren.

Het contextvenster van 1M tokens gebruiken

Grote contexten zijn het waardevolst als bewijs dat ver uit elkaar ligt gezamenlijk moet worden doorgrond. Gebruik ze doordacht:

Zet stabiele repositories of documentcorpora aan het begin.
Voeg vragen en resultaten toe in plaats van het voorvoegsel te herschrijven.
Houd gecachete en niet-gecachete input apart bij.
Haal een kleinere subset op als het volledige corpus niet nodig is.
Leg bronidentificatoren vast, zodat het uiteindelijke antwoord te controleren is.
Comprimeer alleen als je client alle status behoudt die K3 nodig heeft.

Automatische caching kent geen cache-ID en geen gewone TTL-parameter. Stabiele voorvoegsels geven de dienst de beste kans op een cachetreffer.

De volledige status over meerdere beurten behouden

Dit is de belangrijkste K3-specifieke integratieregel.

Voeg bij het voortzetten van een gesprek of het teruggeven van toolresultaten het volledige assistentbericht toe dat de API teruggaf. Bewaar niet alleen content. Moonshot waarschuwt dat K3 is getraind met behouden denkgeschiedenis en instabiel kan worden als de harness vereiste geschiedenis weglaat of halverwege een sessie naar K3 overstapt.

Sla gespreksstatus veilig op, hanteer bewaartermijnen en laat verborgen status niet zien aan gebruikers die die niet mogen zien.

Belangrijke limieten van de Kimi K3 API

K3 heeft altijd denken ingeschakeld.
reasoning_effort ondersteunt low, high en max.
max_completion_tokens staat standaard op 131.072 en kan tot 1.048.576 worden ingesteld.
temperature=1.0, top_p=0.95, n=1, presence_penalty=0 en frequency_penalty=0 liggen vast; laat ze weg.
Openbare afbeeldings-URL's worden niet ondersteund voor vision-berichten.
Verzoeken met meerdere beurten en toolverzoeken moeten het volledige assistentbericht behouden.
Moonshot meldt dat de websearch-tool wordt bijgewerkt en op dit moment niet wordt aanbevolen voor productie.

Checklist voor productie

Houd API-sleutels aan de serverkant.
Voeg time-outs voor verzoeken en begrensde retries toe.
Valideer toolargumenten en autoriseer elke actie.
Beperk het aantal toolbeurten en de lengte van de completion.
Behoud de volledige K3-assistentstatus.
Valideer strikte JSON na het genereren.
Registreer input, gecachete input, output, latentie en fouten.
Wissel niet van model halverwege een K3-sessie.
Voeg expliciete gedragsgrenzen toe om overmatige proactiviteit te beperken.
Test met kapotte tools, gedeeltelijke antwoorden en lange geschiedenissen.

Lees Kimi K3 API-prijzen voordat je limieten voor context en output kiest. Volg de Kimi K3-modelpagina voor de beschikbaarheid op Poyo.ai.

Veelgestelde vragen

Is de Kimi K3 API OpenAI-compatibel?

Ja. Moonshot biedt een OpenAI-compatibel Chat Completions-endpoint aan. De K3-specifieke regels voor status, redeneren, sampling en media blijven gelden.

Wat is de model-ID van Kimi K3?

De officiële model-ID in de Moonshot API is kimi-k3.

Ondersteunt Kimi K3 function calling?

Ja. Het ondersteunt eigen tools, verplichte toolkeuze, bijpassende toolresultaten en dynamisch laden van tools.

Kan Kimi K3 video verwerken?

Ja. Upload de video via de Files API en verwijs in een video-contentobject naar de bestands-ID met ms://.

Hoe gebruik ik het contextvenster van 1M?

Stuur de benodigde berichten en content via het standaardmodelverzoek, laat stabiele voorvoegsels ongewijzigd voor automatische caching en stel begrensde completion-limieten in.