> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kimi K3.1 Pro

> Kimi K3.1 Pro 与高速版官转接入指南：模型选型、OpenAI 兼容调用、思考分档、流式输出、工具调用，以及缓存参数和实测边界。

## 概述

**Kimi K3.1 Pro** 是月之暗面的思考模型，适合代码开发、复杂推理和多步工具任务。API易提供 `kimi-k3.1-pro` 与 `kimi-k3.1-pro-highspeed` 两款官转模型，使用同一套请求格式；切换型号只需修改 `model`。

> [!NOTE]
>
> **先选标准版，再按时延需求切换高速版。** 两款均始终开启思考，可用 `reasoning_effort` 调整思考深度。高速版的输入、输出与缓存写入单价更高，适合对响应速度要求更高的交互流程。

> [!WARNING]
>
> **1 小时缓存本轮未验证通过，不作为已支持能力。** 基础对话、流式、工具调用等已通过；缓存参数参考与本轮验证边界见下方说明。

> **[快速接入](#快速开始)**
>
> 使用 OpenAI SDK 或 HTTP，直接调用 Chat Completions。

> **[模型与价格](#模型选型与价格)**
>
> 对照标准版与高速版，以及输入、输出、缓存的计费方式。

> **[思考与工具](#工具调用)**
>
> 按任务选择思考档位，正确回传工具调用历史。

> **[上下文缓存](#上下文缓存)**
>
> 了解官方缓存参数与 API易本轮实测边界。

## 模型选型与价格

两款模型按实际 token 用量计费，**API易当前配置单价与官网一致**。单位均为 **美元 / 1M tokens**；普通输入与输出扣费已核对，缓存档位为配置价，不代表本轮已验证缓存结算：

| 计费项目 | `kimi-k3.1-pro` | `kimi-k3.1-pro-highspeed` |
| - | - | - |
| 普通输入 | \$2.00 | \$4.00 |
| 输出（含思考） | \$10.00 | \$20.00 |
| 缓存读取（配置价） | \$0.20 | \$0.20 |
| 缓存写入：5 分钟（配置价） | \$2.00 | \$4.00 |
| 缓存写入：1 小时（配置价） | \$4.00 | \$8.00 |

> [!NOTE]
>
> 模型价格与官网对齐，且可能随官网调整；上表仅供参考，具体以顶部导航「模型价格」栏目为准：[模型价格](https://docs.apiyi.com/models/index.md)。

| 型号 | 建议用途 | 选择依据 |
| - | - | - |
| `kimi-k3.1-pro` | 日常开发、推理、文档处理、批量工具任务 | 以成本为先的默认选择 |
| `kimi-k3.1-pro-highspeed` | 交互式智能体、需要更快返回的工作流 | 为更低时延接受更高 token 单价 |

### 充值加赠后的实际成本

满足 [充值加赠活动](https://docs.apiyi.com/faq/recharge-promotions.md) 条件时，**充值送 20％** 相当于使用 1 份充值金额获得 1.2 份可用额度：实际成本为挂牌价的 `1 ÷ 1.2 ≈ 83.33％`，即**约 8.3 折**。

这一折算作用于可用额度，模型挂牌单价不变。活动门槛、加赠比例与适用规则以活动页为准。

## 基础能力实测

API易于 **2026-10-25 (UTC+8)** 对两款模型完成以下基础用例验证：

| 能力 | `kimi-k3.1-pro` | `kimi-k3.1-pro-highspeed` |
| - | - | - |
| 非流式文本对话 | 通过 | 通过 |
| 流式文本输出 | 通过 | 通过 |
| JSON 对象输出 | 通过 | 通过 |
| 函数调用及工具结果回传 | 通过 | 通过 |
| 图像理解 | 通过 | 通过 |
| Responses 基础调用 | 通过 | 通过 |
| Messages 基础调用 | 通过，需显式采样参数 | 通过，需显式采样参数 |
| 普通输入与输出计费日志核查 | 与挂牌单价一致 | 与挂牌单价一致 |

本页以 Chat Completions 为主要接入示例；已有 Responses 集成也可使用 `POST /v1/responses`。图像理解用例采用 Base64 数据输入。

Messages 接口 `POST /v1/messages` 也已通过基础验证；请显式传入 `top_p: 0.95` 与 `temperature: 1`，避免默认采样参数转换引发报错。

> [!NOTE]
>
> 上表验证了基础调用与结果语义，并核对普通输入、输出扣费；不代表已穷举所有参数、最大上下文或长时间运行表现。缓存有效期和计费需单独验证，见下方缓存说明。

## 快速开始

使用 API易令牌，通过 `POST /v1/chat/completions` 调用。先以 `reasoning_effort: "low"` 跑通接入，再根据任务复杂度提高思考档位。

```bash cURL theme={null}
curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer $APIYI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3.1-pro",
    "messages": [
      {"role": "user", "content": "解释 Python 字典与列表的区别，并各举一个使用场景。"}
    ],
    "reasoning_effort": "low",
    "max_completion_tokens": 8192
  }'
```

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1",
    timeout=300,
)

response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[
        {"role": "user", "content": "解释 Python 字典与列表的区别，并各举一个使用场景。"}
    ],
    reasoning_effort="low",
    max_completion_tokens=8192,
)

message = response.choices[0].message
print(message.content)
print(response.usage)
```

> [!TIP]
>
> 把模型名做成配置项。需要高速版时，改成 `kimi-k3.1-pro-highspeed`，其余接入代码可以复用。

## 思考控制与关键参数

两款模型**始终开启思考**。用 `reasoning_effort` 控制深度，而非沿用 Kimi K2.5 的 `enable_thinking` 开关。

| 参数 | 用法 |
| - | - |
| `reasoning_effort` | `low`、`high`、`max`；官方默认 `max` |
| `max_completion_tokens` | 为本次输出设置预算；预算包含思考与最终回答 |
| `stream` | 设为 `true` 接收流式输出 |
| `stream_options.include_usage` | 流式请求设为 `true`，获取末块用量 |
| `tools` | 定义由你的应用执行的函数工具 |
| `prompt_cache_options` | 配置隐式上下文缓存及有效期 |

> [!WARNING]
>
> 不要把 `max_completion_tokens` 设得过小。思考会先消耗输出预算，预算耗尽时可能只得到思考内容，最终回答为空或不完整。检查 `finish_reason`，并按任务需要增加预算。

官方固定采样参数为 `temperature=1`、`top_p=0.95`、`n=1`、`presence_penalty=0`、`frequency_penalty=0`。本页 Chat Completions 示例省略这些参数；Messages 接口按上方说明显式传入采样参数。避免从其他模型复制不兼容的配置。

### 如何读取回答

最终回答在 `choices[0].message.content`，思考内容在 `choices[0].message.reasoning_content`。展示最终回答时读取 `content`；需要单独展示思考过程时，再读取 `reasoning_content`。

思考 token 按输出价格计费，不能只用用户可见的回答长度估算费用。以响应 `usage` 和控制台日志为准。

## 流式输出

思考阶段和正文阶段分别通过 `delta.reasoning_content`、`delta.content` 返回。末尾还可能有 `choices` 为空的用量块，解析时先检查 `chunk.usage`，再读取 `choices`。

```python theme={null}
stream = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[{"role": "user", "content": "设计一个带重试机制的任务队列。"}],
    reasoning_effort="low",
    max_completion_tokens=8192,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.usage is not None:
        print("\nUsage:", chunk.usage)
    if not chunk.choices:
        continue

    delta = chunk.choices[0].delta
    reasoning = getattr(delta, "reasoning_content", None)
    if reasoning:
        # 将思考内容写入独立区域，避免混入最终答案。
        pass
    if delta.content:
        print(delta.content, end="", flush=True)
```

## 工具调用

模型负责生成函数名和参数，实际工具由你的应用执行。收到 `tool_calls` 后，把**完整 assistant 消息**追加到历史，包含 `reasoning_content` 与 `tool_calls`；再追加对应 `tool_call_id` 的工具结果，发起下一轮请求。

```python theme={null}
import json

messages = [{"role": "user", "content": "查询订单 A100 的配送状态。"}]
tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "查询指定订单的配送状态",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
            "additionalProperties": False,
        },
    },
}]

response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=messages,
    tools=tools,
    reasoning_effort="low",
    max_completion_tokens=8192,
)
message = response.choices[0].message
messages.append(message.model_dump(exclude_none=True))

if message.tool_calls:
    for call in message.tool_calls:
        arguments = json.loads(call.function.arguments)
        # 示例结果；生产环境应校验参数后调用真实订单服务。
        result = {"order_id": arguments["order_id"], "status": "已发货"}
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result, ensure_ascii=False),
        })

    final = client.chat.completions.create(
        model="kimi-k3.1-pro",
        messages=messages,
        tools=tools,
        reasoning_effort="low",
        max_completion_tokens=8192,
    )
    print(final.choices[0].message.content)
else:
    print(message.content)
```

> [!WARNING]
>
> 工具调用轮次不要只保留 `content`。遗漏 `reasoning_content` 或 `tool_calls` 可能破坏后续推理与工具结果关联。先校验工具名、参数与执行权限，再运行模型请求的操作。

## 上下文缓存

官方缓存机制适合反复使用的长系统提示词、知识文档与代码上下文。稳定内容放在消息前部，每次变化的问题放在末尾。

> [!WARNING]
>
> **本轮未验证通过，不作为 API易已支持的 1 小时缓存能力。** 两款模型分别用独立长前缀测试 5 分钟和 1 小时策略，请求均成功，但未返回有效缓存读写计数；间隔约 5 分半后的四组回读及后续短间隔复用均未观察到缓存命中。1 小时请求的日志也只出现普通输入计费，未观察到 1 小时缓存写入费用。

以上结论只代表本轮测试结果，不能据此断言该能力在所有请求中均不支持。生产预算请先按普通输入价格估算；确认自己的请求出现缓存用量和对应计费后，再计入缓存节省。以下参数与机制仅供官方格式参考。

### 选择缓存有效期

Chat Completions 使用**请求体顶层** `prompt_cache_options`，默认有效期为 5 分钟。选择 1 小时时传：

```python theme={null}
response = client.chat.completions.create(
    model="kimi-k3.1-pro",
    messages=[
        {"role": "system", "content": LONG_STABLE_CONTEXT},
        {"role": "user", "content": "根据上面的资料，列出三个关键结论。"},
    ],
    reasoning_effort="low",
    max_completion_tokens=8192,
    extra_body={
        "prompt_cache_options": {"mode": "implicit", "ttl": "1h"}
    },
)
print(response.usage)
```

`LONG_STABLE_CONTEXT` 代表你需要重复使用的长文本。后续请求保持该前缀一致，再替换最后的问题。

> [!NOTE]
>
> **缓存有效期在首次写入时确定。** 对已存在的 5 分钟缓存改传 `ttl: "1h"`，不会直接把它升级为 1 小时；命中会按原有有效期续期。需要对照两种策略时，应使用不同的新前缀分别写入。

### 读取与写入如何计费

* **缓存读取**：复用已有前缀，按缓存读取单价计费。
* **缓存写入**：新前缀进入缓存，按所选 5 分钟或 1 小时写入单价计费。
* **普通输入**：未纳入缓存的输入部分，按普通输入单价计费。
* **输出**：思考和最终回答都按输出单价计费。

以上是官方计费分类。本轮只验证了普通输入和输出扣费，未验证到缓存读写结算。排查费用时，同时检查响应 `usage`、缓存读取/创建字段和控制台计费日志，不能只看参数是否被接受。

## 技术规格与接入建议

| 项目 | 说明 |
| - | - |
| 模型 ID | `kimi-k3.1-pro`、`kimi-k3.1-pro-highspeed` |
| 官方上下文窗口 | 1,048,576 tokens |
| 本页主端点 | `POST https://api.apiyi.com/v1/chat/completions` |
| 思考模式 | 始终开启；`reasoning_effort` 选择 `low` / `high` / `max` |
| 最终回答字段 | `choices[0].message.content` |
| 思考字段 | `choices[0].message.reasoning_content` |
| 官方缓存选项 | 默认 5 分钟；可请求 1 小时；平台实测边界见缓存说明 |

**1. 先用低思考档跑通**

先发送短请求，确认模型名、令牌、响应解析正确，再增加上下文长度。

**2. 为思考保留输出预算**

根据 `finish_reason` 与用量调整 `max_completion_tokens`，复杂任务再提高 `reasoning_effort`。

**3. 长任务优先用流式**

分别处理思考与正文，并读取末块用量；客户端和中间代理都应留出足够超时。

**4. 先验证缓存再扩大流量**

用固定长前缀做重复请求，对照缓存用量与计费日志，确认业务请求确实命中。

## 常见问题

> **高速版是否只是不同的模型名？**
>
> 两款使用相同接入格式，高速版定位于更低时延，单价更高。实际速度受提示词长度、思考深度、输出长度和当时负载影响，应以你的业务样本评估。

> **能像 Kimi K2.5 一样关闭思考吗？**
>
> K3.1 Pro 系列始终开启思考。用 `reasoning_effort: "low"` 控制开销，不要沿用旧版 `enable_thinking` 参数。

> **为什么最终回答很短，输出计费却更多？**
>
> 输出包含思考 token。最终回答字符数不能代表完整输出用量，请查看响应 `usage` 和控制台日志。

> **1 小时缓存是否只需把旧请求的 ttl 改成 1h？**
>
> 按官方机制，已存在的缓存沿用首次写入时的有效期，需要从新前缀开始传 `ttl: "1h"`。但 API易本轮尚未验证到 1 小时保留与写入计费，不能把传参成功当作支持证明。

> **充值送 20％为什么是约 8.3 折？**
>
> 因为同样金额可使用 1.2 倍额度，折算为 `1 ÷ 1.2 ≈ 83.33％`。这需要满足活动条件，详见 [充值加赠活动](https://docs.apiyi.com/faq/recharge-promotions.md)。

## 相关文档

* [API 使用手册](https://docs.apiyi.com/api-manual.md)
* [函数调用基础](https://docs.apiyi.com/api-capabilities/openai/function-calling.md)
* [推理模型响应处理](https://docs.apiyi.com/api-capabilities/openai/reasoning-models.md)
* [模型价格](https://docs.apiyi.com/models/index.md)
* [充值加赠活动](https://docs.apiyi.com/faq/recharge-promotions.md)

官方资料核对入口：`platform.moonshot.ai/docs/guide/kimi-k3-1-pro-quickstart`、`platform.kimi.ai/docs/guide/context-caching`、`platform.moonshot.ai/docs/pricing/chat`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.