Kimi K3 API-guide: Python, bilder, verktøy og 1M kontekst

Utviklerguide til Kimi K3 API

Kimi K3 er tilgjengelig gjennom Moonshot AIs OpenAI-kompatible Chat Completions API med modell-ID-en kimi-k3. API-et støtter resonnering som alltid er på, strømming, bilder, opplastet video, streng JSON Schema, egendefinerte verktøy, dynamisk lasting av verktøy og et kontekstvindu på 1 million tokens.

Kompatibilitet betyr ikke identisk oppførsel. K3 har faste samplingverdier, krever fullstendig assistenttilstand i senere verktøy- og samtalerunder, og håndterer resonnering separat fra det endelige innholdet. Denne guiden konsentrerer seg om disse detaljene.

Tilgjengelighet og priser oppdatert 22. juli 2026. Kimi K3 er tilgjengelig på Poyo.ai som kimi-k3 gjennom det OpenAI-kompatible Chat Completions API-et. Prisen er $2.28 per 1M input-tokens og $11.40 per 1M output-tokens – 24 % lavere enn den offisielle prisen.

Krav

Du trenger:

Python 3.9 eller nyere;
Python-pakken openai i versjon 1.0 eller nyere;
en Moonshot API-nøkkel som oppbevares utenfor versjonskontrollen;
base-URL-en https://api.moonshot.ai/v1;
modell-ID-en kimi-k3.

Installer SDK-en:

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

Sett nøkkelen i skallet ditt:

export MOONSHOT_API_KEY="your-key"

I PowerShell:

$env:MOONSHOT_API_KEY="your-key"

Legg aldri en produksjonsnøkkel i et kodeeksempel, en klientbundle, en logg eller et repositorium.

Send din første forespørsel til Kimi K3

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

Still inn resonneringsinnsatsen

K3 bruker alltid tenkemodus. Du styrer innsatsen med feltet reasoning_effort på toppnivå:

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

Støttede verdier er:

Verdi	Bruk den til
`low`	Enklere oppgaver der ventetid og mengde utdata betyr noe
`high`	Krevende koding, analyse og verktøyplanlegging
`max`	De vanskeligste oppgavene og evaluering i benchmark-stil

Den dokumenterte standardverdien er max. Ikke anta at det er den billigste innstillingen i produksjon. Evaluer suksessrate, ventetid og antall genererte tokens for hvert innsatsnivå.

Strøm resonnering og endelig innhold

Strømmede svar leverer resonnering og endelig tekst gjennom ulike delta-felt.

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 innholdet som vises til brukeren, adskilt fra intern behandling. Ikke parse strukturerte utdata fra reasoning_content.

Send et bilde til Kimi K3

Bildemeldinger til K3 bruker en liste med innholdsobjekter. Offentlige bilde-URL-er støttes ikke i denne flyten; koder i stedet et lokalt bilde 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 opplastinger fra brukere. Unngå å logge base64-innhold.

Send en video til Kimi K3

Last opp videoen gjennom Files API, referer til ID-en du får tilbake med ms://-skjemaet, og slett filen når du ikke trenger den lenger.

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)

Returner utdata etter streng JSON Schema

Bruk strict: true når koden videre i kjeden trenger en forutsigbar 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 "{}")

Parse bare det endelige message.content, og valider det på nytt i applikasjonskoden.

Kall egendefinerte verktøy

Det første svaret kan be om ett eller flere verktøy. Utfør hvert tillatte kall, legg til hele assistentmeldingen, og legg deretter til ett tilhørende verktøyresultat for hver 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,
)

Kjør aldri vilkårlige skallkommandoer generert av modellen uten en tilgangsgrense, validering av inndata, et avgrenset miljø og et revisjonsspor.

Last inn verktøy dynamisk

K3 støtter at du legger en fullstendig verktøydefinisjon i en system-melding på det tidspunktet verktøyet blir tilgjengelig. Behold den meldingen i senere historikk, fordi serveren ikke tar vare på den for deg.

Dynamisk lasting gjør at store agentsystemer slipper å sende alle verktøyskjemaer i hver runde. Samtidig gir det nye krav til tilstandshåndtering: modellen må se den nøyaktige deklarasjonen når den tolker senere verktøyresultater.

Bruk kontekstvinduet på 1M tokens

Store kontekster er mest verdifulle når informasjon som ligger langt fra hverandre, må vurderes samlet. Bruk dem bevisst:

Legg stabile repositorier eller dokumentsamlinger i starten.
Legg til spørsmål og resultater i stedet for å skrive om prefikset.
Spor bufret og ikke-bufret input hver for seg.
Hent ut et mindre utvalg når hele samlingen ikke trengs.
Innfør kildeidentifikatorer slik at det endelige svaret kan etterprøves.
Komprimer bare når klienten din bevarer all tilstand som K3 krever.

Automatisk caching har ingen cache-ID eller vanlig TTL-parameter. Stabile prefikser gir tjenesten best mulighet til å treffe cachen.

Bevar fullstendig tilstand over flere runder

Dette er den viktigste integrasjonsregelen som er spesifikk for K3.

Når du fortsetter en samtale eller returnerer verktøyresultater, må du legge til hele assistentmeldingen som API-et returnerte. Ikke behold bare content. Moonshot advarer om at K3 ble trent med bevart tenkehistorikk og kan bli ustabil hvis rammeverket rundt dropper nødvendig historikk eller bytter til K3 midt i en sesjon.

Lagre samtaletilstanden sikkert, sett grenser for oppbevaring, og unngå å vise skjult tilstand til brukere som ikke skal se den.

Viktige grenser i Kimi K3 API

K3 har alltid tenkning aktivert.
reasoning_effort støtter low, high og max.
max_completion_tokens er 131 072 som standard og kan settes opp til 1 048 576.
temperature=1.0, top_p=0.95, n=1, presence_penalty=0 og frequency_penalty=0 er faste; utelat dem.
Offentlige bilde-URL-er støttes ikke i bildemeldinger.
Forespørsler over flere runder og med verktøy må bevare hele assistentmeldingen.
Moonshot sier at nettsøkverktøyet deres er under oppdatering og foreløpig ikke anbefales i produksjon.

Sjekkliste for produksjon

Hold API-nøkler på serversiden.
Legg inn tidsavbrudd for forespørsler og et begrenset antall nye forsøk.
Valider verktøyargumenter og autoriser hver handling.
Begrens antall verktøyrunder og lengden på svarene.
Bevar hele assistenttilstanden til K3.
Valider streng JSON etter generering.
Registrer input, bufret input, output, ventetid og feil.
Unngå å bytte modell midt i en K3-sesjon.
Legg inn eksplisitte atferdsgrenser for å redusere overdreven proaktivitet.
Test med ødelagte verktøy, ufullstendige svar og lange historikker.

Les Kimi K3 API-priser før du velger grenser for kontekst og utdata. Følg modellsiden for Kimi K3 for tilgjengelighet på Poyo.ai.

Ofte stilte spørsmål

Er Kimi K3 API kompatibelt med OpenAI?

Ja. Moonshot tilbyr et OpenAI-kompatibelt Chat Completions-endepunkt. K3-spesifikke regler for tilstand, resonnering, sampling og medier gjelder likevel.

Hva er modell-ID-en til Kimi K3?

Modell-ID-en i Moonshots offisielle API er kimi-k3.

Støtter Kimi K3 funksjonskall?

Ja. Den støtter egendefinerte verktøy, påkrevd verktøyvalg, tilhørende verktøyresultater og dynamisk lasting av verktøy.

Kan Kimi K3 behandle video?

Ja. Last opp videoen gjennom Files API og referer til ms://-fil-ID-en i et videoinnholdsobjekt.

Hvordan bruker jeg kontekstvinduet på 1M?

Send de nødvendige meldingene og innholdet gjennom den vanlige modellforespørselen, hold stabile prefikser uendret for automatisk caching, og sett begrensede grenser for svarlengden.