Przewodnik po API Kimi K3: Python, wizja, narzędzia i kontekst 1M

Przewodnik programisty po API Kimi K3

Kimi K3 jest dostępny przez zgodne z OpenAI API Chat Completions od Moonshot AI, pod identyfikatorem modelu kimi-k3. API obsługuje stale włączone rozumowanie, streaming, obrazy, przesyłane wideo, ścisły JSON Schema, własne narzędzia, dynamiczne ładowanie narzędzi i okno kontekstu o długości miliona tokenów.

Zgodność nie oznacza identycznego zachowania. K3 ma stałe wartości próbkowania, wymaga kompletnego stanu asystenta w kolejnych turach z narzędziami i rozmową oraz osobno obsługuje rozumowanie i treść końcową. Ten przewodnik skupia się właśnie na tych szczegółach.

Dostępność i ceny zaktualizowane 22 lipca 2026. Kimi K3 jest dostępny w Poyo.ai jako kimi-k3 przez zgodne z OpenAI API Chat Completions. Cena to $2.28 za 1M tokenów wejściowych i $11.40 za 1M tokenów wyjściowych, czyli o 24% mniej niż w oficjalnym cenniku.

Wymagania

Potrzebujesz:

Pythona 3.9 lub nowszego;
pakietu Pythona openai w wersji 1.0 lub nowszej;
klucza API Moonshot przechowywanego poza kontrolą wersji;
bazowego adresu URL https://api.moonshot.ai/v1;
identyfikatora modelu kimi-k3.

Zainstaluj SDK:

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

Ustaw klucz w swojej powłoce:

export MOONSHOT_API_KEY="your-key"

W PowerShellu:

$env:MOONSHOT_API_KEY="your-key"

Nigdy nie umieszczaj produkcyjnego klucza w przykładzie kodu, paczce po stronie klienta, logu ani repozytorium.

Wyślij pierwsze żądanie do 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."}
    ]
  }'

Skonfiguruj poziom wysiłku rozumowania

K3 zawsze używa trybu myślenia. Jego poziom wysiłku ustawisz w polu najwyższego poziomu reasoning_effort:

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

Obsługiwane wartości:

Wartość	Do czego jej użyć
`low`	Łatwiejsze zadania, w których liczą się opóźnienie i długość wyniku
`high`	Trudne kodowanie, analiza i planowanie użycia narzędzi
`max`	Najtrudniejsze zadania i ewaluacja w stylu benchmarków

Udokumentowana wartość domyślna to max. Nie zakładaj, że to najtańsze ustawienie produkcyjne. Oceń odsetek sukcesów, opóźnienie i liczbę wygenerowanych tokenów na każdym poziomie wysiłku.

Strumieniuj rozumowanie i treść końcową

W odpowiedziach strumieniowych rozumowanie i tekst końcowy trafiają do różnych pól delta.

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)

Oddziel treść końcową pokazywaną użytkownikowi od przetwarzania wewnętrznego. Nie parsuj ustrukturyzowanego wyjścia z reasoning_content.

Wyślij obraz do Kimi K3

Wiadomości wizyjne K3 używają tablicy obiektów treści. Publiczne adresy URL obrazów nie są w tym trybie obsługiwane; zakoduj lokalny obraz w 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.",
                },
            ],
        }
    ],
)

Przed zakodowaniem plików przesłanych przez użytkowników sprawdź ich typ i rozmiar. Nie zapisuj w logach danych base64.

Wyślij wideo do Kimi K3

Prześlij wideo przez Files API, odwołaj się do zwróconego ID za pomocą schematu ms:// i usuń plik, gdy nie będzie już potrzebny.

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)

Zwracaj wyniki zgodne ze ścisłym JSON Schema

Użyj strict: true, gdy kod dalej w łańcuchu potrzebuje przewidywalnej struktury.

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

Parsuj wyłącznie końcowe message.content, a potem zweryfikuj je jeszcze raz w kodzie aplikacji.

Wywołuj własne narzędzia

Pierwsza odpowiedź może zażądać jednego lub kilku narzędzi. Wykonaj każde dozwolone wywołanie, dołącz kompletną wiadomość asystenta, a następnie dołącz po jednym pasującym wyniku narzędzia dla każdego 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,
)

Nigdy nie wykonuj dowolnych poleceń powłoki wygenerowanych przez model bez granicy uprawnień, walidacji danych wejściowych, ograniczonego środowiska i śladu audytowego.

Ładuj narzędzia dynamicznie

K3 pozwala umieścić kompletną definicję narzędzia w wiadomości system w miejscu, w którym narzędzie staje się dostępne. Zachowaj tę wiadomość w dalszej historii, bo serwer nie przechowuje jej za ciebie.

Dynamiczne ładowanie pomaga dużym systemom agentowym uniknąć wysyłania schematu każdego narzędzia w każdej turze. Wprowadza też nowe wymagania dotyczące zarządzania stanem: model musi widzieć dokładną deklarację, gdy interpretuje późniejsze wyniki narzędzi.

Wykorzystaj okno kontekstu 1M tokenów

Duże konteksty są najcenniejsze, gdy trzeba łącznie wnioskować na podstawie odległych od siebie dowodów. Używaj ich świadomie:

Trzymaj stabilne repozytoria lub korpusy dokumentów na początku.
Dołączaj pytania i wyniki zamiast przepisywać prefiks.
Śledź osobno wejście z cache i bez cache.
Pobieraj mniejszy podzbiór, gdy pełny korpus nie jest potrzebny.
Ustal identyfikatory źródeł, aby odpowiedź końcową dało się zweryfikować.
Kompaktuj kontekst tylko wtedy, gdy twój klient zachowuje cały stan wymagany przez K3.

Automatyczne cache'owanie nie ma ID cache ani zwykłego parametru TTL. Stabilne prefiksy dają usłudze największą szansę na trafienie w cache.

Zachowaj kompletny stan wielu tur

To najważniejsza zasada integracji specyficzna dla K3.

Przy kontynuowaniu rozmowy lub zwracaniu wyników narzędzi dołączaj kompletną wiadomość asystenta zwróconą przez API. Nie zachowuj samego content. Moonshot ostrzega, że K3 był trenowany z zachowaną historią myślenia i może działać niestabilnie, jeśli harness pominie wymaganą historię albo przełączy się na K3 w połowie sesji.

Przechowuj stan rozmowy w bezpieczny sposób, stosuj limity retencji i nie ujawniaj ukrytego stanu użytkownikom, którzy nie powinni go widzieć.

Ważne limity API Kimi K3

K3 ma zawsze włączone myślenie.
reasoning_effort obsługuje wartości low, high i max.
max_completion_tokens domyślnie wynosi 131 072 i można go ustawić do 1 048 576.
Wartości temperature=1.0, top_p=0.95, n=1, presence_penalty=0 i frequency_penalty=0 są stałe; pomiń je.
Publiczne adresy URL obrazów nie są obsługiwane w wiadomościach wizyjnych.
Żądania wielotur i z narzędziami muszą zachować kompletną wiadomość asystenta.
Moonshot informuje, że jego narzędzie do wyszukiwania w sieci jest aktualizowane i obecnie nie jest zalecane do produkcji.

Lista kontrolna przed produkcją

Trzymaj klucze API po stronie serwera.
Dodaj limity czasu żądań i ograniczoną liczbę ponownych prób.
Waliduj argumenty narzędzi i autoryzuj każde działanie.
Ogranicz liczbę tur z narzędziami i długość odpowiedzi.
Zachowuj kompletny stan asystenta K3.
Waliduj ścisły JSON po wygenerowaniu.
Zapisuj wejście, wejście z cache, wyjście, opóźnienie i błędy.
Unikaj przełączania modeli w środku sesji K3.
Dodaj jawne granice zachowania, aby ograniczyć nadmierną proaktywność.
Testuj z uszkodzonymi narzędziami, częściowymi odpowiedziami i długimi historiami.

Przeczytaj cennik API Kimi K3, zanim wybierzesz limity kontekstu i wyjścia. Dostępność w Poyo.ai śledź na stronie modelu Kimi K3.

Najczęstsze pytania

Czy API Kimi K3 jest zgodne z OpenAI?

Tak. Moonshot udostępnia zgodny z OpenAI endpoint Chat Completions. Nadal obowiązują jednak zasady specyficzne dla K3 dotyczące stanu, rozumowania, próbkowania i multimediów.

Jaki jest identyfikator modelu Kimi K3?

Oficjalny identyfikator modelu w API Moonshot to kimi-k3.

Czy Kimi K3 obsługuje function calling?

Tak. Obsługuje własne narzędzia, wymuszony wybór narzędzia, pasujące wyniki narzędzi i dynamiczne ładowanie narzędzi.

Czy Kimi K3 potrafi przetwarzać wideo?

Tak. Prześlij wideo przez Files API i odwołaj się do jego ID pliku ms:// w obiekcie treści typu wideo.

Jak korzystać z okna kontekstu 1M?

Wyślij potrzebne wiadomości i treści w standardowym żądaniu do modelu, nie zmieniaj stabilnych prefiksów, by działało automatyczne cache'owanie, i ustaw ograniczone limity długości odpowiedzi.