Руководство по API Kimi K3.1 Pro и использованию в Agent
Kimi K3.1 Pro входит в семейство моделей K3.1 от Moonshot AI и предназначена для программирования, создания 3D-объектов, финансовых исследований и длительных сценариев с Agent. При вызове через официальный API используется ID модели kimi-k3.1-pro, а Base URL для OpenAI SDK — https://api.moonshot.cn/v1. Режим мышления всегда включён. Уровень рассуждений можно задать как low, high или max; по умолчанию используется max.Официальное краткое руководство
В этом руководстве на основе официальной документации описаны подключение, рассуждения, работа с изображениями и цикл вызова инструментов. Результаты бенчмарков опубликованы поставщиком и не являются тестами Guishu Intelligence.
Кратко
| Параметр | Проверенная информация |
|---|---|
| Официальный ID модели | kimi-k3.1-pro |
| Официальный API Base URL | https://api.moonshot.cn/v1 |
| Уровень рассуждений | low, high и max; по умолчанию: max |
| Режим мышления | Всегда включён |
| Контекст | В официальной документации заявлена поддержка 1 млн токенов |
| Высокоскоростная версия | kimi-k3.1-pro-highspeed — отдельная модель. Доступность и цену проверяйте в каталоге соответствующей платформы. |
| Дата проверки документации | 2026-10-24 |
Сведения о возможностях и моделях приведены по официальной документации Kimi K3.1 Pro. Версии моделей, условия доступа и стоимость могут меняться. Текущие доступные модели и цены на нашей платформе указаны на странице цен на модели.
Для каких задач подходит эта модель?
K3.1 Pro рассчитана на многоэтапную работу: понять требования, создать результат, проверить его и доработать с учётом обратной связи. Контекст на 1 млн токенов позволяет передать больше материалов, однако успех длительной задачи по-прежнему зависит от инструментов, среды и критериев приёмки. В официальном описании выделены программирование, 3D-творчество и финансовые исследования. Примеры ниже взяты из стороннего обзора и демонстраций поставщика — это не результаты наших запусков.
3D-камера: действительно ли конструкция меняется вместе с параметрами?
В статье «Отечественные модели сделали ещё один большой шаг вперёд: практическая проверка Kimi K3.1 Pro» Лю Сяопай попросил несколько моделей создать интерактивную камеру. По сообщению автора, K3.1 Pro сгенерировала 34 выбираемых компонента и диафрагму с девятью лепестками; 35 оптических показателей соответствовали проверкам автора. Во втором раунде при изменении фокусного расстояния с 50 mm на 85 mm изменилась и геометрия, а не только подпись.
У этого же примера были недостатки: единицы при экспорте не соответствовали требованиям, а между корпусом и диафрагмой оставались проблемы с зазорами. Для дизайн-задач полезнее проверять размеры, интерактивность, экспортированные файлы и последующие правки, а не только изображение рендера. Автор использовал разные среды инструментов для программирования, поэтому эти впечатления нельзя считать контролируемым сравнением моделей на равных условиях.
Игровая карта: создать инструмент, а затем поручить Agent им воспользоваться
Тот же автор создал браузерный редактор карт Terraria: размещение блоков должно было соответствовать правилам игры, а экспортированные карты — загружаться обратно в игру. Затем автор попросил K3.1 Pro построить сцену в созданном редакторе. Такая задача объединяет понимание формата файлов, разработку интерфейса и работу с инструментом — это ближе к реальному процессу, чем генерация демонстрационного фрагмента кода. По мнению автора, у Kimi и моделей для сравнения были разные сильные стороны в визуальной части; это личное наблюдение, а не универсальная оценка эстетики.
Финансовое исследование: проверяйте формулы и источники, а не только выводы
В материалах, представленных Зэнанем, Чжан Цянь и Panda из издания 机器之心 (Machine Heart), описаны финансовое моделирование, исследовательские отчёты и 3D-инженерные примеры. В официальной документации также показаны финансовая модель с изменяемыми бизнес-предпосылками и исследовательский отчёт со ссылками на источники. Практические критерии приёмки: пересчитываются ли формулы при изменении предпосылок, можно ли проверить исходные файлы для ключевых цифр и открывается ли каждый источник в отчёте. Демонстрация поставщика не гарантирует точность для произвольных финансовых задач.Официальное описание возможностей и примеры
На дату проверки документации для этой статьи поставщик планирует открыть полный набор весов до 4 ноября. Это план, а не объявление о выпуске. Наличие 3D-функций в официальном приложении также не означает, что в API встроен инструмент для 3D-моделирования.
Простой вызов API
В официальном примере используются Python 3.9+ и OpenAI SDK. Храните API-ключ в переменной окружения; не помещайте его в исходный код и не добавляйте в систему контроля версий.
python3 -m pip install --upgrade 'openai>=1.0'
export MOONSHOT_API_KEY="your-api-key"
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["MOONSHOT_API_KEY"],
base_url="https://api.moonshot.cn/v1",
)
result = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{"role": "user", "content": "Назовите три способа организовать надёжный процесс проверки кода."}],
reasoning_effort="high",
)
print(result.choices[0].message.content)
Для прямого подключения к Moonshot используйте выданный Moonshot ключ и указанный выше официальный Base URL. При работе через сторонний сервис, совместимый с OpenAI API, замените Base URL, ключ и модель на значения этого сервиса; не передавайте ему свои учётные данные Moonshot. Список моделей и условия оплаты Guishu Intelligence смотрите на странице цен на модели.
Как выбрать уровень рассуждений
K3.1 Pro всегда работает в режиме мышления. Параметр reasoning_effort задаёт глубину рассуждений, а не включает и выключает режим мышления. Официально доступны уровни low, high и max; значение по умолчанию — max.Описание уровней рассуждений
- Для коротких ответов на вопросы или преобразований с чёткой структурой сначала попробуйте
low. - Для многоэтапных изменений кода, анализа и планирования начните с
high. - Для сложных задач, требующих более глубоких рассуждений, сравните качество, задержку и фактическую стоимость при
max.
Это рекомендации по организации работы, а не гарантия производительности. В production оценивайте точность, задержку и стоимость на собственном наборе задач.
Диалоги в несколько ходов: сохраняйте полное сообщение assistant
Для многоходовых диалогов и возврата результатов инструментов официальное руководство рекомендует добавлять в следующий запрос полное сообщение assistant, полученное от API, а не сохранять только текстовое поле content. Структурированные поля, например вызовы инструментов, могут понадобиться на следующих этапах.Официальное описание многоходовых диалогов
messages = [{"role": "user", "content": "Сначала составь план миграции, затем опиши риски."}]
first = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=messages,
reasoning_effort="high",
)
messages.append(first.choices[0].message)
messages.append({"role": "user", "content": "Преобразуй раздел о рисках в контрольный список."})
second = client.chat.completions.create(model="kimi-k3.1-pro", messages=messages)
print(second.choices[0].message.content)
Если приложение сохраняет диалоги между запросами, храните поля сообщений, необходимые протоколу, и проверьте по официальной документации, как SDK сериализует объекты сообщений.
Вызовы инструментов и цикл Agent
Инструменты определяет и выполняет приложение: модель формирует вызов, приложение проверяет его аргументы и запускает нужную функцию, а затем возвращает результат модели. Не выполняйте вывод модели как доверенную команду.
import json
tools = [{
"type": "function",
"function": {
"name": "lookup_order",
"description": "Проверить статус заказа",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
messages = [{"role": "user", "content": "Проверьте статус заказа A-104"}]
response = client.chat.completions.create(
model="kimi-k3.1-pro", messages=messages, tools=tools
)
assistant = response.choices[0].message
messages.append(assistant) # Сохраняем полное сообщение assistant
for call in assistant.tool_calls or []:
args = json.loads(call.function.arguments)
# В реальном приложении перед вызовом контролируемой бизнес-функции
# проверьте аргументы и права пользователя.
tool_result = {"order_id": args["order_id"], "status": "processing"}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(tool_result),
})
final = client.chat.completions.create(
model="kimi-k3.1-pro", messages=messages, tools=tools
)
print(final.choices[0].message.content)
В официальном руководстве по вызову инструментов также указано, что результат каждого инструмента нужно возвращать с соответствующим tool_call_id, а полное сообщение assistant — сохранять для последующих ходов. За авторизацию, проверку аргументов, тайм-ауты, идемпотентность и аудит отвечает приложение.
Ввод изображений: используйте массив объектов
Согласно официальной документации, поле content в сообщении с изображением должно быть массивом объектов, а не сериализованной строкой. В примере изображение передаётся через Base64 Data URL. Также можно использовать ссылку на файл ms:// в рамках поддерживаемого процесса работы с файлами. Не рассчитывайте, что модель прочитает обычный публичный URL изображения.Официальное описание ввода изображений
import base64
from pathlib import Path
image_data = base64.b64encode(Path("diagram.png").read_bytes()).decode()
response = client.chat.completions.create(
model="kimi-k3.1-pro",
messages=[{
"role": "user",
"content": [
{"type": "image_url", "image_url": {
"url": f"data:image/png;base64,{image_data}"
}},
{"type": "text", "text": "Опишите компоненты системы и связи между ними на схеме."},
],
}],
)
print(response.choices[0].message.content)
Перед подключением проверьте поддерживаемые форматы изображений, ограничения размера и требования файлового API. Перед отправкой конфиденциальных изображений внешней модели убедитесь, что это допускают правила обработки данных вашей организации.
Как интерпретировать официальные бенчмарки и сторонний опыт
В документации Moonshot указана оценка K3.1 Pro в 65.7% на Terminal-Bench 4.0 и приведены сравнения с GPT-6 Astra и Claude Opus 5.5. Это опубликованные поставщиком результаты бенчмарка. Интерпретируйте их с учётом набора задач, конфигурации тестирования и даты публикации: они не предсказывают долю успешных решений для всех задач программирования.Официальное описание модели и бенчмарки
Автор Лю Сяопай поделился примерами интерактивного 3D-проекта камеры и собственными сравнениями моделей. Это сторонний опыт, а не тест Guishu Intelligence и не стандартизированное воспроизводимое сравнение моделей. Для оценки используйте собственную кодовую базу, проектные ограничения и примеры неудач, фиксируя запросы, инструменты, число повторов, задержку и стоимость.
Контрольный список подключения
- Уточните, вызываете ли вы официальный API напрямую или используете совместимый сервис, и укажите соответствующие ID модели, Base URL и ключ.
- Начните с более низкого уровня рассуждений и сравните качество, задержку и расходы на типичных задачах.
- В многоходовых диалогах и сценариях Agent сохраняйте полное сообщение assistant и связывайте результаты с правильными вызовами инструментов.
- Формируйте сообщения с изображениями как массив объектов; для локальных файлов используйте поддерживаемый способ кодирования или файловый процесс.
- Установите границы доступа, проверку аргументов, тайм-ауты и обработку ошибок для выполнения инструментов.
- Перед развёртыванием проверьте текущий каталог моделей, доступные регионы и цены, не полагаясь на старую конфигурацию.
Часто задаваемые вопросы
Какой API ID у модели Kimi K3.1 Pro?
В официальной документации указан ID kimi-k3.1-pro. Высокоскоростная версия называется kimi-k3.1-pro-highspeed; её следует настраивать как отдельную модель.
Какой уровень рассуждений используется по умолчанию?
В официальной документации перечислены low, high и max; по умолчанию используется max. Режим мышления всегда включён.
Можно ли передать URL изображения напрямую?
Нет. В официальной документации прямо указано, что публичные URL изображений не поддерживаются. Используйте массив объектов vision с Base64 Data URL либо ссылку ms:// через процесс работы с файлами.
Зачем Agent возвращать полное сообщение assistant?
Оно может содержать структурированные поля, например вызовы инструментов. Если сохранить только текст, потеряется информация для следующих взаимодействий. Результаты инструментов также нужно возвращать с соответствующим tool_call_id.
Доступна ли Kimi K3.1 Pro в Guishu Intelligence?
Актуальные доступные модели, маршрутизацию и цены проверяйте на странице цен на модели. Наличие возможностей в официальном API не означает, что модель или её высокоскоростная версия доступна на нашей платформе.
Дополнительные материалы
Дата проверки официальной документации: 2026-10-24. Возможности модели, параметры API и условия доступа могут меняться; сверяйтесь с документацией Moonshot Kimi API.