Kimi K3.1 Pro API 接入与 Agent 使用指南

Kimi K3.1 Pro 是 Moonshot AI 的 K3.1 系列模型，面向代码、3D 创作、金融研究和长程 Agent 工作。通过官方 API 调用时，模型 ID 为 kimi-k3.1-pro，OpenAI SDK 的 Base URL 为 https://api.moonshot.cn/v1。模型始终启用思考模式，推理强度可设为 low、high 或 max，默认 max。官方快速开始

本文按官方接口说明介绍接入、推理、视觉和工具循环。厂商公布的基准结果属于厂商评测；下文不将其表述为贵数智能实测。

核心信息

项目	已核实信息
官方模型 ID	kimi-k3.1-pro
官方 API Base URL	https://api.moonshot.cn/v1
推理强度	low、high、max；默认 max
思考模式	始终开启
上下文	官方文档称支持 100 万 token
高速型号	kimi-k3.1-pro-highspeed；为独立型号，是否可用及价格需查对应平台目录
文档核验日期	2026-10-24

以上能力和型号信息以官方 Kimi K3.1 Pro 文档为准。模型版本、访问资格和费用可能变化；本站具体可用模型与价格请查看模型价格。

这次升级适合拿来做什么？

K3.1 Pro 的看点是多步骤工作：读取要求、生成工程、检查结果，再根据反馈修改。百万 token 上下文可容纳更多材料，但长任务是否成功还取决于工具、环境和验收条件。官方介绍重点覆盖代码、3D 创作和金融研究；以下案例分别来自第三方体验与厂商展示，不是本站运行结果。

3D 相机：看结构是否真的随参数变化

刘小排在《国产模型又往前走了一大步：Kimi K3.1 Pro 实测》中，让多个模型制作可交互的相机模型。他报告 K3.1 Pro 生成了 34 个可选择部件和 9 片光圈叶片，35 项光学读数符合其检查要求；第二轮把镜头从 50mm 改成 85mm 时，模型也改变了几何结构，而不是只换标签。

同一案例仍有缺陷：导出单位未按要求处理，机身框架与光圈间隙也存在问题。对设计任务，更有用的验收方式是同时检查尺寸、交互、导出文件和二次修改，而不只看一张渲染图。作者使用了不同的编程工具环境，这些体验不能当成控制变量一致的模型排名。

游戏地图：生成工具，再让 Agent 使用它

同一作者还制作了浏览器中的 Terraria 地图编辑器，要求方块放置符合游戏规则，导出的地图能回到游戏中运行；随后让 K3.1 Pro 使用生成的编辑器搭建场景。这类任务连接了文件格式理解、界面开发和工具操作，比生成一段展示代码更接近真实工作流。作者认为 Kimi 与对比模型各有视觉长处；这些是个人观察，不是普遍的审美结论。

金融研究：检查公式与引用，而不只读结论

机器之心编辑泽南、张倩、Panda 的介绍材料整理了财务建模、研究报告和 3D 工程案例。官方文档也展示了可调整经营假设的财务模型与带来源的研究报告。这些案例值得借鉴的是验收要求：修改假设后公式能否联动、关键数字能否回到原始文件、报告引用能否逐条打开。厂商展示不等于对任意金融任务的正确性保证。官方能力与案例介绍

截至本文核验，官方称计划在 11 月 4 日前开放完整权重；本文不将计划描述为已经发布，也不把官方应用中的 3D 功能视作 API 自带的建模工具。

API 基础调用

官方示例使用 Python 3.9+ 与 OpenAI SDK。API Key 应放在环境变量中，不要写入源码或提交到版本库。

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 发放的 Key 和上述官方 Base URL。若使用兼容 API 的第三方服务，应替换为该服务提供的 Base URL、Key 和模型目录，不要把官方凭据交给第三方。贵数智能的当前支持型号及计费方式以模型价格页为准。

如何选择推理强度

K3.1 Pro 始终处于思考模式；reasoning_effort 控制推理强度，而不是切换思考开关。官方提供 low、high、max 三档，默认值为 max。官方推理强度说明

• 简短问答或结构明确的转换任务，可先试 low。
• 多步骤代码修改、分析和计划任务，可从 high 开始。
• 需要较深推理的复杂任务，可比较 max 的质量、延迟和实际费用。

这些是工作流选择建议，不是模型性能保证。生产环境应以自己的任务集评估正确率、延迟与成本。

多轮对话：保留完整 assistant message

官方要求多轮对话以及工具回传时，将 API 返回的完整 assistant message 加入下一次请求，而不是只保留文本 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 message

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 message。应用必须自行实施鉴权、参数校验、超时、幂等和审计。

视觉输入：使用对象数组

官方文档规定，视觉消息的 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)

实际接入前应核对图像格式、大小和文件接口限制；将敏感图片发送到外部模型前，也要确认组织的数据处理规则。

官方基准与第三方体验如何解读

Moonshot 文档披露，K3.1 Pro 在 Terminal-Bench 4.0 得分 65.7%，并列出与 GPT-6 Astra、Claude Opus 5.5 的对比；这些数字是厂商发布的基准信息，应结合任务集、测试配置和发布日期理解，不能外推为所有代码任务的胜率。官方模型介绍与基准

第三方作者刘小排分享了相机 3D 交互作品等体验，并给出个人模型比较判断。该内容是作者的第三方体验，不是贵数智能测试，也不等于统一、可复现的横评。评估模型时，建议选取自己的代码库、设计约束和失败样本，记录提示词、工具、重试次数、时延及费用。

接入检查清单

1. 确认调用的是官方直连还是兼容服务，并使用对应的模型 ID、Base URL 与 Key。
2. 从较低推理强度开始，用代表性任务逐步比较质量、时延和账单。
3. 多轮与 Agent 场景保存完整 assistant message，并正确关联工具结果。
4. 视觉消息按对象数组构造；本地图片使用官方支持的编码或文件流程。
5. 对工具执行设置权限边界、参数校验、超时和失败处理。
6. 部署前确认当前模型目录、可用区域和价格，避免沿用旧配置。

常见问题

Kimi K3.1 Pro 的 API 模型 ID 是什么？

官方文档给出的 ID 是 kimi-k3.1-pro。高速型号写作 kimi-k3.1-pro-highspeed，两者不能混为一个模型配置。

推理强度默认是多少？

官方文档列出 low、high、max，默认 max；模型本身始终启用思考模式。

能否直接传图片 URL？

官方文档明确不支持公网图片 URL。请使用视觉对象数组和 Base64 Data URL，或按文件流程使用 ms:// 引用。

为什么 Agent 要回传完整 assistant message？

其中可能包含工具调用等结构化字段。仅保存文本内容会丢失后续交互所需的信息；工具结果还需要使用对应的 tool_call_id。

贵数智能是否提供 Kimi K3.1 Pro？

本站可用型号、路由和价格以模型价格页当前展示为准；官方直连能力不等于本站已提供，也不等于本站支持高速型号。

延伸阅读

• 查看模型价格与可用型号
• 浏览贵数智能博客

---

官方资料核验日期：2026-10-24。模型能力、API 参数和访问条件可能更新，请以 Moonshot Kimi API 文档为准。