Руководство по Kimi K3 API: Python, Vision, инструменты и контекст на 1 млн токенов

Руководство разработчика Kimi K3 API

Kimi K3 доступен через OpenAI-совместимый API Chat Completions от Moonshot AI с идентификатором модели kimi-k3. API поддерживает постоянно включённый режим рассуждений, потоковую передачу данных, изображения, загруженное видео, строгую JSON Schema, пользовательские инструменты, динамическую загрузку инструментов и контекстное окно размером 1 миллион токенов.

Совместимость не означает полностью одинаковое поведение. K3 использует фиксированные значения параметров сэмплирования, требует сохранения полного состояния ассистента в последующих ходах с инструментами и диалогах, а также отделяет процесс рассуждения от финального содержимого ответа. Это руководство посвящено именно этим особенностям.

Доступность и цены обновлены 22 июля 2026 года. Kimi K3 доступна в Poyo.ai как kimi-k3 через совместимый с OpenAI Chat Completions API. Цена составляет $2.28 за 1 млн входных токенов и $11.40 за 1 млн выходных токенов — на 24% ниже официальной цены.

Требования

Вам понадобятся:

Python 3.9 или новее;
Python-пакет openai версии 1.0 или новее;
API-ключ Moonshot, хранящийся вне системы контроля версий;
базовый URL https://api.moonshot.ai/v1;
идентификатор модели kimi-k3.

Установите SDK:

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

Установите ключ в вашей оболочке:

export MOONSHOT_API_KEY="your-key"

В PowerShell:

$env:MOONSHOT_API_KEY="your-key"

Никогда не размещайте рабочий ключ в примерах кода, клиентских сборках, логах или репозиториях.

Выполните первый запрос к 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."}
    ]
  }'

Настройка уровня рассуждений

K3 всегда использует режим размышления. Настройте его интенсивность через поле верхнего уровня 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."}
    ],
)

Поддерживаемые значения:

Значение	Используйте для
`low`	Более простые задачи, где важны скорость и объём вывода
`high`	Сложное программирование, анализ и планирование использования инструментов
`max`	Самые сложные задачи и оценка в стиле бенчмарков

Документированное значение по умолчанию — max. Не следует считать его самым дешёвым вариантом для продакшена. Оценивайте процент успешных результатов, задержку и количество сгенерированных токенов для каждого уровня.

Потоковая передача рассуждений и финального содержимого

Потоковые ответы передают рассуждения и итоговый текст через разные поля 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)

Отделяйте финальный пользовательский контент от внутренней обработки. Не извлекайте структурированный вывод из reasoning_content.

Отправка изображения в Kimi K3

Сообщения с поддержкой Vision в K3 используют массив объектов содержимого. В этом сценарии публичные URL изображений не поддерживаются; локальное изображение необходимо закодировать в 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.",
                },
            ],
        }
    ],
)

Проверяйте тип и размер файла перед кодированием пользовательских загрузок. Не записывайте в логи base64-полезные нагрузки.

Отправка видео в Kimi K3

Загрузите видео через Files API, используйте возвращённый ID с форматом ms:// и удалите файл, когда он больше не нужен.

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)

Возврат строгого вывода JSON Schema

Используйте strict: true, если последующему коду требуется предсказуемая структура данных.

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

Разбирайте только финальное message.content, затем повторно проверяйте его в коде приложения.

Вызов пользовательских инструментов

Первый ответ может запросить один или несколько инструментов. Выполните каждый разрешённый вызов, добавьте полное сообщение ассистента, затем добавьте один соответствующий результат инструмента для каждого 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,
)

Никогда не выполняйте произвольные команды оболочки, сгенерированные моделью, без ограничений прав доступа, проверки входных данных, изолированной среды и журнала аудита.

Динамическая загрузка инструментов

K3 поддерживает размещение полного определения инструмента в сообщении system в момент, когда инструмент становится доступным. Сохраняйте это сообщение в последующей истории, поскольку сервер не хранит его за вас.

Динамическая загрузка помогает большим агентным системам не отправлять схему каждого инструмента при каждом запросе. Однако она создаёт новые требования к управлению состоянием: модель должна видеть точное объявление при интерпретации последующих результатов инструментов.

Использование контекстного окна на 1 млн токенов

Большие контексты особенно ценны, когда необходимо совместно анализировать данные, находящиеся далеко друг от друга. Используйте их осознанно:

Размещайте стабильные репозитории или коллекции документов в начале.
Добавляйте вопросы и результаты вместо переписывания префикса.
Отслеживайте кэшированные и некэшированные входные данные отдельно.
Извлекайте меньший набор данных, когда полный корпус не нужен.
Используйте идентификаторы источников, чтобы финальный ответ можно было проверить.
Выполняйте сокращение контекста только если ваш клиент сохраняет всё состояние, необходимое K3.

Автоматическое кэширование не имеет параметра cache ID или обычного TTL. Стабильные префиксы дают сервису наилучшую возможность использовать кэш.

Сохранение полного состояния многошагового диалога

Это самое важное правило интеграции, специфичное для K3.

При продолжении диалога или возврате результатов инструментов добавляйте полное сообщение ассистента, полученное от API. Не сохраняйте только content. Moonshot предупреждает, что K3 обучалась с сохранением истории размышлений и может работать нестабильно, если система удаляет необходимую историю или переключается на K3 в середине сессии.

Храните состояние диалогов безопасно, применяйте ограничения хранения и не раскрывайте скрытое состояние пользователям, которым оно недоступно.

Важные ограничения Kimi K3 API

K3 всегда работает с включённым режимом размышления.
reasoning_effort поддерживает low, high и max.
max_completion_tokens по умолчанию равен 131,072 и может быть установлен до 1,048,576.
temperature=1.0, top_p=0.95, n=1, presence_penalty=0 и frequency_penalty=0 являются фиксированными; не указывайте их.
Публичные URL изображений не поддерживаются для сообщений Vision.
Многошаговые запросы и запросы с инструментами должны сохранять полное сообщение ассистента.
Moonshot сообщает, что его инструмент веб-поиска обновляется и в настоящее время не рекомендуется для продакшена.

Чек-лист для продакшена

Храните API-ключи только на серверной стороне.
Добавьте таймауты запросов и ограниченные повторы.
Проверяйте аргументы инструментов и авторизуйте каждое действие.
Ограничивайте количество ходов инструментов и длину ответа.
Сохраняйте полное состояние ассистента K3.
Проверяйте строгий JSON после генерации.
Записывайте входные данные, кэшированный ввод, вывод, задержку и ошибки.
Не переключайте модели в середине сессии K3.
Добавляйте явные поведенческие ограничения для снижения чрезмерной инициативности.
Тестируйте работу с неработающими инструментами, частичными ответами и длинными историями.

Прочитайте цены Kimi K3 API, прежде чем выбирать ограничения контекста и вывода. Следите за страницей модели Kimi K3, чтобы узнать о доступности на Poyo.ai.

Часто задаваемые вопросы

Совместим ли Kimi K3 API с OpenAI?

Да. Moonshot предоставляет OpenAI-совместимый endpoint Chat Completions. При этом для K3 действуют собственные правила состояния, рассуждений, сэмплирования и работы с медиа.

Какой идентификатор модели Kimi K3?

Официальный идентификатор модели в API Moonshot — kimi-k3.

Поддерживает ли Kimi K3 вызов функций?

Да. Поддерживаются пользовательские инструменты, обязательный выбор инструментов, соответствующие результаты инструментов и динамическая загрузка инструментов.

Может ли Kimi K3 обрабатывать видео?

Да. Загрузите видео через Files API и укажите его ID файла ms:// в объекте содержимого видео.

Как использовать контекстное окно на 1 млн токенов?

Передавайте необходимые сообщения и содержимое через стандартный запрос модели, сохраняйте неизменными стабильные префиксы для автоматического кэширования и устанавливайте ограниченные лимиты завершения.