Kimi K3 API-guide: Python, billeder, værktøjer og 1M kontekst

Udviklerguide til Kimi K3 API

Kimi K3 er tilgængelig via Moonshot AI's OpenAI-kompatible Chat Completions API med model-ID'et kimi-k3. API'et understøtter altid-aktiv ræsonnering, streaming, billeder, uploadet video, streng JSON Schema, brugerdefinerede værktøjer, dynamisk indlæsning af værktøjer og et kontekstvindue på 1 million tokens.

Kompatibilitet betyder ikke identisk adfærd. K3 har faste samplingværdier, kræver den fulde assistenttilstand i senere værktøjs- og samtalerunder og håndterer ræsonnering adskilt fra det endelige indhold. Denne guide fokuserer på netop de detaljer.

Tilgængelighed og priser opdateret 22. juli 2026. Kimi K3 er tilgængelig på Poyo.ai som kimi-k3 via det OpenAI-kompatible Chat Completions API. Prisen er $2.28 pr. 1M input-tokens og $11.40 pr. 1M output-tokens — 24 % lavere end den officielle pris.

Forudsætninger

Du skal bruge:

Python 3.9 eller nyere;
Python-pakken openai i version 1.0 eller nyere;
en Moonshot API-nøgle, der opbevares uden for kildekodestyring;
basis-URL'en https://api.moonshot.ai/v1;
model-ID'et kimi-k3.

Installér SDK'et:

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

Sæt nøglen i din shell:

export MOONSHOT_API_KEY="your-key"

I PowerShell:

$env:MOONSHOT_API_KEY="your-key"

Læg aldrig en produktionsnøgle i et kodeeksempel, en klientbundle, en log eller et repository.

Send din første Kimi K3-anmodning

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

Indstil ræsonneringsindsats

K3 bruger altid tænketilstand. Indstil indsatsen via feltet reasoning_effort på øverste niveau:

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

De understøttede værdier er:

Værdi	Brug den til
`low`	Lettere opgaver, hvor svartid og outputmængde har betydning
`high`	Svær kodning, analyse og værktøjsplanlægning
`max`	De sværeste opgaver og evaluering i benchmark-stil

Standardværdien ifølge dokumentationen er max. Gå ikke ud fra, at den er den billigste indstilling i produktion. Evaluér succesrate, svartid og genererede tokens ved hvert niveau.

Stream ræsonnering og endeligt indhold

Streamede svar udstiller ræsonnering og endelig tekst i forskellige delta-felter.

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)

Hold det endelige indhold, som brugeren ser, adskilt fra intern behandling. Parsér ikke struktureret output fra reasoning_content.

Send et billede til Kimi K3

K3's vision-beskeder bruger et array af indholdsobjekter. Offentlige billed-URL'er understøttes ikke i dette flow; kodér et lokalt billede som 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.",
                },
            ],
        }
    ],
)

Valider filtype og størrelse, før du koder brugeres uploads. Undgå at logge base64-payloads.

Send en video til Kimi K3

Upload video via Files API'et, henvis til det returnerede ID med skemaet ms://, og slet filen, når du ikke længere har brug for den.

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)

Returnér strengt JSON Schema-output

Brug strict: true, når den efterfølgende kode har brug for en forudsigelig struktur.

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

Parsér kun det endelige message.content, og valider det derefter igen i applikationskoden.

Kald brugerdefinerede værktøjer

Det første svar kan anmode om et eller flere værktøjer. Udfør hvert tilladt kald, tilføj den fulde assistentbesked, og tilføj derefter ét matchende værktøjsresultat for hvert tool_call_id.

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

Udfør aldrig vilkårlige shell-kommandoer, som modellen har genereret, uden en tilladelsesgrænse, inputvalidering, et afgrænset miljø og et revisionsspor.

Indlæs værktøjer dynamisk

K3 understøtter, at du placerer en komplet værktøjsdefinition i en system-besked på det tidspunkt, hvor værktøjet bliver tilgængeligt. Behold den besked i den senere historik, fordi serveren ikke gemmer den for dig.

Dynamisk indlæsning hjælper store agentsystemer med at undgå at sende hvert eneste værktøjsskema i hver runde. Det stiller også nye krav til tilstandshåndtering: Modellen skal se den præcise deklaration, når den fortolker senere værktøjsresultater.

Brug kontekstvinduet på 1M tokens

Store kontekster er mest værdifulde, når fjerntliggende beviser skal ræsonneres over samlet. Brug dem bevidst:

Placér stabile repositories eller dokumentsamlinger først.
Tilføj spørgsmål og resultater i stedet for at omskrive præfikset.
Følg cachet og ikke-cachet input hver for sig.
Hent en mindre delmængde, når hele samlingen ikke er nødvendig.
Opret kildeidentifikatorer, så det endelige svar kan verificeres.
Komprimér kun, når din klient bevarer al den tilstand, K3 kræver.

Automatisk caching har intet cache-ID og ingen almindelig TTL-parameter. Stabile præfikser giver tjenesten størst chance for at ramme cachen.

Bevar den fulde tilstand på tværs af flere runder

Dette er den vigtigste K3-specifikke integrationsregel.

Når du fortsætter en samtale eller returnerer værktøjsresultater, skal du tilføje den fulde assistentbesked, som API'et returnerede. Behold ikke kun content. Moonshot advarer om, at K3 er trænet med bevaret tænkehistorik og kan blive ustabil, hvis din harness dropper påkrævet historik eller skifter til K3 midt i en session.

Gem samtaletilstand sikkert, anvend opbevaringsgrænser, og undgå at vise skjult tilstand til brugere, som ikke skal se den.

Vigtige begrænsninger i Kimi K3 API

K3 har altid tænkning aktiveret.
reasoning_effort understøtter low, high og max.
max_completion_tokens er som standard 131.072 og kan sættes op til 1.048.576.
temperature=1.0, top_p=0.95, n=1, presence_penalty=0 og frequency_penalty=0 er faste; udelad dem.
Offentlige billed-URL'er understøttes ikke i vision-beskeder.
Anmodninger med flere runder og værktøjer skal bevare den fulde assistentbesked.
Moonshot oplyser, at deres websøgningsværktøj er under opdatering og i øjeblikket ikke anbefales til produktion.

Tjekliste til produktion

Hold API-nøgler på serversiden.
Tilføj timeouts på anmodninger og begrænsede genforsøg.
Valider værktøjsargumenter, og autorisér hver handling.
Begræns antallet af værktøjsrunder og længden af svar.
Bevar den fulde K3-assistenttilstand.
Valider strengt JSON efter generering.
Registrér input, cachet input, output, svartid og fejl.
Undgå at skifte model midt i en K3-session.
Tilføj eksplicitte adfærdsgrænser for at dæmpe overdreven proaktivitet.
Test med defekte værktøjer, delvise svar og lange historikker.

Læs Kimi K3 API-priser, før du vælger grænser for kontekst og output. Følg modelsiden for Kimi K3 for tilgængelighed på Poyo.ai.

Ofte stillede spørgsmål

Er Kimi K3 API OpenAI-kompatibelt?

Ja. Moonshot udstiller et OpenAI-kompatibelt Chat Completions-endpoint. Reglerne for K3-specifik tilstand, ræsonnering, sampling og medier gælder stadig.

Hvad er model-ID'et for Kimi K3?

Det officielle model-ID i Moonshot API er kimi-k3.

Understøtter Kimi K3 function calling?

Ja. Den understøtter brugerdefinerede værktøjer, påkrævet værktøjsvalg, matchende værktøjsresultater og dynamisk indlæsning af værktøjer.

Kan Kimi K3 behandle video?

Ja. Upload videoen via Files API'et, og henvis til dens fil-ID med ms:// i et videoindholdsobjekt.

Hvordan bruger jeg kontekstvinduet på 1M?

Send de nødvendige beskeder og det nødvendige indhold via den almindelige modelanmodning, lad stabile præfikser stå uændrede for automatisk caching, og sæt begrænsede grænser for svarlængden.