# 下载产物内容 Source: https://platform.kimi.com/docs/api-reference/产物/下载产物内容 /hosted-agents/openapi.yaml get /v1/artifacts/{id}/content 下载产物内容。未指定 `version` 时下载最新版本。 # 列出产物 Source: https://platform.kimi.com/docs/api-reference/产物/列出产物 /hosted-agents/openapi.yaml get /v1/artifacts 列出调用方可见的产物，最近交付的在前。每个条目为该产物的最新版本。用 `session_id` 筛选单个会话的产物。 # 列出产物版本 Source: https://platform.kimi.com/docs/api-reference/产物/列出产物版本 /hosted-agents/openapi.yaml get /v1/artifacts/{id}/versions 列出一个产物的全部版本，最新在前。每个条目为该版本的完整产物。 # 删除产物 Source: https://platform.kimi.com/docs/api-reference/产物/删除产物 /hosted-agents/openapi.yaml delete /v1/artifacts/{id} 永久删除一个产物及其全部版本。已上报该产物的事件不会撤回。 # 获取产物 Source: https://platform.kimi.com/docs/api-reference/产物/获取产物 /hosted-agents/openapi.yaml get /v1/artifacts/{id} 返回单个产物的元数据。未指定 `version` 时返回最新版本，指定时返回该确切版本。 # 上传文件 Source: https://platform.kimi.com/docs/api-reference/文件/上传文件 /hosted-agents/openapi.yaml post /v1/files 以 multipart 表单数据上传一个文件，并返回其文件记录。 - **表单**：`file` 部分必填，须携带文件名（或在表单中显式提供 `filename`）。该部分自身的 Content-Type 可以省略，存储的 MIME 类型将按文件内容与文件名检测。 - **限制**：单个文件上限 100 MiB 且不能为空。上传后的文件不可修改。 - **命名**：与现有文件重名上传时，服务器会在存储的文件名上添加后缀，例如 `report (1).txt`。 # 列出文件 Source: https://platform.kimi.com/docs/api-reference/文件/列出文件 /hosted-agents/openapi.yaml get /v1/files 列出已上传的文件。不带 `kimi-api-version` 请求头的请求列出整个组织的文件列表；`2026-09-01-beta` 请求列出项目下的文件。不带 `page_size` 时返回完整列表。通过 `POST /v1/sessions/{id}/resources` 将文件挂载到会话。 # 列出智能体 Source: https://platform.kimi.com/docs/api-reference/智能体/列出智能体 /hosted-agents/openapi.yaml get /v1/agents 返回调用方的智能体，默认最新在前，除非 `order` 为 `created_at`。已归档的智能体不会出现在列表中。 将 `official_only` 设为 true 时，仅返回平台提供的官方智能体；默认值为 false。 # 列出智能体版本 Source: https://platform.kimi.com/docs/api-reference/智能体/列出智能体版本 /hosted-agents/openapi.yaml get /v1/agents/{id}/versions 返回智能体的不可变版本，最新在前。每一项都是该版本捕获的完整配置。 # 创建智能体 Source: https://platform.kimi.com/docs/api-reference/智能体/创建智能体 /hosted-agents/openapi.yaml post /v1/agents 创建智能体及其首个不可变版本（`"1"`）。 - 省略 `version`（或使用 `"latest"`）的技能引用会固定到确切版本。插件版本始终固定为当前采纳的版本，必须省略。 - `multiagent` 名册在写入时解析为固定的智能体版本。 # 归档智能体 Source: https://platform.kimi.com/docs/api-reference/智能体/归档智能体 /hosted-agents/openapi.yaml post /v1/agents/{id}/archive 归档智能体。已归档的智能体仍可读取，但不能更新，也不能用于开启新会话。已有会话不受影响。 # 更新智能体 Source: https://platform.kimi.com/docs/api-reference/智能体/更新智能体 /hosted-agents/openapi.yaml patch /v1/agents/{id} 修改请求体中提供的字段，并创建一个新的不可变智能体版本。 - 数组和 `metadata` 会替换已存储的值。传入空值可清空对应集合。`null` 值视为未提供。 - 传入当前的 `version` 进行乐观并发检查。版本过期时更新失败，返回 409 `conflict_error`。 - 空补丁返回 400 `invalid_request_error`。已归档的智能体拒绝更新，返回 400 `failed_precondition_error`。 # 获取智能体 Source: https://platform.kimi.com/docs/api-reference/智能体/获取智能体 /hosted-agents/openapi.yaml get /v1/agents/{id} 返回单个智能体及其最新版本。已归档的智能体仍可读取。 # 列出环境 Source: https://platform.kimi.com/docs/api-reference/环境/列出环境 /hosted-agents/openapi.yaml get /v1/environments 返回调用方的环境，最新在前。除非 `include_archived` 为 true，否则不包含已归档的环境。 将 `official_only` 设为 true 时，仅返回平台提供的官方环境；默认值为 false。 # 创建环境 Source: https://platform.kimi.com/docs/api-reference/环境/创建环境 /hosted-agents/openapi.yaml post /v1/environments 创建一个环境，将其配置冻结为不可变版本 `"1"`，并开始构建。 最新版本的 `build_status` 报告 `ready` 后，会话即可使用该环境。名称不要求唯一。 # 删除环境 Source: https://platform.kimi.com/docs/api-reference/环境/删除环境 /hosted-agents/openapi.yaml delete /v1/environments/{id} 永久删除一个已归档的环境及其全部版本。 环境必须先归档，且没有任何未终止的会话仍在引用它，否则返回 400 `failed_precondition_error`。 # 归档环境 Source: https://platform.kimi.com/docs/api-reference/环境/归档环境 /hosted-agents/openapi.yaml post /v1/environments/{id}/archive 归档一个环境。已归档的环境拒绝更新，也不能承载新会话。现有会话不受影响。 # 更新环境 Source: https://platform.kimi.com/docs/api-reference/环境/更新环境 /hosted-agents/openapi.yaml patch /v1/environments/{id} 仅修改请求体中出现的字段。`null` 值视为未提供，传入空对象或空数组可清空对应集合。 每次更新——包括仅修改元数据——都会冻结一个新的不可变版本并开始构建。只有之后创建的会话会使用新版本。配置类型不能更改。已归档的环境拒绝更新（400 `failed_precondition_error`）。 # 获取环境 Source: https://platform.kimi.com/docs/api-reference/环境/获取环境 /hosted-agents/openapi.yaml get /v1/environments/{id} 返回单个环境，包括其最新版本的构建状态。已归档的环境仍可读取。 # 查询余额 Source: https://platform.kimi.com/docs/api/balance GET /v1/users/me/balance 查询当前账户的可用余额。 查询您在 Kimi 开放平台上的可用余额、代金券余额和现金余额。当可用余额小于等于 0 时，用户无法调用推理 API。 ```python python expandable theme={null} import os import requests api_key = os.environ.get("MOONSHOT_API_KEY") url = "https://api.moonshot.cn/v1/users/me/balance" response = requests.get( url, headers={"Authorization": f"Bearer {api_key}"}, ) print(response.json()) ``` ```bash curl expandable theme={null} curl https://api.moonshot.cn/v1/users/me/balance \ -H "Authorization: Bearer $MOONSHOT_API_KEY" ``` ```javascript node.js expandable theme={null} const apiKey = process.env.MOONSHOT_API_KEY; async function main() { const response = await fetch("https://api.moonshot.cn/v1/users/me/balance", { method: "GET", headers: { Authorization: `Bearer ${apiKey}`, }, }); const data = await response.json(); console.log(data); } main(); ``` | 字段 | 类型 | 说明 | | - | - | - | | `code` | integer | 响应码。0 表示成功。 | | `data` | object | 余额数据对象 | | `data.available_balance` | number | 可用余额（单位：人民币元），包含现金余额和代金券余额。当小于等于 0 时，用户无法调用推理 API | | `data.voucher_balance` | number | 代金券余额（单位：人民币元），不可为负 | | `data.cash_balance` | number | 现金余额（单位：人民币元），可为负值表示欠费。当为负值时，`available_balance` 等于 `voucher_balance` 的值 | | `scode` | string | 状态码 | | `status` | boolean | 请求状态 | **响应示例** ```json theme={null} { "code": 0, "data": { "available_balance": 49.58894, "voucher_balance": 46.58893, "cash_balance": 3.00001 }, "scode": "0x0", "status": true } ``` 当 `available_balance` 小于等于 0 时，调用推理 API 将返回 `exceeded_current_quota_error` 错误。请及时充值或检查代金券有效期。 `platform.kimi.com`（国内站）与 `platform.kimi.ai`（国际站）申请的 API Key 完全独立，混用会返回 401 错误。请确认调用端点与 Key 所属平台一致。 # 取消批处理任务 Source: https://platform.kimi.com/docs/api/batch-cancel POST /v1/batches/{batch_id}/cancel 取消一个进行中的批处理任务。 取消一个正在进行的批处理任务。取消后，任务状态将先变为 `cancelling`，最终变为 `cancelled`。仅 `validating`、`in_progress`、`finalizing` 状态的任务可以取消。 ```python Python theme={null} import os from openai import OpenAI from openai.types import Batch client = OpenAI( api_key=os.environ.get("MOONSHOT_API_KEY"), base_url=os.environ.get("MOONSHOT_BASE_URL", "https://api.moonshot.cn/v1"), ) batch: Batch = client.batches.cancel("your_batch_id") print(f"状态: {batch.status}") # cancelling ``` ```bash cURL theme={null} curl -X POST ${MOONSHOT_BASE_URL:-https://api.moonshot.cn/v1}/batches/your_batch_id/cancel \ -H "Authorization: Bearer $MOONSHOT_API_KEY" ``` ```javascript Node.js theme={null} const OpenAI = require("openai"); const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: process.env.MOONSHOT_BASE_URL || "https://api.moonshot.cn/v1", }); async function main() { const batch = await client.batches.cancel("your_batch_id"); console.log(`状态: ${batch.status}`); // cancelling } main(); ``` 调用成功后，接口返回一个 `BatchObject` 对象，包含以下字段： | 字段 | 类型 | 说明 | | - | - | - | | `id` | string | 批处理任务的唯一标识符 | | `object` | string | 对象类型，固定为 `batch` | | `endpoint` | string | 请求端点 | | `input_file_id` | string | 输入文件 ID | | `completion_window` | string | 任务处理时间窗口 | | `status` | string | 当前状态。取消请求成功后通常为 `cancelling`，最终变为 `cancelled` | | `output_file_id` | string \| null | 处理成功的结果文件 ID | | `error_file_id` | string \| null | 处理失败的错误文件 ID | | `created_at` | integer | 创建时间（Unix 时间戳） | | `in_progress_at` | integer \| null | 开始执行时间（Unix 时间戳） | | `expires_at` | integer \| null | 过期时间（Unix 时间戳） | | `finalizing_at` | integer \| null | 开始准备结果的时间（Unix 时间戳） | | `completed_at` | integer \| null | 完成时间（Unix 时间戳） | | `failed_at` | integer \| null | 校验失败时间（Unix 时间戳） | | `cancelling_at` | integer \| null | 发起取消时间（Unix 时间戳） | | `cancelled_at` | integer \| null | 取消完成时间（Unix 时间戳） | | `request_counts` | object | 请求计数，包含 `completed`（已完成）、`failed`（失败）、`total`（总数） | | `metadata` | object \| null | 自定义元数据 | 仅 `validating`、`in_progress`、`finalizing` 状态的任务可以取消。若任务已处于 `completed`、`failed`、`expired` 或 `cancelled` 状态，调用此接口将返回 400 错误。 **常见错误说明** * **400 请求错误**：任务状态不允许取消，或请求参数无效。请确认任务状态后再发起取消。 * **401 未授权**：API Key 无效或缺失。请检查 `Authorization: Bearer ` 是否正确。 * **404 未找到**：指定的 `batch_id` 不存在。请确认 ID 拼写正确且该任务属于当前组织。 * **500 服务器错误**：服务端内部错误，请稍后重试；若持续出现，请附带 `request_id` 联系支持团队。 详见 [常见错误码说明](/docs/api/errors)。 完整的调用示例和状态流转说明，请参考 [Batch API 指南](/docs/guide/use-batch-api)。 # 创建批处理任务 Source: https://platform.kimi.com/docs/api/batch-create POST /v1/batches 创建批处理任务，以更低价格异步批量处理请求。 **限制：** | 限制项 | 说明 | | - | - | | 文件格式 | 必须为 `.jsonl` 扩展名 | | 文件大小 | 不能为空，最大 100MB | | 组织文件配额 | 每个组织最多 1000 个 batch 类型文件 | | 模型一致性 | 同一批次内所有请求必须使用相同模型 | | `custom_id` | 文件内必须唯一 | | 模型权限 | 指定的模型必须存在且用户有访问权限 | 完整的调用示例请参考 [Batch API 指南](/docs/guide/use-batch-api)。 # 列出批处理任务 Source: https://platform.kimi.com/docs/api/batch-list GET /v1/batches 列出当前账户的批处理任务。 列出当前组织下的所有批处理任务，支持分页查询。常用于查看任务列表、检查批量任务状态或进行批量管理。 ```python Python theme={null} import os from openai import OpenAI from openai.pagination import SyncCursorPage from openai.types import Batch client = OpenAI( api_key=os.environ.get("MOONSHOT_API_KEY"), base_url=os.environ.get("MOONSHOT_BASE_URL", "https://api.moonshot.cn/v1"), ) batches: SyncCursorPage[Batch] = client.batches.list(limit=10) for batch in batches.data: print(f"{batch.id} - {batch.status} ({batch.request_counts.completed}/{batch.request_counts.total})") ``` ```bash cURL theme={null} curl "${MOONSHOT_BASE_URL:-https://api.moonshot.cn/v1}/batches?limit=10" \ -H "Authorization: Bearer $MOONSHOT_API_KEY" ``` ```javascript Node.js theme={null} const OpenAI = require("openai"); const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: process.env.MOONSHOT_BASE_URL || "https://api.moonshot.cn/v1", }); async function main() { const batches = await client.batches.list({ limit: 10 }); for (const batch of batches.data) { console.log(`${batch.id} - ${batch.status} (${batch.request_counts.completed}/${batch.request_counts.total})`); } } main(); ``` 列出任务接口返回一个分页列表对象，包含以下字段： | 字段 | 类型 | 说明 | | - | - | - | | `object` | string | 对象类型，固定为 `"list"` | | `data` | array\[object] | 批处理任务列表，每个元素为 `BatchObject` 对象，字段含义与[获取任务详情](/docs/api/batch-retrieve)一致 | | `has_more` | boolean | 是否还有更多数据。为 `true` 时，可通过 `after` 参数传入本页最后一个 `batch.id` 获取下一页 | **响应示例** ```json theme={null} { "object": "list", "data": [ { "id": "batch_xxx", "object": "batch", "endpoint": "/v1/chat/completions", "input_file_id": "file_xxx", "completion_window": "24h", "status": "completed", "output_file_id": "file_yyy", "error_file_id": null, "created_at": 1711475054, "in_progress_at": 1711475055, "expires_at": 1711561454, "finalizing_at": 1711475100, "completed_at": 1711475110, "failed_at": null, "cancelling_at": null, "cancelled_at": null, "request_counts": { "completed": 100, "failed": 0, "total": 100 }, "metadata": null } ], "has_more": false } ``` 完整的调用示例和状态流转说明，请参考 [Batch API 指南](/docs/guide/use-batch-api)。 当 `has_more` 为 `true` 时，需要通过 `after` 参数进行分页查询。将上一页最后一个 `batch.id` 作为 `after` 的值传入，即可获取下一页结果。若省略 `after` 参数，每次查询均返回第一页。 # 获取批处理任务详情 Source: https://platform.kimi.com/docs/api/batch-retrieve GET /v1/batches/{batch_id} 获取指定批处理任务的详情与进度。 获取指定批处理任务的当前状态、进度统计和详细元数据。通常用于创建任务后轮询任务是否完成。 ```python Python theme={null} import os from openai import OpenAI from openai.types import Batch client = OpenAI( api_key=os.environ.get("MOONSHOT_API_KEY"), base_url=os.environ.get("MOONSHOT_BASE_URL", "https://api.moonshot.cn/v1"), ) batch: Batch = client.batches.retrieve("your_batch_id") print(f"状态: {batch.status}") print(f"进度: {batch.request_counts.completed}/{batch.request_counts.total}") ``` ```bash cURL theme={null} curl ${MOONSHOT_BASE_URL:-https://api.moonshot.cn/v1}/batches/your_batch_id \ -H "Authorization: Bearer $MOONSHOT_API_KEY" ``` ```javascript Node.js theme={null} const OpenAI = require("openai"); const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: process.env.MOONSHOT_BASE_URL || "https://api.moonshot.cn/v1", }); async function main() { const batch = await client.batches.retrieve("your_batch_id"); console.log(`状态: ${batch.status}`); console.log(`进度: ${batch.request_counts.completed}/${batch.request_counts.total}`); } main(); ``` | 字段 | 类型 | 说明 | | - | - | - | | `id` | string | 批处理任务的唯一标识符 | | `object` | string | 对象类型，固定为 `batch` | | `endpoint` | string | 请求端点 | | `input_file_id` | string | 输入文件 ID | | `completion_window` | string | 任务处理时间窗口 | | `status` | string | 当前状态：`validating`（校验中）、`failed`（校验失败）、`in_progress`（执行中）、`finalizing`（准备结果中）、`completed`（已完成）、`expired`（已过期）、`cancelling`（取消中）、`cancelled`（已取消） | | `output_file_id` | string \| null | 处理成功的结果文件 ID | | `error_file_id` | string \| null | 处理失败的错误文件 ID | | `created_at` | integer | 创建时间（Unix 时间戳） | | `in_progress_at` | integer \| null | 开始执行时间（Unix 时间戳） | | `expires_at` | integer \| null | 过期时间（Unix 时间戳） | | `finalizing_at` | integer \| null | 开始准备结果的时间（Unix 时间戳） | | `completed_at` | integer \| null | 完成时间（Unix 时间戳） | | `failed_at` | integer \| null | 校验失败时间（Unix 时间戳） | | `cancelling_at` | integer \| null | 发起取消时间（Unix 时间戳） | | `cancelled_at` | integer \| null | 取消完成时间（Unix 时间戳） | | `request_counts` | object | 请求数量统计，包含 `completed`（已完成）、`failed`（失败）、`total`（总数） | | `metadata` | object \| null | 自定义元数据 | 完整的调用示例和轮询脚本请参考 [Batch API 指南](/docs/guide/use-batch-api)。 当 `status` 为 `completed` 时，`output_file_id` 包含结果文件 ID；当 `status` 为 `failed` 时，建议查看 `error_file_id` 获取错误详情。如果指定的 `batch_id` 不存在，接口将返回 `404` 错误（`resource_not_found_error`）。 # Chat Completions API Source: https://platform.kimi.com/docs/api/chat POST /v1/chat/completions 创建对话补全：向 Kimi 模型发送消息并获取回复，支持流式输出、工具调用与视觉输入。 创建一个对话补全请求，模型将根据输入的消息列表生成回复。 `content` 字段支持以下两种形式： **纯文本字符串** ```json theme={null} { "content": "你好" } ``` **对象数组**（用于多模态输入） 数组中每个元素通过 `type` 字段区分类型： ```json theme={null} { "content": [ { "type": "text", "text": "描述这张图片" }, { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }, { "type": "video_url", "video_url": { "url": "data:video/mp4;base64,..." } } ] } ``` 其中 `image_url` 和 `video_url` 也支持直接传入字符串，效果等同于对象形式中的 `url` 字段： ```json theme={null} { "type": "image_url", "image_url": "data:image/png;base64,..." } ``` #### 参数说明 数组中每个元素的字段说明如下： | 参数名称 | 是否必须 | 说明 | 类型 | | - | - | - | - | | `type` | required | 内容类型 | `"text"` \| `"image_url"` \| `"video_url"` | | `text` | 当 `type=text` 时必填 | 文本内容 | string | | `image_url` | 当 `type=image_url` 时必填 | 用于传输图片，支持对象形式 `{"url": "..."}` 或直接传入 URL 字符串 | object \| string | | `video_url` | 当 `type=video_url` 时必填 | 用于传输视频，支持对象形式 `{"url": "..."}` 或直接传入 URL 字符串 | object \| string | 当 `image_url` 传入对象时，其字段说明如下： | 参数名称 | 是否必须 | 说明 | 类型 | | - | - | - | - | | `url` | required | 使用 base64 编码或通过 file id 指定的图片内容 | string | 当 `video_url` 传入对象时，其字段说明如下： | 参数名称 | 是否必须 | 说明 | 类型 | | - | - | - | - | | `url` | required | 使用 base64 编码或通过 file id 指定的视频内容，例如 `data:video/mp4;base64,...` | string | 无论使用对象形式（`url` 字段）还是字符串简写，均支持以下两种格式： * base64 编码：`data:image/png;base64,...` 或 `data:video/mp4;base64,...` * 文件引用：`ms://` 详见[使用 Kimi 视觉模型](/docs/guide/use-kimi-vision-model)。 #### 调用示例 ```python python expandable theme={null} import os import base64 from openai import OpenAI from openai.types.chat import ChatCompletion client: OpenAI = OpenAI( api_key=os.environ.get("MOONSHOT_API_KEY"), base_url="https://api.moonshot.cn/v1", ) # 对图片进行 base64 编码 with open("您的图片地址", "rb") as f: img_base: str = base64.b64encode(f.read()).decode("utf-8") response: ChatCompletion = client.chat.completions.create( model="kimi-k2.6", messages=[ { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": f"data:image/jpeg;base64,{img_base}", }, }, { "type": "text", "text": "请描述这个图片", }, ], } ], ) print(response.choices[0].message.content) ``` ```bash curl expandable theme={null} curl https://api.moonshot.cn/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -d '{ "model": "kimi-k2.6", "messages": [ { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQ..." } }, { "type": "text", "text": "请描述这个图片" } ] } ] }' ``` ```javascript node.js expandable theme={null} const fs = require("fs"); const OpenAI = require("openai"); const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: "https://api.moonshot.cn/v1", }); async function main() { // 对图片进行 base64 编码 const imgBase = fs.readFileSync("您的图片地址").toString("base64"); const response = await client.chat.completions.create({ model: "kimi-k2.6", messages: [ { role: "user", content: [ { type: "image_url", image_url: { url: `data:image/jpeg;base64,${imgBase}`, }, }, { type: "text", text: "请描述这个图片", }, ], }, ], }); console.log(response.choices[0].message.content); } main(); ``` ### 非流式响应 ```json theme={null} { "id": "cmpl-04ea926191a14749b7f2c7a48a68abc6", "object": "chat.completion", "created": 1698999496, "model": "kimi-k2.6", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "你好，李雷！1+1等于2。如果你有其他问题，请随时提问！" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 19, "completion_tokens": 21, "total_tokens": 40, "cached_tokens": 10, "prompt_tokens_details": { "cached_tokens": 10, "cache_write_tokens": 0 } } } ``` ### 流式响应 ```text theme={null} data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]} data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]} ... data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":19,"completion_tokens":13,"total_tokens":32,"cached_tokens":12,"prompt_tokens_details":{"cached_tokens":12,"cache_write_tokens":0}}} data: [DONE] ``` 响应示例中的模型名称会根据请求中的 model 参数返回。当使用 `kimi-k2.6` 模型时，响应中的 `"model"` 字段将显示为 `"kimi-k2.6"`。 Kimi API 会对重复的请求前缀自动启用上下文缓存，命中部分以更低价格计费且响应更快。通过 `prompt_cache_options` 可以控制缓存写入行为： | 参数 | 类型 | 说明 | | - | - | - | | `prompt_cache_options` | object | 上下文缓存写入选项。不传时默认开启缓存写入（`5m` 档） | | `prompt_cache_options.mode` | `"implicit"` | 缓存写入模式，仅支持 `implicit`：自动将请求前缀写入缓存 | | `prompt_cache_options.ttl` | `"5m"` \| `"1h"` | 缓存写入的有效期，仅支持 `5m`、`1h` 两档（默认 `5m`），两档缓存相互独立 | ```json theme={null} { "model": "kimi-k3", "messages": [{"role": "user", "content": "你好"}], "prompt_cache_options": { "mode": "implicit", "ttl": "1h" } } ``` **行为说明** * 缓存以组织（org）为粒度隔离，组织之间不共享缓存。 * 相同前缀的请求在缓存有效期内命中后，缓存的有效期会按原 TTL 刷新；命中部分只收取缓存读取费用，不再收取缓存写入费用。 * 缓存写入按 TTL 分别计费，价格详见[产品定价](/docs/pricing/chat)。 * 不支持手动清除缓存，已缓存的前缀在至少 5 分钟不活动后自动过期。 * 暂不支持显式缓存断点：`content` 中出现 `prompt_cache_breakpoint` 时请求会被拒绝（HTTP 400）。 **用量字段** `usage.prompt_tokens` 始终为总输入 Token 数，其内部分类通过 `prompt_tokens_details` 返回： | 字段 | 说明 | | - | - | | `usage.prompt_tokens_details.cached_tokens` | 命中缓存的 Token 数量（缓存读取） | | `usage.prompt_tokens_details.cache_write_tokens` | 本次写入缓存的 Token 数量（缓存写入） | `cached_tokens`、`cache_write_tokens` 与未缓存部分互斥，三者之和等于 `prompt_tokens`，即未缓存部分 = `prompt_tokens` − `cached_tokens` − `cache_write_tokens`。 流式请求中，完整的缓存读写明细仅在最后一个 chunk 的 `usage` 字段中返回（需设置 `stream_options.include_usage=true`）。Chat Completions 的响应不回显实际应用的 mode/ttl（与 Responses API 不同），请从请求发起侧记录所用取值。 Context Caching 的机制背景详见[上下文缓存指南](/docs/guide/context-caching)。 Kimi API 是无状态的，本身不具有记忆功能。要实现多轮对话，需在每次请求时把前一轮的 assistant 回复（以及工具执行结果，如适用）原样追加到 `messages` 数组中再发送。 ```python theme={null} messages = [ {"role": "system", "content": "你是 Kimi。"}, {"role": "user", "content": "你好，我叫李雷。"} ] completion = client.chat.completions.create(model="kimi-k2.6", messages=messages) reply = completion.choices[0].message # 将 assistant 回复追加回 messages，供下一轮使用 messages.append({"role": "assistant", "content": reply.content}) messages.append({"role": "user", "content": "1+1 等于多少？"}) ``` 当对话历史过长时，建议只保留最近的若干条消息，或做消息压缩，以避免超出模型的上下文长度限制。 详见 [配置多轮对话参数](/docs/guide/engage-in-multi-turn-conversations-using-kimi-api)。 通过 `response_format` 参数可约束模型输出格式： * `{"type": "text"}`（默认）：普通文本输出 * `{"type": "json_object"}`：强制输出合法 JSON Object * `{"type": "json_schema", "json_schema": {...}}`：按给定 JSON Schema 输出结构化数据（Structured Output） 使用 `json_object` 时，**必须在 system prompt 或 user prompt 中明确描述期望的 JSON 字段和类型**，否则模型可能输出不符合预期的结果。 ```json theme={null} { "model": "kimi-k2.6", "messages": [ {"role": "system", "content": "请输出 JSON，包含 title、author、summary 字段。"}, {"role": "user", "content": "总结这篇文章..."} ], "response_format": {"type": "json_object"} } ``` 详见 [使用 Kimi API 的 JSON Mode](/docs/guide/use-json-mode-feature-of-kimi-api)。 通过 `tools` 参数传入 JSON Schema 定义的外部工具，模型可决定在适当时机调用它们。 **请求示例** ```json theme={null} { "model": "kimi-k2.6", "messages": [{"role": "user", "content": "北京今天天气怎么样？"}], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "获取指定城市的天气", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名称"} }, "required": ["city"] } } } ] } ``` **响应中的 `tool_calls`** 当 `finish_reason` 为 `"tool_calls"` 时，模型返回 `tool_calls` 数组，包含 `id`、`function.name` 和 `function.arguments`： ```json theme={null} { "choices": [{ "message": { "role": "assistant", "content": "", "tool_calls": [{ "id": "call_xxx", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"北京\"}" } }] }, "finish_reason": "tool_calls" }] } ``` **提交工具执行结果** 在本地执行工具后，将结果通过 `role="tool"` 消息追加到 `messages` 中（`tool_call_id` 必须与请求中的 `id` 对应）： ```json theme={null} {"role": "tool", "tool_call_id": "call_xxx", "content": "晴，25°C"} ``` 详见 [使用 Kimi API 完成工具调用](/docs/guide/use-kimi-api-to-complete-tool-calls)。 `kimi-k3` 始终进行推理，使用顶层 `reasoning_effort`（支持 `"low"`、`"high"`、`"max"`，默认 `"max"`）。`kimi-k2.6` 和 `kimi-k2.7-code` 支持思考模式，模型在输出最终答案前会先输出推理过程（`reasoning_content`）。 **K2.x 请求参数** | 字段 | 类型 | 说明 | | - | - | - | | `thinking.type` | `"enabled"` \| `"disabled"` | 思考开关（`kimi-k2.7-code` 始终为 `enabled`，不可关闭） | | `thinking.keep` | `null` \| `"all"` | Preserved Thinking：是否将历史轮次的 `reasoning_content` 保留在上下文。`kimi-k2.6` 默认 `null`（不保留），可选 `"all"`；`kimi-k2.7-code` 固定为 `"all"`（保留），传入其他值报错 | **响应字段** 非流式响应中，`choices[0].message` 包含： | 字段 | 说明 | | - | - | | `content` | 最终答案 | | `reasoning_content` | 推理过程（仅在思考模式启用时返回） | ```json theme={null} { "choices": [{ "message": { "role": "assistant", "content": "1+1 等于 2。", "reasoning_content": "用户问的是基础数学问题，直接相加即可。" } }] } ``` 多轮对话中若使用思考模式，请务必将每一轮 assistant 消息的 `reasoning_content` 原样保留在 `messages` 中，否则模型可能丢失推理上下文。 详见 [配置思考模式](/docs/guide/use-thinking-models)。 设置 `stream: true` 可启用流式输出，模型会以 Server-Sent Events (SSE) 格式逐段返回生成的内容。推荐在聊天、代码生成、长文本输出等实时性要求高的场景中使用。 ```python theme={null} completion = client.chat.completions.create( model="kimi-k2.6", messages=[{"role": "user", "content": "请解释什么是递归。"}], stream=True ) for chunk in completion: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="") ``` **SSE 响应格式** 每一行以 `data:` 开头，内容为 JSON 对象。当 `finish_reason` 为 `null` 时，内容在 `delta.content` 中累加；当 `finish_reason` 不为 `null` 时，表示输出结束： ```text theme={null} data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]} data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]} data: {"id":"cmpl-xxx","object":"chat.completion.chunk","created":1698999575,"model":"kimi-k2.6","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":19,"completion_tokens":13,"total_tokens":32,"cached_tokens":12,"prompt_tokens_details":{"cached_tokens":12,"cache_write_tokens":0}}} data: [DONE] ``` **`stream_options`** 通过 `stream_options: {"include_usage": true}` 可在最后一个 chunk（`data: [DONE]` 之前）额外获取 `usage` 字段，显示本次请求的 Token 消耗： ```python theme={null} stream=True, stream_options={"include_usage": True} ``` 详见 [利用 Kimi API 的流式输出功能](/docs/guide/utilize-the-streaming-output-feature-of-kimi-api)。 Partial Mode（Prefill）允许你在 `messages` 的最后一条 assistant 消息中预填输出前缀，从而引导模型按照你期望的格式或方向继续生成。 **开启方式** 在 `messages` 数组末尾添加一条 `role="assistant"` 的消息，并设置 `partial: true`： ````python theme={null} completion = client.chat.completions.create( model="kimi-k2.6", messages=[ {"role": "user", "content": "用 Python 实现快速排序。"}, {"role": "assistant", "content": "```python\n", "partial": True} ] ) ```` 模型会从 \`\`\`\`python\n\` 之后继续生成代码，而不是先输出解释文字再写代码。 **常见用途** * 强制模型以特定格式开头（如 JSON 的 `{`、代码块的 \`\`\`\`python\`） * 角色扮演中保持角色名称前缀（配合 `name` 字段） * 在 `finish_reason="length"` 时，用相同的前缀续写被截断的内容 请勿将 Partial Mode 与 `response_format={"type": "json_object"}` 混用，否则可能获得预期外的模型回复。如需引导 JSON 输出，建议直接使用 [Structured Output](/docs/guide/response_format) 或单独设置 `partial: true` 并预填 `{`。 详见 [使用 Kimi API 的 Partial Mode](/docs/guide/use-partial-mode-feature-of-kimi-api)。 # 常见错误码说明 Source: https://platform.kimi.com/docs/api/errors 查询 Kimi API 的 HTTP 状态码、错误类型、常见原因和对应的排查处理方法。 当请求失败时，API 会返回包含错误信息的 JSON 响应： ```json theme={null} { "error": { "type": "content_filter", "message": "The request was rejected because it was considered high risk" } } ``` ## 错误列表 ## 400 — 请求错误 | error type | 典型 message | 原因与处理 | | - | - | - | | `content_filter` | The request was rejected because it was considered high risk | 输入或模型输出触发内容安全审查。请修改提示词，避免敏感/高风险内容。 | | `invalid_request_error` | 请求格式错误、缺少必填参数或参数类型非法。对照接口文档检查请求体。 | | | `invalid_request_error` | Input token length too long | 输入 tokens 超过模型最大上下文限制。缩短输入或换用更大上下文模型。 | | `invalid_request_error` | prompt tokens + max\_tokens 超过模型规格。减小 max\_tokens 或换模型。 | | | `invalid_request_error` | Invalid purpose: xxx, only \`file-extract\`, \`batch\`, \`batch\_output\`, \`lambda\`, \`image\` and \`video\` accepted | 文件上传的 purpose 字段不合法，需为上述取值之一。 | | `invalid_request_error` | File size is too large, max file size is 100MB, please confirm and re-upload the file | 上传文件超过 100MB 限制。压缩或拆分后重新上传。 | | `invalid_request_error` | File size is zero, please confirm and re-upload the file | 上传文件大小为 0。检查文件是否损坏或为空。 | | `invalid_request_error` | 上传文件总数超过上限。删除不再使用的早期文件后重试。 | | ## 401 — 认证错误 | error type | 典型 message | 原因与处理 | | - | - | - | | `invalid_authentication_error` | Invalid Authentication | API Key 无效或格式错误。请检查 `Authorization: Bearer <key>`。 | | `incorrect_api_key_error` | Incorrect API key provided | 未提供 API Key 或 Key 错误。 | **平台 Key 隔离说明**：`platform.kimi.com`（中国站）与 `platform.kimi.ai`（国际站）的账户、余额和 API Key 完全独立，混用会返回 401。请确认调用端点与 Key 所属平台一致。 ## 403 — 权限错误 | error type | 典型 message | 原因与处理 | | - | - | - | | `permission_denied_error` | The API you are accessing is not open | 该 API 暂未对当前账号开放。 | | `permission_denied_error` | You are not allowed to get other user info | 不允许访问其他用户信息。请检查接口权限范围。 | | `permission_denied_error` | Your IP is not allowed to access this organization | 调用 IP 不在组织白名单内（国际站常见）。联系管理员添加 IP。 | ## 404 — 资源不存在 | error type | 典型 message | 原因与处理 | | - | - | - | | `resource_not_found_error` | 模型不存在，或当前账号无权限访问该模型。检查 model 参数拼写及账号 tier。 | | ## 429 — 速率限制 / 额度不足 | error type | 典型 message | 原因与处理 | | - | - | - | | `engine_overloaded_error` | The engine is currently overloaded, please try again later | 服务节点负载较高（如高峰期容量压力）。按照 `Retry-After` 提示等待、降低并发并使用指数退避重试；该错误由服务端容量导致，充值或提升 Tier 不能直接消除。 | | `exceeded_current_quota_error` | 账户欠费或已停用。检查余额与账单。 | | | `exceeded_current_quota_error` | 账户 token 额度不足。充值后再试。 | | | `rate_limit_reached_error` | 触发组织级并发限制。降低并发或等待指定时间后重试。 | | | `rate_limit_reached_error` | 触发组织级 RPM（每分钟请求数）限制。按响应提示等待后重试。 | | | `rate_limit_reached_error` | 触发组织级 TPM（每分钟 token 数）限制。降低调用频率或升级 tier。 | | | `rate_limit_reached_error` | 触发组织级 TPD（每日 token 数）限制。次日恢复或升级套餐。 | | ## 499 / 500 / 503 / 504 — 连接与服务端错误 | HTTP | error type | 原因与处理 | | - | - | - | | 499 | `client_closed_request` | 客户端在服务端返回前断开连接。常见于流式响应被中间代理切断或用户主动取消。检查 KeepAlive 与超时设置。 | | 500 | `server_error` / `unexpected_output` | 服务端内部错误。请稍后重试；若持续出现，请附带 `request_id` 联系支持。 | | 503 | `server_unavailable` | 服务暂时不可用。稍后重试，通常与节点扩容/维护有关。 | | 504 | `504 Gateway Time-out` | 服务端 900 秒无响应，网关返回 HTML 超时页面。常见于非流式长请求，建议改用流式输出（`stream: true`）。 | ## 排障建议 * **收到 401**：先确认是否使用了正确平台的 API Key * **收到 429**：先根据 `error.type` 区分原因：节点过载请退避重试，组织限速可降低并发或升级用户等级，余额不足请充值，详见 [充值与限速](/docs/pricing/limits) * **收到 500**：请稍后重试，如持续出现请附带 `request_id` 联系支持团队 [api-service@moonshot.ai](mailto:api-service@moonshot.ai) * **收到 504**：服务端 900 秒无响应导致网关超时，建议改用流式输出（`stream: true`） # 计算 Token Source: https://platform.kimi.com/docs/api/estimate POST /v1/tokenizers/estimate-token-count 在发送请求前估算输入内容的 Token 数量。 estimate-token-count 的输入结构体和 chat completion 基本一致。 ```bash theme={null} curl 'https://api.moonshot.cn/v1/tokenizers/estimate-token-count' \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -d '{ "model": "kimi-k3", "messages": [ { "role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。" }, { "role": "user", "content": "你好，我叫李雷，1+1等于多少？" } ] }' ``` ```python theme={null} import os import base64 import json import requests api_key = os.environ.get("MOONSHOT_API_KEY") endpoint = "https://api.moonshot.cn/v1/tokenizers/estimate-token-count" image_path = "image.png" with open(image_path, "rb") as f: image_data = f.read() # 我们使用标准库 base64.b64encode 函数将图片编码成 base64 格式的 image_url image_url = f"data:image/{os.path.splitext(image_path)[1].lstrip('.')};base64,{base64.b64encode(image_data).decode('utf-8')}" payload = { "model": "kimi-k3", "messages": [ { "role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。" }, { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": image_url, }, }, { "type": "text", "text": "请描述图片的内容。", }, ], } ] } response = requests.post( endpoint, headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" }, data=json.dumps(payload) ) print(response.json()) ``` 当没有 error 字段，可以取 `data.total_tokens` 作为计算结果。 # 获取文件内容 Source: https://platform.kimi.com/docs/api/files-content GET /v1/files/{file_id}/content 获取以 file-extract 用途上传的文件的提取内容，返回 Markdown 格式文本。 ```python theme={null} # 注意，之前 retrieve_content api 在最新版本标记了 warning, 可以用下面这行代替 # 如果是旧版本，可以用 retrieve_content file_content = client.files.content(file_id=file_object.id).text ``` ```bash theme={null} curl https://api.moonshot.cn/v1/files/{file_id}/content \ -H "Authorization: Bearer $MOONSHOT_API_KEY" ``` 提取结果为 Markdown 格式文本，而非纯文本： * 源文档中的加粗、标题、列表、表格等格式会以 Markdown 语法呈现，例如加粗文本以 `**` 包裹。 * 列表等结构边界处可能出现 `{=html}` 代码块包裹的 `` 空注释块，属于正常输出，可安全删除。 * 如下游需要纯文本，可将结果按 Markdown 解析后提取纯文本，或用正则剔除上述标记。 # 删除文件 Source: https://platform.kimi.com/docs/api/files-delete DELETE /v1/files/{file_id} 删除指定的已上传文件。 删除一个已上传的文件。删除成功后，该文件将不再占用存储空间，也无法继续用于对话或 Batch 等场景。 ```python showLineNumbers expandable theme={null} import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("MOONSHOT_API_KEY"), base_url="https://api.moonshot.cn/v1", ) # 删除指定文件 delete_result = client.files.delete(file_id="file_xxx") print(delete_result) ``` ```bash showLineNumbers theme={null} curl -X DELETE https://api.moonshot.cn/v1/files/file_xxx \ -H "Authorization: Bearer $MOONSHOT_API_KEY" ``` ```js showLineNumbers expandable theme={null} const OpenAI = require("openai"); const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: "https://api.moonshot.cn/v1", }); async function main() { const deleteResult = await client.files.delete({ file_id: "file_xxx", }); console.log(deleteResult); } main(); ``` 删除文件接口返回一个 JSON 对象，包含以下字段： | 字段 | 类型 | 说明 | | - | - | - | | `id` | string | 已删除文件的标识符 | | `object` | string | 固定为 `"file"` | | `deleted` | boolean | 文件是否删除成功 | **响应示例** ```json theme={null} { "id": "file_xxx", "object": "file", "deleted": true } ``` 删除操作不可撤销。已上传文件会占用组织总存储配额（默认 10 GiB）；达到配额上限后，新的上传会被拒绝。删除不再使用的文件可以释放配额。 如果文件不存在或已被删除，接口将返回 `404` 错误。请确认 `file_id` 正确无误。 # 列出文件 Source: https://platform.kimi.com/docs/api/files-list GET /v1/files 列出当前账户已上传的文件。 ```python theme={null} file_list = client.files.list() for file in file_list.data: print(file) # 查看每个文件的信息 ``` # 获取文件信息 Source: https://platform.kimi.com/docs/api/files-retrieve GET /v1/files/{file_id} 获取指定文件的元信息。 ```python theme={null} client.files.retrieve(file_id=file_id) # FileObject( # id='file_clg681objj8g9m7n4je0', # bytes=761790, # created_at=1700815879, # filename='xlnet.pdf', # object='file', # purpose='file-extract', # status='ok', status_details='') ``` # 上传文件 Source: https://platform.kimi.com/docs/api/files-upload POST /v1/files 上传文件用于文本内容抽取、图片理解或视频理解，支持 pdf、doc、txt 等文本类格式。 单文件大小上限为 100 MiB，超限时返回文件过大错误。文件个数不再受限，改为按组织总存储量限制，默认 10 GiB。文件解析服务限时免费，请求高峰期平台可能会有限流策略。 文件接口支持以下格式：`.pdf`、`.txt`、`.csv`、`.doc`、`.docx`、`.xls`、`.xlsx`、`.ppt`、`.pptx`、`.md`、`.dot`、`.epub`、`.html`、`.json`、`.mobi`、`.log`、`.go`、`.h`、`.c`、`.cpp`、`.cxx`、`.cc`、`.cs`、`.java`、`.js`、`.css`、`.jsp`、`.php`、`.py`、`.py3`、`.asp`、`.yaml`、`.yml`、`.ini`、`.conf`、`.ts`、`.tsx` 等。 注意：图片文件不再支持内容抽取（`file-extract`）。如需图片理解，请使用 `purpose="image"` 上传图片，详见[使用视觉模型](/docs/guide/use-kimi-vision-model)。 上传文件时选择 `purpose="file-extract"`，随后可以让模型获取文件中的信息作为上下文。抽取结果为 Markdown 格式文本（加粗、标题、列表等以 Markdown 语法呈现），可直接放入 messages，详见[获取文件内容](/docs/api/files-content)。 ```python showLineNumbers expandable theme={null} from pathlib import Path import os from openai import OpenAI client = OpenAI( api_key=os.environ["MOONSHOT_API_KEY"], base_url = "https://api.moonshot.cn/v1", ) # xlnet.pdf 是一个示例文件, 我们支持 pdf, doc 等文本类格式 file_object = client.files.create(file=Path("xlnet.pdf"), purpose="file-extract") # 获取结果 # 注意，之前 retrieve_content api 在最新版本标记了 warning, 可以用下面这行代替 # 如果是旧版本，可以用 retrieve_content file_content = client.files.content(file_id=file_object.id).text # 把它放进请求中 messages = [ { "role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。", }, { "role": "system", "content": file_content, }, {"role": "user", "content": "请简单介绍 xlnet.pdf 讲了啥"}, ] # 然后调用 chat-completion, 获取 Kimi 的回答 completion = client.chat.completions.create( model="kimi-k3", messages=messages, temperature=0.6, ) print(completion.choices[0].message) ``` ```bash showLineNumbers theme={null} # xlnet.pdf 是一个示例文件 curl https://api.moonshot.cn/v1/files \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -F purpose="file-extract" \ -F file="@xlnet.pdf" ``` ```js showLineNumbers expandable theme={null} const OpenAI = require("openai"); const fs = require("fs") const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: "https://api.moonshot.cn/v1", }); async function main() { // xlnet.pdf 是一个示例文件, 我们支持 pdf, doc 等文本类格式 let file_object = await client.files.create({ file: fs.createReadStream("xlnet.pdf"), purpose: "file-extract" }) // 注意，之前 retrieve_content api 在最新版本标记了 warning, 可以用下面这行代替 // 如果是旧版本，可以用 retrieve_content let file_content = await (await client.files.content(file_object.id)).text() // 把它放进请求中 let messages = [ { "role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。", }, { "role": "system", "content": file_content, }, {"role": "user", "content": "请简单介绍 xlnet.pdf 讲了啥"}, ] const completion = await client.chat.completions.create({ model: "kimi-k3", messages: messages, temperature: 0.6 }); console.log(completion.choices[0].message.content); } main(); ``` 其中 `$MOONSHOT_API_KEY` 部分需要替换为您自己的 API Key。或者在调用前给它设置好环境变量。 如果你想一次性上传多个文件，并根据这些文件与 Kimi 对话，你可以参考如下示例： ```python expandable theme={null} from typing import * import os import json from pathlib import Path from openai import OpenAI client = OpenAI( base_url="https://api.moonshot.cn/v1", api_key=os.environ["MOONSHOT_API_KEY"], ) def upload_files(files: List[str]) -> List[Dict[str, Any]]: """ upload_files 会将传入的文件（路径）全部通过文件上传接口 '/v1/files' 上传，并获取上传后的 文件内容生成文件 messages。每个文件会是一个独立的 message，这些 message 的 role 均为 system，Kimi 大模型会正确识别这些 system messages 中的文件内容。 :param files: 一个包含要上传文件的路径的列表，路径可以是绝对路径也可以是相对路径，请使用字符串 的形式传递文件路径。 :return: 一个包含了文件内容的 messages 列表，请将这些 messages 加入到 Context 中， 即请求 `/v1/chat/completions` 接口时的 messages 参数中。 """ messages = [] for file in files: file_object = client.files.create(file=Path(file), purpose="file-extract") file_content = client.files.content(file_id=file_object.id).text messages.append({ "role": "system", "content": file_content, }) return messages def main(): file_messages = upload_files(files=["upload_files.py"]) messages = [ *file_messages, { "role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，" "准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不" "可翻译成其他语言。", }, { "role": "user", "content": "总结一下这些文件的内容。", }, ] print(json.dumps(messages, indent=2, ensure_ascii=False)) completion = client.chat.completions.create( model="kimi-k3", messages=messages, ) print(completion.choices[0].message.content) if __name__ == '__main__': main() ``` 上传文件时，选择 `purpose="image"` 或 `purpose="video"`，上传后的图片或视频可以用于模型的原生理解。 请参阅[使用视觉模型](/docs/guide/use-kimi-vision-model)了解完整示例。 # 列出模型 Source: https://platform.kimi.com/docs/api/list-models GET /v1/models 列出当前可用的模型及其 ID。 列出当前可用的所有模型，包含模型 ID、上下文长度及能力标识等信息。建议在调用对话补全前查询本接口，以确认目标模型是否可用及具备对应能力。 ```python python expandable theme={null} import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("MOONSHOT_API_KEY"), base_url="https://api.moonshot.cn/v1", ) models = client.models.list() print(models.data) ``` ```bash curl expandable theme={null} curl https://api.moonshot.cn/v1/models \ -H "Authorization: Bearer $MOONSHOT_API_KEY" ``` ```javascript node.js expandable theme={null} const OpenAI = require("openai"); const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: "https://api.moonshot.cn/v1", }); async function main() { const models = await client.models.list(); console.log(models.data); } main(); ``` 响应为一个对象，包含以下字段： | 字段 | 类型 | 说明 | | - | - | - | | `object` | string | 对象类型，固定为 `"list"` | | `data` | array\[object] | 模型列表，每个元素为一个模型对象 | `data` 数组中每个模型对象的字段说明： | 字段 | 类型 | 说明 | | - | - | - | | `id` | string | 模型 ID，例如 `kimi-k3` | | `object` | string | 对象类型，固定为 `"model"` | | `created` | integer | 模型创建时的 Unix 时间戳 | | `owned_by` | string | 模型所有者标识，例如 `"moonshot"` | | `context_length` | integer | 模型支持的最大上下文长度（tokens） | | `supports_image_in` | boolean | 是否支持图片输入 | | `supports_video_in` | boolean | 是否支持视频输入 | | `supports_reasoning` | boolean | 是否支持深度思考 | 模型列表及能力标识可能随平台更新而变化。若调用对话补全时收到 `resource_not_found_error`（404），说明模型不存在或当前账号无权限访问，请检查 `model` 参数拼写及账号 tier。 本接口需要有效的 API Key 进行认证。若收到 401 错误，请检查 `Authorization` 请求头是否为 `Bearer `，并确认 API Key 与调用端点所属平台一致（`platform.kimi.com` 与 `platform.kimi.ai` 的 Key 不可混用）。 # Messages API Source: https://platform.kimi.com/docs/api/messages POST /anthropic/v1/messages 以 Anthropic Messages API 兼容的格式调用 Kimi 模型，支持流式输出、工具调用、图片输入、思考与结构化输出。 以 Anthropic Messages API 兼容的格式调用 Kimi 模型。已经在使用 Anthropic SDK、Claude Code 等工具的开发者，只需把 base URL 指向 `https://api.moonshot.cn/anthropic`，即可直接调用 Kimi 模型。 通过顶层 `cache_control` 控制上下文缓存的写入行为（仅顶层传入时生效，`messages` 消息体内的 `cache_control` 标记会被忽略）： | 参数 | 类型 | 说明 | | - | - | - | | `cache_control` | object | 上下文缓存写入选项，仅顶层传入时生效；不传时本次请求只读取缓存（`5m` 档）不写入 | | `cache_control.type` | `"ephemeral"` | 缓存类型，固定为 `ephemeral` | | `cache_control.ttl` | `"5m"` \| `"1h"` | 缓存写入的有效期，仅支持 `5m`、`1h` 两档（默认 `5m`），两档缓存相互独立 | * 传入顶层 `cache_control`：将请求前缀按指定 TTL 写入缓存。 * 不传 `cache_control`：本次请求只尝试读取缓存（`5m` 档），不写入缓存，不产生缓存写入费用。 ```json theme={null} { "model": "kimi-k3", "cache_control": { "type": "ephemeral", "ttl": "1h" }, "messages": [{"role": "user", "content": "你好"}] } ``` **行为说明** * 缓存以组织（org）为粒度隔离，组织之间不共享缓存。 * 相同前缀的请求在缓存有效期内命中后，缓存的有效期会按原 TTL 刷新；命中部分只收取缓存读取费用，不再收取缓存写入费用。 * 缓存写入按 TTL 分别计费，价格详见[产品定价](/docs/pricing/chat)。 * 不支持手动清除缓存，已缓存的前缀在至少 5 分钟不活动后自动过期。 **用量字段** | 字段 | 说明 | | - | - | | `usage.input_tokens` | 既未命中缓存、也未用于创建缓存条目的输入 Token 数 | | `usage.cache_read_input_tokens` | 命中缓存的输入 Token 数（缓存读取） | | `usage.cache_creation_input_tokens` | 创建新缓存条目时写入缓存的输入 Token 数（缓存写入） | | `usage.cache_creation.ephemeral_5m_input_tokens` | 写入 `5m` 档缓存的输入 Token 数 | | `usage.cache_creation.ephemeral_1h_input_tokens` | 写入 `1h` 档缓存的输入 Token 数 | 总输入 = `input_tokens` + `cache_read_input_tokens` + `cache_creation_input_tokens`。 本页 `input_tokens` 的口径与 Chat Completions / Responses API 不同：这两个 API 的 `prompt_tokens` / `input_tokens` 始终为总输入，缓存读写部分在各自的 details 字段中拆分。 Context Caching 的机制背景详见[上下文缓存指南](/docs/guide/context-caching)。 # 模型参数参考 Source: https://platform.kimi.com/docs/api/models-overview 对比 Kimi 各模型系列在 Chat Completions API 中的默认参数、可调范围与使用约束。 不同模型系列对 Chat Completions API 参数有不同的默认值和约束。 ## 参数对比 当 `temperature` 接近 0 时，`n` 只能为 1，否则将返回 `invalid_request_error`。 ## 模型参数配置差异 切换模型时，除了替换 `model` 字段，还需要注意各模型对请求参数的支持范围和默认值不同： | 参数 | `kimi-k3` | `kimi-k2.7-code` | `kimi-k2.6` | | - | - | - | - | | 上下文窗口 | 1M tokens | 256K tokens | 256K tokens | | `thinking` | — | 可省略；显式设置时仅接受 `{"type":"enabled","keep":"all"}` | `{"type":"enabled"}`（默认）、`{"type":"disabled"}`、`{"type":"enabled","keep":"all"}` | | `reasoning_effort` | `"low"` / `"high"` / `"max"`（默认 `"max"`） | 不支持 | 不支持 | | `tool_choice` | `auto` / `none` / `required` | 不支持 `required` | 不支持 `required` | | `temperature` | 固定 `1.0` | 固定 `1.0` | 思考 `1.0` / 非思考 `0.6` | | `top_p` | 固定 `0.95` | 固定 `0.95` | 固定 `0.95` | | `n` | 固定 `1` | 固定 `1` | 固定 `1` | | `presence_penalty` / `frequency_penalty` | 固定 `0` | 固定 `0` | 固定 `0` | 表中"固定"表示该参数不可修改：传入其他值会报错，建议不要显式传入。 ### `thinking` `thinking` 是 K2.x 专属请求参数： * `kimi-k2.6`：支持 `{"type": "enabled"}`（默认）、`{"type": "disabled"}`、`{"type": "enabled", "keep": "all"}` 三种配置。 * `kimi-k2.7-code`：思考默认开启，仅支持 `{"type": "enabled", "keep": "all"}`，传入其他配置会报错。从 `kimi-k2.6` 切换时，需要按 Preserved Thinking 的要求在 `messages` 中回传历史 `reasoning_content`。 详见[使用思考模式](/docs/guide/use-thinking-models)。 ### `reasoning_effort` K3 始终进行推理思考且保留式思考（Preserved Thinking）始终开启。通过请求顶层 `reasoning_effort` 配置推理强度，支持 `"low"` / `"high"` / `"max"` 三档，默认 `"max"`。详见[推理强度](/docs/guide/use-reasoning-effort)。 切换档位会破坏前缀缓存命中，建议在会话开始前确定 `effort` 档位，避免中途切换。 ### `tool_choice` `kimi-k3` 支持 `auto` / `none` / `required` 三档；`kimi-k2.6` 与 `kimi-k2.7-code` 不支持 `required`，传入会报错。详见[工具调用约束](/docs/guide/use-tool-choice)。 ### `temperature` * `kimi-k2.6`：思考模式固定 `1.0`，非思考模式固定 `0.6`，传入其他值报错； * `kimi-k2.7-code`：固定 `1.0`，传入其他值报错。 * `kimi-k3`：固定 `1.0`，传入其他值报错。 建议调用以上模型时不要显式传入 `temperature`。 `kimi-k2.7-code-highspeed` 与 `kimi-k2.7-code` 为同一模型、参数约束完全一致，仅输出速度不同。 ### 常见问题 **从 `kimi-k2.6` 切换到 `kimi-k3`，需要改代码吗？** 将 `model` 替换为 `kimi-k3`，并移除 K2.x 的 `thinking` 配置；如需显式设置推理强度，使用顶层 `reasoning_effort`。K3 的多轮对话和工具调用需要把 API 返回的完整 assistant message 原样回传到 `messages`，包括可能返回的 `reasoning_content`。 **从 `kimi-k2.7-code` 切换到 `kimi-k3`，需要改代码吗？** 替换 `model` 即可，并继续原样回传完整 assistant message；如需显式设置推理强度，使用顶层 `reasoning_effort`。 **原来代码里用的是 OpenAI 的 `reasoning_effort`，切到 `kimi-k3` 需要改吗？** 不需要。K3 支持顶层 `reasoning_effort`，可选值为 `"low"` / `"high"` / `"max"`，默认 `"max"`。 **`tool_choice: "required"` 在 `kimi-k2.6` / `kimi-k2.7-code` 上能用吗？** 不能。这两个模型不支持 `required`，传入会报错；该档位仅 `kimi-k3` 支持。 ## Kimi K2.7 Code 系列 — thinking 参数 `kimi-k2.7-code` 系列包含 `kimi-k2.7-code` 及其高速版 `kimi-k2.7-code-highspeed`，二者为同一模型、参数约束完全一致（含上方表格与 `thinking` 行为），仅输出速度不同，下文统称 `kimi-k2.7-code`。 `kimi-k2.7-code` 面向代码场景，除 `thinking` 外的参数约束与 `kimi-k2.6` 完全一致。与 `kimi-k2.6` 不同的是，它 **始终开启思考、不可禁用**（传入 `{"type": "disabled"}` 会报错），且 **Preserved Thinking 始终开启**（`thinking.keep` 不传或传 `"all"` 都按 `"all"` 处理，传入其他非法值会报错）。因此调用时无需传入 `thinking` 参数，只需切换 `model` 即可，模型始终输出 `reasoning_content`。详细用法见[使用思考模式](/docs/guide/use-thinking-models)。 ## Kimi K2.6 — thinking 参数 Kimi K2.6 支持通过 `thinking` 参数控制是否启用深度思考。接受 `{"type": "enabled"}` 或 `{"type": "disabled"}`。 由于 OpenAI SDK 没有原生的 `thinking` 参数，需要使用 `extra_body` 传递： ```python Python theme={null} completion = client.chat.completions.create( model="kimi-k2.6", messages=[ {"role": "user", "content": "你好"} ], extra_body={ "thinking": {"type": "disabled"} }, max_tokens=1024*32, ) ``` ```bash cURL theme={null} curl https://api.moonshot.cn/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -d '{ "model": "kimi-k2.6", "messages": [ {"role": "user", "content": "你好"} ], "thinking": {"type": "disabled"} }' ``` # API 概述 Source: https://platform.kimi.com/docs/api/overview 查看 Kimi API 的服务地址、认证方式、请求格式、兼容性和主要接口入口。 ## 服务地址 ``` https://api.moonshot.cn ``` 不同兼容协议的 `base_url` 不同，见下方「协议兼容性」。 ## 协议兼容性 Kimi API 兼容三种 API 格式，您可以直接复用对应的官方 SDK 和工具： | 兼容 API | base\_url | 接口 | 可用 SDK / 工具 | | - | - | - | - | | OpenAI Chat Completions | `https://api.moonshot.cn/v1` | [`/chat/completions`](/docs/api/chat) | OpenAI 官方 SDK（Python / Node.js），以及 LangChain、Dify、Coze 等第三方工具和框架 | | OpenAI Responses | `https://api.moonshot.cn/v1` | [`/responses`](/docs/api/responses) | OpenAI 官方 SDK（Python / Node.js） | | Anthropic Messages | `https://api.moonshot.cn/anthropic` | [`/messages`](/docs/api/messages) | Anthropic 官方 SDK、Claude Code 等工具 | 如果您的项目原本在使用 OpenAI 或 Anthropic 的官方 API，只需将 `base_url` 和 API Key 替换为 Kimi 的配置即可迁移，无需修改其他代码。 使用 OpenAI 兼容接口时，部分参数为 Kimi 专有扩展：`thinking` 参数需要通过 SDK 的 `extra_body` 传递；`partial` 是写在 messages 中 assistant 消息上的字段（`"partial": true`），不是顶层请求参数。详见[工具调用](/docs/api/tool-use)和 [Partial Mode](/docs/api/partial)。 ## 认证 所有 API 请求需要在 HTTP 头中携带 API Key： ``` Authorization: Bearer $MOONSHOT_API_KEY ``` API Key 可在 [Kimi 开放平台控制台](https://platform.kimi.com/console/api-keys) 创建和管理。 API Key 是敏感信息，请妥善保管。不要在客户端代码、公开仓库或日志中暴露。建议通过环境变量管理。 使用官方 SDK 时，在初始化时传入 API Key 和对应协议的 `base_url`。 OpenAI 兼容接口： ```python Python theme={null} import os from openai import OpenAI client = OpenAI( api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.cn/v1", ) ``` ```javascript Node.js theme={null} const OpenAI = require("openai"); const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: "https://api.moonshot.cn/v1", }); ``` Anthropic 兼容接口： ```python Python theme={null} import os from anthropic import Anthropic client = Anthropic( api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.cn/anthropic", ) ``` ```javascript Node.js theme={null} const Anthropic = require("@anthropic-ai/sdk"); const client = new Anthropic({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: "https://api.moonshot.cn/anthropic", }); ``` ## 错误处理 请求失败时返回包含 `error.type` 和 `error.message` 的 JSON 错误响应，完整的错误类型、错误消息和排障建议请参阅[错误说明](/docs/api/errors)。 ## API 端点一览 | 端点 | 方法 | 协议 | 说明 | | - | - | - | - | | `/v1/chat/completions` | POST | OpenAI | [创建对话补全](/docs/api/chat) | | `/v1/responses` | POST | OpenAI | [Responses API](/docs/api/responses) | | `/anthropic/v1/messages` | POST | Anthropic | [Messages API](/docs/api/messages) | | `/v1/models` | GET | OpenAI | [列出模型](/docs/api/list-models) | | `/v1/tokenizers/estimate-token-count` | POST | OpenAI | [计算 Token](/docs/api/estimate) | | `/v1/users/me/balance` | GET | OpenAI | [查询余额](/docs/api/balance) | | `/v1/tools/search` | POST | Kimi | [联网搜索 Basic](/docs/api/tools-search) | | `/v1/tools/search_pro` | POST | Kimi | [联网搜索 Pro](/docs/api/tools-search-pro) | | `/v1/tools/fetch` | POST | Kimi | [网页抓取](/docs/api/tools-fetch) | | `/v1/files` | POST | OpenAI | [上传文件](/docs/api/files-upload) | | `/v1/files` | GET | OpenAI | [列出文件](/docs/api/files-list) | | `/v1/files/{file_id}` | GET | OpenAI | [获取文件信息](/docs/api/files-retrieve) | | `/v1/files/{file_id}` | DELETE | OpenAI | [删除文件](/docs/api/files-delete) | | `/v1/files/{file_id}/content` | GET | OpenAI | [获取文件内容](/docs/api/files-content) | | `/v1/batches` | POST | OpenAI | [创建批处理任务](/docs/api/batch-create) | | `/v1/batches` | GET | OpenAI | [列出批处理任务](/docs/api/batch-list) | | `/v1/batches/{batch_id}` | GET | OpenAI | [获取批处理任务详情](/docs/api/batch-retrieve) | | `/v1/batches/{batch_id}/cancel` | POST | OpenAI | [取消批处理任务](/docs/api/batch-cancel) | ## 下一步 发送第一个 API 请求 OpenAI Responses 兼容接口 Anthropic Messages 兼容接口 查看当前可用模型 # Responses API Source: https://platform.kimi.com/docs/api/responses POST /v1/responses 创建一次模型响应。传入文本或图片，生成文本或 JSON 输出；也可以让模型调用你定义的函数工具，或使用服务端执行的联网搜索。 ```python Python theme={null} import os from openai import OpenAI client = OpenAI( api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.cn/v1", ) response = client.responses.create( model="kimi-k3", instructions="你是 Kimi，一个由 Moonshot AI 提供的人工智能助手。", input="用一句话解释什么是上下文缓存。", ) print(response.output_text) ``` ```javascript Node.js theme={null} import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: "https://api.moonshot.cn/v1", }); const response = await client.responses.create({ model: "kimi-k3", instructions: "你是 Kimi，一个由 Moonshot AI 提供的人工智能助手。", input: "用一句话解释什么是上下文缓存。", }); console.log(response.output_text); ``` ```bash cURL theme={null} curl https://api.moonshot.cn/v1/responses \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $MOONSHOT_API_KEY" \ --data '{ "model": "kimi-k3", "instructions": "你是 Kimi，一个由 Moonshot AI 提供的人工智能助手。", "input": "用一句话解释什么是上下文缓存。" }' ``` `tools` 支持四种工具类型：`function`、`namespace`、`custom`（仅 `apply_patch`）与 `web_search`，其他类型不支持。前三种由你在本地执行：模型返回调用请求，你执行后把结果回传；`web_search` 由服务端执行，无需你处理。 **函数调用** 通过 `tools` 传入 JSON Schema 定义的函数，模型可决定在适当时机调用它们： ```json theme={null} { "model": "kimi-k3", "input": "北京今天天气怎么样？", "tools": [ { "type": "function", "name": "get_weather", "description": "获取指定城市的天气", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名称"} }, "required": ["city"] } } ] } ``` 模型决定调用时，`output` 中会包含 `function_call` item，`arguments` 是参数的 JSON 字符串： ```json theme={null} { "type": "function_call", "id": "fc_IrcmDq5JNO0JhWdEpsuZnL9J", "status": "completed", "call_id": "get_weather_0", "name": "get_weather", "arguments": "{\"city\":\"北京\"}" } ``` 在本地执行后，把上一轮的 `output` 原样追加到 `input`，再追加一条 `function_call_output`（`call_id` 必须与 `function_call` 中的一致），发起下一次请求： ```json theme={null} { "model": "kimi-k3", "input": [ {"type": "message", "role": "user", "content": "北京今天天气怎么样？"}, {"type": "function_call", "call_id": "get_weather_0", "name": "get_weather", "arguments": "{\"city\":\"北京\"}"}, {"type": "function_call_output", "call_id": "get_weather_0", "output": "晴，25°C"} ], "tools": [ { "type": "function", "name": "get_weather", "description": "获取指定城市的天气", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名称"} }, "required": ["city"] } } ] } ``` **联网搜索** 在 `tools` 中加入 `{"type": "web_search"}`，服务端会先根据输入判断是否需要搜索，需要时执行搜索并把结果注入模型上下文，模型基于搜索结果作答： ```json theme={null} { "model": "kimi-k3", "input": "今天有什么重大新闻？", "tools": [ {"type": "web_search"} ] } ``` 执行了搜索时，`output` 最前面会多出一个 `web_search_call` item。在 `include` 中加入 `web_search_call.action.sources` 可以拿到搜索命中的网页来源： ```json theme={null} { "type": "web_search_call", "id": "ws_dackjbcdo9rs73fo3oig", "status": "completed", "action": { "type": "search", "query": "2026年9月3日 重大新闻", "sources": [ {"type": "url", "url": "https://example.com/news/1", "title": "新闻标题"} ] } } ``` Kimi API 会对重复的请求前缀自动启用上下文缓存，命中部分以更低价格计费且响应更快。通过 `prompt_cache_options` 可以控制缓存写入行为： | 参数 | 类型 | 说明 | | - | - | - | | `prompt_cache_options` | object | 上下文缓存写入选项。不传时默认开启缓存写入（`5m` 档） | | `prompt_cache_options.mode` | `"implicit"` | 缓存写入模式，仅支持 `implicit`：自动将请求前缀写入缓存 | | `prompt_cache_options.ttl` | `"5m"` \| `"1h"` | 缓存写入的有效期，仅支持 `5m`、`1h` 两档（默认 `5m`），两档缓存相互独立 | ```json theme={null} { "model": "kimi-k3", "input": "你好", "prompt_cache_options": { "mode": "implicit", "ttl": "1h" } } ``` 不传 `prompt_cache_options` 时，默认自动开启缓存写入（`5m` 档）。响应顶层会回显服务端实际应用的 `prompt_cache_options`，以其返回为准。 **行为说明** * 缓存以组织（org）为粒度隔离，组织之间不共享缓存。 * 相同前缀的请求在缓存有效期内命中后，缓存的有效期会按原 TTL 刷新；命中部分只收取缓存读取费用，不再收取缓存写入费用。 * 缓存写入按 TTL 分别计费，价格详见[产品定价](/docs/pricing/chat)。 * 不支持手动清除缓存，已缓存的前缀在至少 5 分钟不活动后自动过期。 * 暂不支持显式缓存断点：`content` 中出现 `prompt_cache_breakpoint` 时请求会被拒绝（HTTP 400）。 **用量字段** `usage.input_tokens` 始终为总输入 Token 数，其内部分类通过 `input_tokens_details` 返回： | 字段 | 说明 | | - | - | | `usage.input_tokens_details.cached_tokens` | 命中缓存的 Token 数量（缓存读取） | | `usage.input_tokens_details.cache_write_tokens` | 本次写入缓存的 Token 数量（缓存写入） | `cached_tokens`、`cache_write_tokens` 与未缓存部分互斥，三者之和等于 `input_tokens`，即未缓存部分 = `input_tokens` − `cached_tokens` − `cache_write_tokens`。 Context Caching 的机制背景详见[上下文缓存指南](/docs/guide/context-caching)。 # 校验请求签名 Source: https://platform.kimi.com/docs/api/signatures-verify POST /v1/signatures/verify 校验 Kimi API 返回的请求签名，证明请求确实由 Kimi API 处理且请求的是指定模型，而非被转发到其他服务。 请求签名（Request Signature）用于证明一次请求确实到达了 Kimi API 本身，而不是被中间层转发到了其他服务或替换了模型。持有 nonce、时间戳、模型和签名的任何一方，都可以通过本接口验证 Kimi API 是否在该时间点以指定模型接受了这个请求，例如向用户或第三方证明服务背后调用的是 Kimi 官方 API、核验代理层没有偷换模型，或用于事后审计与争议举证。 调用 [Chat Completions](/docs/api/chat)、[Responses](/docs/api/responses) 或 [Messages](/docs/api/messages) API 时，在请求头 `X-Msh-Request-Nonce` 中携带一个随机 nonce（推荐使用 UUID v4），响应头中就会返回 `Msh-Request-Timestamp`（Kimi API 接受该请求时的 Unix 毫秒时间戳）和 `Msh-Request-Signature`（以 `reqsigv1_` 为前缀的签名 token），流式与非流式均支持。之后将 nonce、timestamp、请求中的 `model` 和 signature 提交到本接口，签名与三者完全一致时返回 `valid: true`，否则返回 `valid: false`。 签名只证明 Kimi API 在该时间点接受了这个 nonce 和请求模型，不证明请求最终成功或响应内容完整。服务端不记录 nonce，重放同一组参数仍会返回 `valid: true`，防重放和有效时间窗口需由调用方自行控制。 ```python python expandable theme={null} import os import uuid import requests from openai import OpenAI client = OpenAI( api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.cn/v1", ) nonce: str = str(uuid.uuid4()) model: str = "kimi-k2.7-code" # 1. 携带 X-Msh-Request-Nonce 调用模型接口，并读取响应头 raw = client.chat.completions.with_raw_response.create( model=model, messages=[{"role": "user", "content": "你好"}], extra_headers={"X-Msh-Request-Nonce": nonce}, ) timestamp: int = int(raw.headers["Msh-Request-Timestamp"]) signature: str = raw.headers["Msh-Request-Signature"] # 2. 校验签名 verify = requests.post( "https://api.moonshot.cn/v1/signatures/verify", headers={ "Authorization": f"Bearer {os.environ['MOONSHOT_API_KEY']}", "Content-Type": "application/json", }, json={ "nonce": nonce, "timestamp": timestamp, "model": model, "signature": signature, }, ) print(verify.json()) # {"valid": true} ``` ```bash curl expandable theme={null} NONCE="$(uuidgen)" MODEL="kimi-k2.7-code" # 1. 携带 X-Msh-Request-Nonce 调用模型接口，并把响应头保存到文件 curl -sS -D response.headers -o response.json \ https://api.moonshot.cn/v1/chat/completions \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Msh-Request-Nonce: $NONCE" \ -d "{\"model\": \"$MODEL\", \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}]}" TIMESTAMP="$(awk -F': ' 'tolower($1)=="msh-request-timestamp" {gsub("\\r", "", $2); print $2}' response.headers)" SIGNATURE="$(awk -F': ' 'tolower($1)=="msh-request-signature" {gsub("\\r", "", $2); print $2}' response.headers)" # 2. 校验签名 curl -sS https://api.moonshot.cn/v1/signatures/verify \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"nonce\": \"$NONCE\", \"timestamp\": $TIMESTAMP, \"model\": \"$MODEL\", \"signature\": \"$SIGNATURE\"}" ``` ```javascript node.js expandable theme={null} const { randomUUID } = require("crypto"); const OpenAI = require("openai"); const apiKey = process.env.MOONSHOT_API_KEY; const client = new OpenAI({ apiKey, baseURL: "https://api.moonshot.cn/v1", }); async function main() { const nonce = randomUUID(); const model = "kimi-k2.7-code"; // 1. 携带 X-Msh-Request-Nonce 调用模型接口，并读取响应头 const { response } = await client.chat.completions .create( { model, messages: [{ role: "user", content: "你好" }] }, { headers: { "X-Msh-Request-Nonce": nonce } }, ) .withResponse(); const timestamp = Number(response.headers.get("Msh-Request-Timestamp")); const signature = response.headers.get("Msh-Request-Signature"); // 2. 校验签名 const verify = await fetch("https://api.moonshot.cn/v1/signatures/verify", { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json", }, body: JSON.stringify({ nonce, timestamp, model, signature }), }); console.log(await verify.json()); // { valid: true } } main(); ``` # 网页抓取 Source: https://platform.kimi.com/docs/api/tools-fetch POST /v1/tools/fetch 通过 /v1/tools/fetch 接口抓取指定 URL 的网页内容，返回页面标题与 Markdown 格式正文。 抓取指定 URL 的网页内容，返回页面标题与 Markdown 格式正文，适用于网页阅读、资料整理等内容提取场景。 仅支持 `http` 和 `https` 协议的 URL。触发安全风控的 URL 会返回 403 `security_risk` 错误；页面无可提取正文时返回 404 `markdown_not_found` 错误。 ```python python expandable theme={null} import os import requests api_key = os.environ.get("MOONSHOT_API_KEY") url = "https://api.moonshot.cn/v1/tools/fetch" response = requests.post( url, headers={"Authorization": f"Bearer {api_key}"}, json={"url": "https://platform.kimi.com/docs/api/overview"}, ) print(response.json()) ``` ```bash curl expandable theme={null} curl https://api.moonshot.cn/v1/tools/fetch \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -d '{"url": "https://platform.kimi.com/docs/api/overview"}' ``` ```javascript node.js expandable theme={null} const apiKey = process.env.MOONSHOT_API_KEY; async function main() { const response = await fetch("https://api.moonshot.cn/v1/tools/fetch", { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}`, }, body: JSON.stringify({ url: "https://platform.kimi.com/docs/api/overview", }), }); const data = await response.json(); console.log(data); } main(); ``` | 字段 | 类型 | 说明 | | - | - | - | | `url` | string | 抓取 URL | | `markdown` | string | 抓取结果的 Markdown 内容；文本与图片按在页面中出现的顺序拼接，图片以占位符形式嵌入（格式见下方示例），各段之间以空行分隔 | | `title` | string | 页面标题 | **响应示例** ```json theme={null} { "url": "https://platform.kimi.com/docs/api/overview", "markdown": "# API 概述\n\nKimi API 开放平台文档入口。", "title": "API 概述 - Kimi API 开放平台" } ``` **markdown 内容形态示例** ```text theme={null} # API 概述 Kimi API 开放平台文档入口。 ![image1](https://platform.kimi.com/assets/logo/dark.svg) 更多正文内容…… ``` **通用响应头** | 响应头 | 说明 | | - | - | | `X-Msh-Track-Id` | 请求 ID；请求携带同名头时沿用，否则由服务端生成。排查问题时请提供该 ID | | `X-Msh-Chat-Id` | 会话 ID，固定为 `toolgw-{X-Msh-Track-Id}`；排查问题时请一并提供 | 以上两个响应头在所有响应（包括错误响应）中均会携带。 | HTTP 状态码 | error.type | 典型 message | 说明 | | - | - | - | - | | 400 | `invalid_request` | `invalid request body` | 请求体不是合法 JSON | | 400 | `invalid_url` | `The provided URL is invalid: only http and https are supported` | URL 为空或协议非 http/https | | 400 | `invalid_url` | `The provided URL is invalid: missing host` | URL 缺少主机名 | | 401 | - | 无错误响应体 | API Key 缺失或无效 | | 403 | - | 无错误响应体 | 账号未激活或已停用 | | 403 | `security_risk` | `We consider the current URL poses a security risk and are unable to provide fetch service at this time.` | URL 触发安全风控，请更换 URL | | 404 | `markdown_not_found` | `No text/markdown content found for the current URL.` | 页面无可提取的正文内容 | | 408 | `client_canceled` | `client canceled the request` | 客户端在服务端返回前断开连接 | | 429 | `rate_limited` | `project concurrency limit exceeded` | 触发频率或并发限制；响应头携带 `X-RateLimit-Limit`、`X-RateLimit-Remaining`，触发每秒请求数限制时还携带 `X-RateLimit-Reset` | | 429 | `rate_limit_unavailable` | `rate limit store unavailable` | 限速服务暂时不可用，请稍后重试 | | 500 | `internal_error` | 内部错误原文 | 服务内部错误，请稍后重试；若持续出现，请携带 `X-Msh-Track-Id` 联系支持团队 | | 502 | `upstream_failed` | `upstream service failed` | 服务暂时不可用，请稍后重试 | | 504 | `timeout` | `request timeout` | 抓取超时，请稍后重试 | 计费说明：请求成功（HTTP 200）且返回的 `markdown` 非空白时，计费一次；请求失败或页面无正文内容时不计费。具体价格详见[联网搜索定价](/docs/pricing/websearch)。 # 联网搜索 Basic Source: https://platform.kimi.com/docs/api/tools-search POST /v1/tools/search 通过 /v1/tools/search 接口发起网页搜索，返回结构化搜索结果。 发起一次网页搜索，返回标题、摘要、站点、链接等结构化搜索结果列表，适用于需要自行编排搜索逻辑的 Agent 应用。 ```python python expandable theme={null} import os import requests api_key = os.environ.get("MOONSHOT_API_KEY") url = "https://api.moonshot.cn/v1/tools/search" response = requests.post( url, headers={"Authorization": f"Bearer {api_key}"}, json={ "text_query": "Kimi K2 模型 发布", "limit": 5, "timeout_seconds": 10, }, ) print(response.json()) ``` ```bash curl expandable theme={null} curl https://api.moonshot.cn/v1/tools/search \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -d '{"text_query": "Kimi K2 模型 发布", "limit": 5, "timeout_seconds": 10}' ``` ```javascript node.js expandable theme={null} const apiKey = process.env.MOONSHOT_API_KEY; async function main() { const response = await fetch("https://api.moonshot.cn/v1/tools/search", { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}`, }, body: JSON.stringify({ text_query: "Kimi K2 模型 发布", limit: 5, timeout_seconds: 10, }), }); const data = await response.json(); console.log(data); } main(); ``` | 字段 | 类型 | 说明 | | - | - | - | | `search_results` | array\[object] | 搜索结果列表；无结果时为空数组 | | `search_results[].authority` | string | 来源权威性等级 | | `search_results[].date` | string | 搜索结果日期 | | `search_results[].icon` | string | 站点图标 URL | | `search_results[].mime` | string | 内容 MIME 类型 | | `search_results[].site_name` | string | 站点名称 | | `search_results[].snippet` | string | 搜索结果摘要 | | `search_results[].text` | string | 网页正文内容；`include_content=true` 时返回，为 false 时为空字符串 | | `search_results[].title` | string | 搜索结果标题 | | `search_results[].url` | string | 搜索结果链接 | 以上字符串字段在无数据时返回空字符串。 **响应示例** ```json theme={null} { "search_results": [ { "authority": "S", "date": "2026-06-01", "icon": "https://platform.kimi.com/favicon.ico", "mime": "text/html", "site_name": "Kimi API 开放平台", "snippet": "Kimi API 开放平台文档入口。", "text": "", "title": "API 概述 - Kimi API 开放平台", "url": "https://platform.kimi.com/docs/api/overview" } ] } ``` **通用响应头** | 响应头 | 说明 | | - | - | | `X-Msh-Track-Id` | 请求 ID；请求携带同名头时沿用，否则由服务端生成。排查问题时请提供该 ID | | `X-Msh-Chat-Id` | 会话 ID，固定为 `toolgw-{X-Msh-Track-Id}`；排查问题时请一并提供 | 以上两个响应头在所有响应（包括错误响应）中均会携带。 | HTTP 状态码 | error.type | 典型 message | 说明 | | - | - | - | - | | 400 | `invalid_request` | `invalid request body` | 请求体不是合法 JSON | | 400 | `invalid_request` | `text_query is required` | 缺少搜索查询文本 | | 400 | `invalid_request` | `timeout_seconds must be less than or equal to 60` | `timeout_seconds` 取值范围为 1-60 | | 400 | `invalid_request` | `limit must be between 1 and 20` | `limit` 取值范围为 1-20 | | 401 | - | 无错误响应体 | API Key 缺失或无效 | | 403 | - | 无错误响应体 | 账号未激活或已停用 | | 408 | `client_canceled` | `client canceled the request` | 客户端在服务端返回前断开连接 | | 429 | `rate_limited` | `project qps limit exceeded` | 触发频率或并发限制；响应头携带 `X-RateLimit-Limit`、`X-RateLimit-Remaining`，触发每秒请求数限制时还携带 `X-RateLimit-Reset` | | 429 | `rate_limit_unavailable` | `rate limit store unavailable` | 限速服务暂时不可用，请稍后重试 | | 500 | `internal_error` | 内部错误原文 | 服务内部错误，请稍后重试；若持续出现，请携带 `X-Msh-Track-Id` 联系支持团队 | | 502 | `upstream_failed` | `upstream service failed` | 服务暂时不可用，请稍后重试 | | 504 | `timeout` | `request timeout` | 搜索超时；可调大 `timeout_seconds` 或精简查询后重试 | 计费说明：请求成功（HTTP 200）且 `search_results` 非空时，计费一次；请求失败或未返回结果时不计费。具体价格详见[联网搜索定价](/docs/pricing/websearch)。 # 联网搜索 Pro Source: https://platform.kimi.com/docs/api/tools-search-pro POST /v1/tools/search_pro 通过 /v1/tools/search_pro 接口发起网页搜索，支持站点与时间范围约束，并返回结构化正文片段。 在联网搜索 Basic 的基础上，支持通过 `sites` 将结果约束在指定站点内（多个站点按 OR 处理，最多 5 个），通过 `time_window` 约束结果的时间范围，并为每个结果返回结构化正文片段（`chunks`），适用于对信息来源和时效有要求的检索场景。 `time_window` 的 `start` 与 `end` 支持 `YYYY`、`YYYY-MM`、`YYYY-MM-DD` 三种格式，均按周期第一天归一化后比较，`start` 不得晚于 `end`。 ```python python expandable theme={null} import os import requests api_key = os.environ.get("MOONSHOT_API_KEY") url = "https://api.moonshot.cn/v1/tools/search_pro" response = requests.post( url, headers={"Authorization": f"Bearer {api_key}"}, json={ "text_query": "Kimi K2 模型 发布", "limit": 5, "sites": ["moonshot.cn", "kimi.com"], "time_window": {"start": "2026-01", "end": "2026-09"}, }, ) print(response.json()) ``` ```bash curl expandable theme={null} curl https://api.moonshot.cn/v1/tools/search_pro \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -d '{"text_query": "Kimi K2 模型 发布", "limit": 5, "sites": ["moonshot.cn", "kimi.com"], "time_window": {"start": "2026-01", "end": "2026-09"}}' ``` ```javascript node.js expandable theme={null} const apiKey = process.env.MOONSHOT_API_KEY; async function main() { const response = await fetch("https://api.moonshot.cn/v1/tools/search_pro", { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}`, }, body: JSON.stringify({ text_query: "Kimi K2 模型 发布", limit: 5, sites: ["moonshot.cn", "kimi.com"], time_window: { start: "2026-01", end: "2026-09" }, }), }); const data = await response.json(); console.log(data); } main(); ``` | 字段 | 类型 | 说明 | | - | - | - | | `search_results` | array\[object] | 搜索结果列表；无结果时为空数组 | | `search_results[].authority` | string | 来源权威性等级 | | `search_results[].date` | string | 搜索结果日期 | | `search_results[].icon` | string | 站点图标 URL | | `search_results[].mime` | string | 内容 MIME 类型 | | `search_results[].site_name` | string | 站点名称 | | `search_results[].snippet` | string | 搜索结果摘要 | | `search_results[].title` | string | 搜索结果标题 | | `search_results[].url` | string | 搜索结果链接 | | `search_results[].chunks` | array\[object] | 结构化正文片段，按页面聚合；无正文时为空数组 | | `search_results[].chunks[].text` | string | 正文片段内容 | | `search_results[].chunks[].score` | number | 正文片段与查询词的相关性得分 | 除 `chunks` 外，以上字符串字段在无数据时返回空字符串。 **响应示例** ```json theme={null} { "search_results": [ { "authority": "S", "date": "2026-06-01", "icon": "https://platform.kimi.com/favicon.ico", "mime": "text/html", "site_name": "Kimi API 开放平台", "snippet": "Kimi API 开放平台文档入口。", "title": "API 概述 - Kimi API 开放平台", "url": "https://platform.kimi.com/docs/api/overview", "chunks": [ { "text": "Kimi API 提供聊天补全、文件、批处理等接口，兼容 OpenAI 与 Anthropic 协议。", "score": 1.23 } ] } ] } ``` **通用响应头** | 响应头 | 说明 | | - | - | | `X-Msh-Track-Id` | 请求 ID；请求携带同名头时沿用，否则由服务端生成。排查问题时请提供该 ID | | `X-Msh-Chat-Id` | 会话 ID，固定为 `toolgw-{X-Msh-Track-Id}`；排查问题时请一并提供 | 以上两个响应头在所有响应（包括错误响应）中均会携带。 | HTTP 状态码 | error.type | 典型 message | 说明 | | - | - | - | - | | 400 | `invalid_request` | `invalid request body` | 请求体不是合法 JSON | | 400 | `invalid_request` | `text_query is required` | 缺少搜索查询文本 | | 400 | `invalid_request` | `timeout_seconds must be less than or equal to 60` | `timeout_seconds` 取值范围为 1-60 | | 400 | `invalid_request` | `limit must be between 1 and 20` | `limit` 取值范围为 1-20 | | 400 | `invalid_request` | `sites must contain at most 5 entries` | `sites` 最多 5 个站点 | | 400 | `invalid_request` | `site must not contain whitespace or parentheses` | `sites` 单条不能包含空白字符或括号 | | 400 | `invalid_request` | `time_window.start is invalid, expect YYYY / YYYY-MM / YYYY-MM-DD` | `time_window` 日期格式不合法（`end` 同理） | | 400 | `invalid_request` | `time_window.start must not be after time_window.end` | 按周期第一天归一化后，`start` 不得晚于 `end` | | 401 | - | 无错误响应体 | API Key 缺失或无效 | | 403 | - | 无错误响应体 | 账号未激活或已停用 | | 408 | `client_canceled` | `client canceled the request` | 客户端在服务端返回前断开连接 | | 429 | `rate_limited` | `project qps limit exceeded` | 触发频率或并发限制；响应头携带 `X-RateLimit-Limit`、`X-RateLimit-Remaining`，触发每秒请求数限制时还携带 `X-RateLimit-Reset` | | 429 | `rate_limit_unavailable` | `rate limit store unavailable` | 限速服务暂时不可用，请稍后重试 | | 500 | `internal_error` | 内部错误原文 | 服务内部错误，请稍后重试；若持续出现，请携带 `X-Msh-Track-Id` 联系支持团队 | | 502 | `upstream_failed` | `upstream service failed` | 服务暂时不可用，请稍后重试 | | 504 | `timeout` | `request timeout` | 搜索超时；可调大 `timeout_seconds` 或精简查询后重试 | 计费说明：请求成功（HTTP 200）且 `search_results` 非空时，计费一次；请求失败或未返回结果时不计费。具体价格详见[联网搜索定价](/docs/pricing/websearch)。 # 快速开始 Source: https://platform.kimi.com/docs/get-api-key 从创建 API Key 到完成第一次 Kimi API 调用。 Kimi API 提供了与 Kimi 大模型交互的能力，兼容 OpenAI 与 Anthropic API 格式。只需准备 API Key、选择模型，并配置 `base_url`，即可通过 HTTP API、OpenAI SDK 或 Anthropic SDK 发起调用。 [Kimi K3 模型](/docs/guide/kimi-k3-quickstart) 已正式发布。它是 Kimi 迄今能力最强的模型，支持 1M token 上下文与视觉理解，适合 [Claude Code](guide/claude-code-kimi) 等编程 Agent 场景，以及知识工作与深度推理场景。加入 [Kimi 开发者交流群](/docs/api/join-the-community) ，let's build on Kimi! ## 开始使用 访问 [Kimi API 开放平台](https://platform.kimi.com/) ，登录后进入 [API Keys](https://platform.kimi.com/console/api-keys) 页面创建并复制 API Key。 请妥善保管你的 API Key，不要泄露给他人，也不要直接硬编码在代码中。建议使用环境变量保存： ```bash theme={null} export MOONSHOT_API_KEY="你的_KIMI_API_KEY" ``` 登录开放平台，进入控制台、开发工作台和用户中心。 创建、复制和管理用于 API 调用的密钥。 作为快速开始入口，建议优先从 Kimi K3 开始；也可以根据场景选择 Kimi K2.7 Code 或 Kimi K2.6。 Kimi K3 是面向长程编程与端到端知识工作的旗舰模型——2.8 万亿参数、1M token 上下文，综合智能达到领先水平。 面向代码场景的 Coding 模型，支持 256K 上下文窗口、文本/图片/视频输入和思考模式。如需更高输出速度，可选择 `kimi-k2.7-code-highspeed`。 综合能力强，支持 256K 上下文窗口、文本/图片/视频输入、思考与非思考模式，适合通用对话、Agent 任务、视觉理解和复杂推理。 不确定如何选择时，默认从 `kimi-k3` 开始。如果你主要做代码生成、代码修改或编程 Agent 且追求更高输出速度，可以选择 `kimi-k2.7-code-highspeed`。 Kimi API 兼容 OpenAI 与 Anthropic API 格式，你可以根据项目技术栈选择最合适的接入方式。 OpenAI 兼容格式，支持 OpenAI SDK 与任意语言 HTTP 接入。 OpenAI 兼容格式，生成文本/JSON 输出或调用函数工具。 Anthropic 兼容格式，适合 Anthropic SDK、Claude Code 等工具接入。 无需写代码，快速测试提示词、模型效果和业务样例。 下面以 Kimi K3 模型为例。示例中的 `MOONSHOT_API_KEY` 需要替换为你在平台上创建的 API Key，或提前设置为同名环境变量。 本页示例默认使用最新模型 `kimi-k3`。K3 使用请求顶层 `reasoning_effort` 配置推理强度（支持 `"low"` / `"high"` / `"max"`，默认 `"max"`）。换用 `kimi-k2.6` 等其他模型时，只需替换 `model` 字段，但各模型的参数配置存在差异，详见[模型参数参考](/docs/api/models-overview)。 如果你希望使用编程场景的高速模型，可将示例中的 `kimi-k3` 替换为 `kimi-k2.7-code-highspeed`；如果要调用 Kimi K2.6，则替换为 `kimi-k2.6`。 ```python theme={null} import os from openai import OpenAI client = OpenAI( api_key=os.environ["MOONSHOT_API_KEY"], base_url="https://api.moonshot.cn/v1", ) completion = client.chat.completions.create( model="kimi-k3", messages=[ {"role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。"}, {"role": "user", "content": "你好，我叫李雷，1+1等于多少？"} ] ) print(completion.choices[0].message.content) ``` ```bash theme={null} curl https://api.moonshot.cn/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $MOONSHOT_API_KEY" \ -d '{ "model": "kimi-k3", "messages": [ {"role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。"}, {"role": "user", "content": "你好，我叫李雷，1+1等于多少？"} ] }' ``` ```js theme={null} const OpenAI = require("openai"); const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, baseURL: "https://api.moonshot.cn/v1", }); async function main() { const completion = await client.chat.completions.create({ model: "kimi-k3", messages: [ {"role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。"}, {"role": "user", "content": "你好，我叫李雷，1+1等于多少？"} ] }); console.log(completion.choices[0].message.content); } main(); ``` 运行上述代码前，请准备： 1. Python 3.8 及以上版本，或 Node.js 18 及以上版本。 2. OpenAI SDK 1.0.0 及以上版本。Kimi API 兼容 OpenAI API 格式，你可以直接使用 Python 或 Node.js OpenAI SDK 进行调用。 ```text theme={null} pip install --upgrade 'openai>=1.0' # Python npm install openai@latest # Node.js ``` 3. API Key。你需要从 Kimi 开放平台中 [创建一个 API Key](https://platform.kimi.com/console/api-keys) ，将其传入 `OpenAI Client` 以便平台正确识别你的身份。 如果成功运行上述代码，且没有任何报错，你将看到类似如下的内容输出： ```text theme={null} 你好，李雷！1+1 等于 2。这是一个基本的数学加法问题。如果你有其他问题或需要帮助，请随时告诉我。 ``` *注：由于 Kimi 大模型的不确定性，实际的回复内容可能并不与上述内容完全一致。* ## 探索更多功能 启用 `stream`，让回复边生成边返回，适合聊天、代码生成和长文本输出场景。 通过维护 `messages` 列表实现上下文记忆，让模型记住对话历史。 Kimi K3、Kimi K2.7 Code 和 Kimi K2.6 均支持文本、图片与视频输入。 让模型调用外部函数或 API，实现 Agent 任务、联网搜索和复杂工作流。 强制模型输出合法 JSON，方便结构化数据提取和下游系统对接。 使用思考能力处理复杂推理、多步工具调用和 Agent 任务。 ### 流式输出 ```json theme={null} { "model": "kimi-k3", "messages": [ { "role": "user", "content": "请解释什么是递归，并给出一个 Python 示例。" } ], "stream": true } ``` ### 多模态输入 ```json theme={null} { "model": "kimi-k3", "messages": [ { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }, { "type": "text", "text": "请描述这张图片。" } ] } ] } ``` 对于较大的视频或需要多次引用的图片、视频，建议使用文件上传方式。图片建议不超过 4K 分辨率，视频建议不超过 1080p。 ## 相关资源 查看 Kimi K3 的模型能力、调用示例和最佳实践。 查看 Kimi K2.7 Code 的模型能力、调用示例和最佳实践。 查看 Kimi K2.6 的模型能力、图片/视频理解示例和工具调用说明。 提供建议、问题反馈、分享案例: Let's Build with Kimi ! 查看当前可用模型名称和模型说明。 # 自动断线重连 Source: https://platform.kimi.com/docs/guide/auto-reconnect 为 Kimi API 流式请求实现断线重连，并结合 Partial Mode 从中断处继续生成。 因为并发限制、复杂的网络环境等情况，一些时候我们的连接可能因为一些预期外的状况而中断，通常这种偶发的中断并不会持续很久，我们希望在这种情况下业务依然可以稳定运行，使用简单的代码即可实现断线重连的需求。 本页示例默认使用最新模型 `kimi-k3`。K3 使用请求顶层 `reasoning_effort` 配置推理强度（支持 `"low"` / `"high"` / `"max"`，默认 `"max"`）。换用 `kimi-k2.6` 等其他模型时，只需替换 `model` 字段，但各模型的参数配置存在差异，详见[模型参数参考](/docs/api/models-overview)。 ```python theme={null} import os from openai import OpenAI import time client = OpenAI( api_key=os.environ["MOONSHOT_API_KEY"], base_url = "https://api.moonshot.cn/v1", ) def chat_once(msgs): response = client.chat.completions.create( model = "kimi-k3", messages = msgs ) return response.choices[0].message.content def chat(input: str, max_attempts: int = 100) -> str | None: messages = [ {"role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。"}, ] # 我们将用户最新的问题构造成一个 message（role=user），并添加到 messages 的尾部 messages.append({ "role": "user", "content": input, }) st_time = time.time() for i in range(max_attempts): print(f"Attempts: {i+1}/{max_attempts}") try: response = chat_once(messages) ed_time = time.time() print("Query Successful!") print(f"Query Time: {ed_time-st_time}") return response except Exception as e: print(e) time.sleep(1) continue print("Query Failed.") return print(chat("你好，请给我讲一个童话故事。")) ``` 上面的代码实现了一个简单的断线重连功能，最多重复 100 次，每次连接之间等待 1s，你也可以根据具体的需求更改这些数值以及满足重试的条件。 # 联网搜索最佳实践 Source: https://platform.kimi.com/docs/guide/best-practices-for-web-search 按场景选择搜索接口、控制成本、写有效查询词、配置参数，提升联网搜索结果质量。 开发者在给 AI 应用、联网问答 Agent、RAG 接入搜索能力时，往往会发现「找到网页」不等于「能用」，整页网页往往夹杂导航、广告等无关内容，直接交给模型既浪费 Token，又稀释关键信息。 现在 Kimi 开放平台为开发者提供联网搜索 Basic、联网搜索 Pro 和网页抓取三个独立的 REST 接口，把网页处理成可直接使用的信息：结构化搜索结果、相关正文片段或指定网页正文，提供「又快又好」的联网搜索体验。 其中，联网搜索 Pro 在专业知识搜索任务和事实类查询能力上做了专项提升：模型先读懂正文，再把与问题最相关的内容片段挑出来返回，同时返回 `authority`（来源权威性等级）字段，方便开发者对结果做下一步评估、过滤。 相比把整页网页交给模型，使用联网搜索 Pro 接口有四个好处： * **更准的回答**：减少导航、广告等无关信息干扰，让关键信息更集中。 * **更低的 Token 成本**：只将高相关片段送入上下文，减少无效 Token 消耗，响应更快。 * **更少的工程投入**：正文切块和相关性排序由服务端完成，结果可直接交给模型使用。 * **来源始终可溯**：每个片段保留标题、链接和站点信息，方便引用和核查。 本页介绍如何选对接口、控制成本、写出有效的查询词、配置参数，用更少的调用拿到更准的结果。 ## 选择合适的接口 | 接口 | 端点 | 返回内容 | 适合场景 | | - | - | - | - | | 联网搜索 Basic | `POST /v1/tools/search` | 相关网页的标题、链接和摘要；`include_content=true` 时附带网页正文 | 搜索结果展示、网页采集，或想自己加工正文 | | 联网搜索 Pro | `POST /v1/tools/search_pro` | 网页正文中与查询词最相关的内容片段，按相关性排序 | 联网问答、RAG、Agent、报告与总结 | | 网页抓取 | `POST /v1/tools/fetch` | 指定网页的标题和 Markdown 正文 | 已知目标 URL，需要获取网页正文 | 三个接口按次计费，价格见 [联网搜索价格](/docs/pricing/websearch)。 常见任务和推荐的接口： | 你想完成的事情 | 推荐接口 | 说明 | | - | - | - | | 搜索结果展示 | 联网搜索 Basic | 网页标题、摘要、链接和正文适合作为来源卡片或结果列表直接展示 | | 网页采集与自行加工 | 联网搜索 Basic | 拿到完整正文后接入自己的切块和筛选流程 | | 联网问答 | 联网搜索 Pro | 返回与问题相关的内容片段，模型基于片段组织答案，并保留来源链接 | | 实时 Web RAG | 联网搜索 Pro | 先搜索外部网页，再把相关片段作为临时检索结果交给模型 | | 报告与研究 | 联网搜索 Pro | 围绕主题搜索多个来源，优先提取关键段落，再由模型整理为竞品分析、政策解读或行业报告 | | 限定站点或时间范围搜索 | 联网搜索 Pro | 通过 `sites` 和 `time_window` 参数约束搜索范围，提高结果相关性 | | 已有明确网页地址 | 网页抓取 | 直接获取指定网页的标题和 Markdown 正文 | 联网搜索 Pro 在 联网搜索 Basic 找到网页之后多做了一步：读懂正文，把与问题最相关的内容片段挑出来，按相关性排好序。 结果不经过模型、直接展示给用户时（搜索结果页、来源卡片），或者想自己加工正文（切块、筛选）时，联网搜索 Pro 的加工反而是多余的，建议选用 联网搜索 Basic。 ## 控制成本 | 场景 | 做法 | | - | - | | 只需要摘要判断相关性 | 联网搜索 Basic 保持 `include_content=false`（默认值），只返回标题、链接和摘要，最快、最便宜 | | 需要细读正文 | 用 联网搜索 Pro，返回的正文片段（chunks）已按相关性排序，相比把整页原文交给模型，token 消耗通常能下降一个数量级（具体效果因查询和网页内容而异）。每个片段保留所属网页的标题、链接和站点信息，来源可溯 | | 确定需要整页原文（例如全文入库） | 联网搜索 Basic 设置 `include_content=true`，或者对已知的 URL 直接调用网页抓取 | 除了单次调用拿回的内容量，调用次数也影响成本。建议把同一信息需求的追问改写成一条更完整的查询词，合并成一次调用。近似查询词搜到的页面高度重叠，拆开调用就要为同一批页面重复付费；合并之后，同样的花费能覆盖更多不同的来源。 例如，想调研 2025 年诺贝尔物理学奖的获奖情况： * ✗ 拆成三次调用：`2025 年诺贝尔物理学奖`、`2025 年诺贝尔物理学奖 获奖成果`、`2025 年诺贝尔物理学奖 实验验证` * ✓ 合并成一次调用：`2025 年诺贝尔物理学奖 获奖成果 实验验证` 搜索与网页抓取调用的费用说明见 [联网搜索价格](/docs/pricing/websearch)。 如果单次搜索的结果不够深入，可以把查询词写得更具体。 ## 写有效查询词 接口按提交的查询词（`text_query`）原样搜索，不会自动改写、补全或扩展。查询词决定搜到什么。模糊的查询词把调用浪费在无关页面上，具体的查询词让每个结果都有用。 把查询词写具体有三个维度： | 维度 | 写法 | 反例 | 正例 | | - | - | - | - | | 实体 | 给明确的专有名词（人名、公司、产品、事件名），不要给类别描述。没有实体，搜索引擎只能猜你要找什么 | `最近很火的 AI 大模型` | `Kimi K3 新特性 评测` | | 时间 | 时效性问题带上年份、季度或版本号。时间词既影响结果的新鲜度，也帮助系统判断结果的相关性 | `最新财报` | `2026 Q2 财报 营收` | | 限定词 | 限定角度或来源类型，决定搜到的是官网、新闻、公告原文还是论坛讨论 | `Kimi K3 API 定价` | `Kimi K3 API 定价 官方文档` | 三个维度组合起来，一次调用就能拿到可以直接使用的材料： * ✗ `诺贝尔奖` * ✓ `2025 年诺贝尔物理学奖 获奖成果 实验验证` 另外还有两点要注意： * **一次调用只表达一个信息需求**。把互不相关的问题堆进一条查询词，得到的只是一条又长又散的查询，结果质量反而下降。 * **不要用同义改写重发**。两次近似查询的结果高度重叠，等于为同一份结果付了两次费。第一次结果不好时，应该补实体、时间、限定词，或者换一个角度（换维度、换语言）。 ## 按站点和时间过滤结果 联网搜索 Pro 提供两个约束参数，可以直接限定搜索范围： * `sites`：限定来源站点，最多 5 个，多个站点按 OR 处理。例如 `["gov.cn", "miit.gov.cn"]` 让结果只来自指定站点。 * `time_window`：限定发布时间的起止范围，日期支持 `YYYY`、`YYYY-MM`、`YYYY-MM-DD` 三种格式。查询词里的时间词影响搜索和排序，`time_window` 直接按时间过滤结果，两者可以叠加。 ## 设置结果数量和超时时间 联网搜索 Basic 和 联网搜索 Pro 还支持 `limit` 和 `timeout_seconds`，建议显式设置： * `limit`：返回结果的数量上限，默认 5，范围 1 到 20。先取少量结果判断方向，再决定是否深入。 * `timeout_seconds`：超时时间，范围 1 到 60 秒。返回正文（`include_content=true`）或使用 联网搜索 Pro 时耗时更长，建议给足超时时间。 ## 处理边界情况 * 网页能否取到正文，受网站可访问性、登录限制、反爬策略、页面结构和网络状况影响。搜索接口取不到正文时，仍会返回网页的标题、链接和摘要，可以先按摘要判断相关性，再决定是否换来源。 * 网页抓取 返回的 Markdown 是网页正文的提取结果，不包含图片、视频等多媒体资源。 ## 完整示例 以下示例用 联网搜索 Pro 搜索 2025 年诺贝尔物理学奖：查询词包含时间和实体，`sites` 限定官方站点，`time_window` 限定发布时间范围： ```bash theme={null} curl -X POST "https://api.moonshot.cn/v1/tools/search_pro" \ --header "Authorization: Bearer $MOONSHOT_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "text_query": "2025 年诺贝尔物理学奖 获奖成果 实验验证", "limit": 5, "timeout_seconds": 30, "sites": ["nobelprize.org"], "time_window": { "start": "2025-10", "end": "2025-12" } }' ``` 响应中的每个结果包含网页的标题、链接、站点、日期和若干正文片段，片段按相关性排序，可以直接交给模型使用： ```json theme={null} { "search_results": [ { "title": "The Nobel Prize in Physics 2025 - Press release", "url": "https://www.nobelprize.org/prizes/physics/2025/press-release/", "site_name": "NobelPrize.org", "date": "2025-10-07", "snippet": "...", "chunks": [ { "text": "……与查询词最相关的正文片段……", "score": 1.2432842 } ] } ] } ``` 其中 `chunks[].score` 是片段与查询词的相关性分数，只在同一次查询内有相对意义，不要跨查询比较绝对值。 # 在 Claude Code 中使用 Kimi Source: https://platform.kimi.com/docs/guide/claude-code-kimi 介绍如何将 Kimi API 接入 Claude Code，并完成模型选择与配置验证。 > 本文介绍如何在 [Claude Code](https://claude.com/product/claude-code) 中接入 Kimi 的 Anthropic 兼容端点（[Messages API](/docs/api/messages)）。Claude Code 的界面与配置项可能随版本变化，请以实际版本为准。 ## 安装 Claude Code 已安装的用户可跳过。执行以下命令安装： ```shell theme={null} npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com ``` macOS 和 Linux： ```shell theme={null} # 安装 nodejs curl -fsSL https://fnm.vercel.app/install | bash # 新开一个终端，让 fnm 生效 fnm install 24.3.0 fnm default 24.3.0 fnm use 24.3.0 ``` Windows（PowerShell）： ```powershell theme={null} # 右键按 Windows 按钮，点击「终端」，然后依次执行 winget install OpenJS.NodeJS Set-ExecutionPolicy -Scope CurrentUser RemoteSigned # 关闭终端窗口，新开一个终端窗口 ``` 安装 Node.js 后，执行一次初始化配置： ```shell theme={null} node --eval " const fs = require('fs'); const path = require('path'); const os = require('os'); const homeDir = os.homedir(); const filePath = path.join(homeDir, '.claude.json'); if (fs.existsSync(filePath)) { const content = JSON.parse(fs.readFileSync(filePath, 'utf-8')); fs.writeFileSync(filePath, JSON.stringify({ ...content, hasCompletedOnboarding: true }, null, 2), 'utf-8'); } else { fs.writeFileSync(filePath, JSON.stringify({ hasCompletedOnboarding: true }, null, 2), 'utf-8'); }" ``` 如果您之前通过第三方工具或手动修改过 `~/.claude/settings.json`，里面残留的旧配置会 **覆盖** 终端里 export 的同名环境变量，导致新配置不生效或模型请求被静默改写。建议先执行以下脚本清理： ```shell theme={null} node --eval " const fs = require('fs'); const path = require('path'); const os = require('os'); const settingsPath = path.join(os.homedir(), '.claude', 'settings.json'); if (fs.existsSync(settingsPath)) { const content = JSON.parse(fs.readFileSync(settingsPath, 'utf-8')); if (content && typeof content === 'object' && content.env && typeof content.env === 'object') { for (const key of [ 'ANTHROPIC_BASE_URL', 'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_MODEL', 'ANTHROPIC_SMALL_FAST_MODEL', 'CLAUDE_CODE_SUBAGENT_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL_NAME', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL_NAME', 'ANTHROPIC_DEFAULT_HAIKU_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME', 'ANTHROPIC_DEFAULT_FABLE_MODEL', 'ANTHROPIC_DEFAULT_FABLE_MODEL_NAME', 'ENABLE_TOOL_SEARCH', 'CLAUDE_CODE_AUTO_COMPACT_WINDOW', 'CLAUDE_CODE_EFFORT_LEVEL', ]) { delete content.env[key]; } fs.writeFileSync(settingsPath, JSON.stringify(content, null, 2), 'utf-8'); } }" ``` 该脚本仅删除 `env` 中的端点、密钥与模型相关变量，不影响 `settings.json` 中的其他配置（如权限、主题等）。 另外，请检查 `~/.zshrc`、`~/.bashrc` 等 shell 配置文件中是否残留旧的 `ANTHROPIC_*` export（Windows 用户请检查用户环境变量），如有请一并删除，否则同样会干扰新配置。 ## 获取 Kimi API Key 访问 [Kimi 开放平台](https://platform.kimi.com/console/api-keys) 创建 API Key，替换下文中的 `YOUR_MOONSHOT_API_KEY`。 ## 配置环境变量 将以下变量写入 `~/.claude/settings.json` 的 `env` 字段，保存后重启 Claude Code 即可生效。本示例将 HAIKU 档配置为 `kimi-k2.7-code`，其余档位均为 `kimi-k3[1m]`。 ```json theme={null} { "env": { "ANTHROPIC_BASE_URL": "https://api.moonshot.cn/anthropic", "ANTHROPIC_AUTH_TOKEN": "YOUR_MOONSHOT_API_KEY", "ANTHROPIC_MODEL": "kimi-k3[1m]", "ANTHROPIC_DEFAULT_OPUS_MODEL": "kimi-k3[1m]", "ANTHROPIC_DEFAULT_SONNET_MODEL": "kimi-k3[1m]", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "kimi-k2.7-code", "ANTHROPIC_DEFAULT_FABLE_MODEL": "kimi-k3[1m]", "CLAUDE_CODE_SUBAGENT_MODEL": "kimi-k3[1m]", "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000", "CLAUDE_CODE_EFFORT_LEVEL": "max" } } ``` 注意：`settings.json` 的 `env` 会 **覆盖** 终端里 export 的同名变量；该文件包含明文 API Key，请勿提交到 git 仓库。 ### 配置项说明 Claude Code 内部会按场景使用不同档位的模型（主对话、后台摘要、子 Agent 等），只配置部分变量会让对应场景静默失败： | 变量 | 作用 | 不配置的后果 | | - | - | - | | `ANTHROPIC_BASE_URL` | Kimi 端点地址 | 请求发往 Anthropic 官方端点，鉴权失败 | | `ANTHROPIC_AUTH_TOKEN` | Kimi API Key | 返回 401 鉴权错误 | | `ANTHROPIC_MODEL` | 主对话模型 | 报模型不存在错误 | | `ANTHROPIC_DEFAULT_OPUS_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_HAIKU_MODEL` / `ANTHROPIC_DEFAULT_FABLE_MODEL` | 各任务档位使用的模型 | 对应档位的任务失败 | | `CLAUDE_CODE_SUBAGENT_MODEL` | 子 Agent 模型 | 子任务失败或效果明显变差 | | `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 触发自动压缩的上下文窗口 | 过小会过早压缩丢失上下文，过大报上下文超限错误 | | `CLAUDE_CODE_EFFORT_LEVEL` | 推理强度 | 建议设为 `max`，调低可能影响复杂任务质量 | ## 模型与思考行为 三个模型在 Claude Code 中的行为差异： | 模型 | 思考模式 | 使用要点 | | - | - | - | | `kimi-k3`（默认） | 默认开启，可关闭 | 开箱即用，无需额外配置 | | `kimi-k2.7-code` | 强制开启，不可关闭 | 必须在 Claude Code 中开启 Thinking（macOS `Option+T`，Windows/Linux `Alt+T`）后使用 | | `kimi-k2.6` | 可选，可关闭 | 适合对延迟敏感的简单任务 | 未开启思考时，`kimi-k2.7-code` 的请求会被拒绝并返回 `400 invalid thinking: only type=enabled is allowed for this model`。 ## 确认配置是否生效 配置完成后，可以先用 curl 验证端点和 API Key 是否可用： ```shell theme={null} curl https://api.moonshot.cn/anthropic/v1/messages \ --header "Authorization: Bearer YOUR_MOONSHOT_API_KEY" \ --header "Content-Type: application/json" \ --data '{"model": "kimi-k3", "max_tokens": 1, "messages": [{"role": "user", "content": "hi"}]}' ``` 返回正常的 JSON 响应即说明端点与凭据均可用；返回 401 说明 API Key 无效或与平台不匹配。确认无误后启动 Claude Code，输入 `/status` 确认配置状态： * Base URL 应显示为 `https://api.moonshot.cn/anthropic` * Model 应显示为 `kimi-k3[1m]` status Claude Code 的 `/model` 菜单会显示已配置的模型。 model-menu 最后随意发送一条消息（例如 `你好`），能正常收到回复即说明端到端配置成功： chat-verify ## 常见问题 * 检查 `ANTHROPIC_AUTH_TOKEN` 是否为有效的 Kimi API Key，并确认 `YOUR_MOONSHOT_API_KEY` 已替换为你的 Key； * 确认 `ANTHROPIC_BASE_URL` 与创建 API Key 的平台一致，即在上文「获取 Kimi API Key」链接对应的平台创建 Key 并使用本页给出的端点； * 如果您之前配置过 `ANTHROPIC_API_KEY`，请将其删除，避免与 `ANTHROPIC_AUTH_TOKEN` 同时存在导致冲突。 检查各模型变量的值是否拼写正确（`kimi-k3[1m]`），注意不要有多余的空格或引号。 通常是 `ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL` 或 `CLAUDE_CODE_SUBAGENT_MODEL` 未配置，对应场景请求了 Kimi 端点无法识别的模型名，请对照「配置项说明」补齐。 * 检查 `~/.claude/settings.json` 的 `env` 中是否有残留旧配置，可执行上文折叠块中的清理脚本； * 检查 `~/.zshrc`、`~/.bashrc` 等 shell 配置文件中是否有旧的 `ANTHROPIC_*` export 残留； * 修改 `settings.json` 后需重启 Claude Code 才会生效。 `ANTHROPIC_AUTH_TOKEN` 设置后会优先于已保存的登录态生效，一般无需处理。可在会话中输入 `/status` 确认当前生效的凭据来源；如需清除已保存的登录，可执行 `/logout`。 # 在 Codex 中使用 Kimi K3 Source: https://platform.kimi.com/docs/guide/codex-kimi 通过 Kimi Responses API 将 Codex 直连 Kimi K3：配置 API Key、编辑 `~/.codex/config.toml`，并分别在桌面端与 CLI 中验证连接。 Kimi 开放平台原生支持 Codex 使用的 [Responses API](/docs/api/responses)，因此 Codex 可以直接使用 `kimi-k3` 模型，无需协议转换或本地代理。 Codex CLI 目前支持文本和图片输入，但尚未提供原生视频输入通道，无法将视频文件直接作为多模态输入提交给模型。这是 Codex CLI 输入层的限制，并非 Kimi K3 模型的能力限制——Kimi K3 API 原生支持视频输入，按 [视觉输入](/docs/guide/use-kimi-vision-model) 直接调用 `kimi-k3` 即可进行完整的视频理解，无需手动抽帧。 ## 准备工作 开始前，请完成以下准备工作。安装和账号相关操作请按照对应的官方指引完成，本文不再展开。 按照 Codex 官方文档完成安装，并至少启动一次 Codex CLI。 在 Kimi 开放平台创建并保存 API Key。 ## 第一步：配置 API Key Codex 通过环境变量读取 API Key，请不要把 Key 写进 `config.toml`。为避免 Key 被记入命令历史，请按以下方式输入： ```bash theme={null} echo "请粘贴你的 Kimi API Key，然后按 Enter（输入内容不会显示）：" read -s KIMI_API_KEY export KIMI_API_KEY ``` 该方式只对当前终端会话生效；如需长期保存，可将 `export` 命令写入 `~/.zshrc`（文件为明文，请注意权限）。 ```powershell theme={null} $env:KIMI_API_KEY="YOUR_KIMI_API_KEY" ``` 如需长期保存，请在 **设置 > 系统 > 关于 > 高级系统设置 > 环境变量** 中添加 `KIMI_API_KEY`。 ## 第二步：将 Kimi 添加为模型供应商 打开 `~/.codex/config.toml`（Windows 上为 `%USERPROFILE%\.codex\config.toml`），添加以下配置。如果 `model` 或 `model_provider` 已存在，请替换其值： ```toml theme={null} model = "kimi-k3" model_provider = "kimi" model_context_window = 1048576 [model_providers.kimi] name = "Kimi" base_url = "https://api.moonshot.cn/v1" env_key = "KIMI_API_KEY" wire_api = "responses" ``` | 配置项 | 类型 | 作用 | | - | - | - | | `wire_api = "responses"` | `string` | 通过原生 Responses API 与 Kimi 通信，这是实现直连的关键配置 | | `env_key = "KIMI_API_KEY"` | `string` | Codex 读取 API Key 的环境变量名 | | `model_context_window = 1048576` | `integer` | 与 `kimi-k3` 的 1M 上下文窗口对齐；不配置时 Codex 会使用默认模型元数据，可能影响表现 | ## 在 Codex Desktop（桌面端）中使用 完成前面的 API Key 和供应商配置后，退出并重新启动 Desktop，使其重新读取 `~/.codex/config.toml`。 启动 Desktop 后，打开模型选择器并选择 `kimi-k3`。此时界面可能会显示 **自定义**，但实际请求仍然使用你配置的 `kimi-k3`。 Desktop 模型状态区显示「自定义」 发送一个简单请求： ```text theme={null} 你是谁 ``` 能正常收到回复，说明基本连接已经建立。接着发送一个会触发 Codex Agent 能力的任务： ```text theme={null} 检查这个仓库并总结它的结构。 ``` 如果 Desktop 能在工具结果返回后继续生成最终回答，说明模型调用与工具调用均已正常工作： Desktop 中 Kimi 完成仓库检查并返回结构总结 ## 在 Codex CLI 中使用 Codex CLI 与 Desktop 共用同一份用户级配置，前面的配置对它同样生效。进入需要使用的项目目录，启动 Codex（如果 Codex CLI 已经在运行，请先退出当前会话，以便重新加载配置）： ```bash theme={null} cd /path/to/your/project codex ``` 启动后，先确认 Codex CLI 显示的当前模型为 `kimi-k3`： 在 Codex CLI 中确认当前模型为 kimi-k3 发送一个简单请求（例如 `你好`），能正常收到回复即说明 Codex 已成功连接 Kimi Responses API。 在底层，Codex 会将请求发送到 `POST https://api.moonshot.cn/v1/responses`。请求与响应的协议细节请参阅 [Responses API 参考](/docs/api/responses)。 ## 常见问题 API Key 无效，或 Key 与 base\_url 分属不同平台——在 [platform.kimi.com](https://platform.kimi.com) 创建的 Key 只能用于 `https://api.moonshot.cn/v1`。同时确认 `KIMI_API_KEY` 已配置在启动 Codex 或 Desktop 的环境中；对于 CLI，可以在启动 Codex 的终端中执行 `test -n "$KIMI_API_KEY" && echo set || echo missing` 检查。 请求中包含了暂不受支持的 `search_context_size` 参数，移除即可。Codex 默认发送的请求不包含该参数，内置的 web\_search 工具开箱即用。 base\_url 填写有误——请确认其值恰好为 `https://api.moonshot.cn/v1`（带 /v1 后缀）。如果之前通过 CC Switch 等本地路由接入，还要确认 base\_url 不再指向 `http://127.0.0.1:...` 之类的本地地址。 触发了速率或并发限制。各档位的配额请参阅 [速率限制](/docs/pricing/limits)。 kimi-k3 不在 Codex 内置的模型目录中，该警告属于预期现象，不影响使用；第二步的 `model_context_window = 1048576` 已确保上下文窗口按 1M 计算。 Codex 只在启动时读取 config.toml，请退出后重新启动；同时确认修改的是 `~/.codex/config.toml` 本身，且没有被 `-c` 参数或 profile 覆盖。如果之前通过 CC Switch 接入，还需在其 **设置 > 路由** 中关闭 Codex，否则它会持续改写 config.toml，覆盖新配置。 各状态码的含义请参阅 [错误码](/docs/api/errors)。 # 在 Playground 中配置 ModelScope MCP 服务器 Source: https://platform.kimi.com/docs/guide/configure-the-modelscope-mcp-server 在 Kimi Playground 中同步并启用 ModelScope 托管的 MCP 服务，让模型调用已配置的工具。 Kimi 开放平台与 ModelScope（魔搭）官方合作：在 Kimi Playground 中输入魔搭 API 令牌，即可一键同步账号下所有已配置托管的 MCP 服务。需要让 Playground 中的模型调用 MCP 工具时，按本页完成同步与启用即可。 ## 同步魔搭托管的 MCP 服务 登录 Kimi Playground（[https://platform.kimi.com/playground），确保可以使用](https://platform.kimi.com/playground），确保可以使用) Kimi K2 模型进行基本对话。 MCP 服务在「MCP 服务器设置」中添加，Playground 默认已选中 ModelScope 作为 MCP 服务提供商。如果之前未使用过 ModelScope MCP 广场，先参考 [ModelScope 官方文档](https://modelscope.cn/mcp/kimi-playground) 选择并托管 MCP 服务；也可以在 ModelScope 社区发现海量 MCP 服务器。 ### 打开 MCP 服务器设置 点击配置按钮，进入「MCP 服务器设置」： mcp-server-setting ### 填入魔搭 API 令牌并同步 在弹出的面板中选择同步外部平台： syc API 令牌可在[魔搭首页-访问令牌](https://modelscope.cn/my/myaccesstoken)页面获取： keys 获取令牌后，粘贴到步骤 3 的空格中，点击「开始同步」： start-syc 同步完成后，所有已配置连接的魔搭 Hosted MCP 服务会出现在 Kimi Playground 的可用 MCP 服务列表中： mcp-list ### 增量同步 MCP 服务 后续在 ModelScope MCP 广场新增或删除托管 MCP 服务后，在"设置-MCP 服务器-同步服务器"中点击同步按钮，即可增量更新： add-mcp ## 在对话中启用 MCP 服务 同步完成后，Kimi Playground 页面左侧会显示已导入的「MCP 服务列表」，在其中多选并启用本次对话需要使用的 MCP 服务： manage-mcp 例如，在列表中启用高德地图相关的 MCP 服务，即可让助手帮你规划行程： maps # 上下文缓存最佳实践 Source: https://platform.kimi.com/docs/guide/context-caching 了解 Kimi API 上下文缓存的适用场景与计费，提高缓存命中率，选择 5m / 1h 缓存时长（TTL），并查看缓存用量。 在文档问答、编程智能体和多轮对话中，产品文档、代码库、工具定义、系统提示词等内容通常会被重复使用。每次请求都重新传入，不仅让上下文变长，也会反复产生输入费用。上下文缓存（Context Caching）可以复用这些重复的请求前缀。缓存命中的内容按更低价格计费：以 `kimi-k3` 为例，命中价格仅为未命中价格的 **1/10**，从而降低高频调用的成本。 本次平台升级将缓存写入（Cache Write）单独列为计费项，并提供 `5m` 和 `1h` 两档缓存时长（Time To Live，TTL）。开发者可以根据调用间隔选择缓存时长，清晰掌握缓存成本、观测降本效果。 ## 哪些内容适合缓存 上下文缓存适合在多次请求中重复发送固定内容的场景，例如： | 场景 | 反复发送的固定内容 | | - | - | | 文档问答 | 产品文档、知识库或公司制度 | | 编程 Agent | 代码库、开发规范和工具定义 | | 长会话 Agent | system prompt、工具定义和会话规则 | | 定时巡检与报告 | 报告模板、指标定义和参考资料 | 命中缓存后，重复部分按缓存命中价格计费。如果相同前缀很少复用，或复用间隔超过 TTL，使用上下文缓存的收益有限，不必专门配置。 ## 提高缓存命中率的方式 缓存按请求前缀匹配。前缀中任何一处发生变化，该位置之后的内容都无法复用。 上下文缓存如何命中：未变化的前缀可直接从缓存读取，前缀一旦变化缓存不再匹配 因此建议： 1. 把稳定的 system prompt、工具定义、参考资料和代码库放在请求前部。 2. 把用户问题、工具结果和任务状态等每轮变化的内容放在后部。 3. 保持同一会话中固定内容的顺序和文本完全一致，不要在前缀中插入时间戳、随机 ID 或其他动态字段。 4. 将定时任务的执行间隔控制在 TTL 内，利用命中续期保持缓存有效。 5. 缓存按组织（org）隔离：同一组织内共享，组织之间不共享。 缓存不支持手动清除；缓存前缀无活动超过所选 TTL 后自动过期。 ## 定价原则 Cache Write（缓存写入）单独列为计费项。以 `kimi-k3` 为例，缓存相关价格如下： | 计费项 | 价格（每 1M tokens） | 说明 | | - | - | - | | Input（缓存未命中） | ¥20 | 请求中未命中缓存的部分（每次请求单独计费） | | Cache Write（`5m`） | ¥20 | 前缀首次写入缓存时一次性收取；写入后 5 分钟内有效，每次命中后有效期重新计算为 5 分钟 | | Cache Write（`1h`） | ¥40 | 前缀首次写入缓存时一次性收取；写入后 1 小时内有效，每次命中后有效期重新计算为 1 小时 | | Cached Input（缓存命中） | ¥2 | 请求中命中缓存的部分（每次请求单独计费） | 其他模型与计费项的完整价格，见[模型推理价格说明](/docs/pricing/chat)。 上下文缓存计费：以 kimi-k3 为例的计费项与价格 费用可以总结为两点： * **总价不变**：缓存写入的拆分是计费透明化。写入成本原先就包含在输入价格中，拆分后现有请求的整体费用不变。 * **命中就省钱**：缓存命中价格是缓存未命中价格的 1/10。以 `kimi-k3` 为例，命中部分按缓存命中价格计费（¥2 / 1M tokens），每次命中比缓存未命中少 ¥18 / 1M tokens。 ## 两档 TTL 怎么选 缓存写入支持 `5m` 和 `1h` 两档 TTL。不传 `prompt_cache_options` 时，系统默认使用 `5m` TTL：满足命中条件的前缀会自动写入并尝试复用，账单上会产生相应的缓存写入费用。 * 连续追问间隔通常不超过 5 分钟时，选择 `5m`。 * 请求间隔会超过 5 分钟、但能在 1 小时内复用时，选择 `1h`。 * 相同前缀通常要间隔超过 1 小时才会复用时，不建议专门配置缓存。 以 `1h` 为例算一笔账（假设前缀 1M tokens），只要在 1 小时内再命中 2 次，就比选 `5m` 划算；命中越多省得越多。 * 选 `1h` 而不是 `5m`，唯一多付的成本是写入费贵 ¥20（¥40 vs ¥20）。 * 之后每命中一次缓存，这部分输入的成本从 ¥20 降到 ¥2，省 ¥18。 * 所以：命中 1 次，省 ¥18；命中 2 次，共省 ¥36，扣掉多付的 ¥20，选择 `1h` 比选择 `5m` 净省 ¥16。 5m 与 1h 累计费用对比：命中 2 次后选择 1h 更划算 缓存条目的 TTL 在首次写入时锁定，不能改写：相同前缀命中后按原 TTL 免费续期，新增部分也按锁定的 TTL 继续写入。已有条目完全过期后，才能用新的 TTL 重新写入。 ## 如何设置缓存 TTL Chat Completions API 和 Responses API 在省略 `prompt_cache_options` 时默认按 `5m` TTL 写入缓存。需要指定 TTL 时，传入 `prompt_cache_options`： ```bash theme={null} # 将 prompt_cache_options.ttl 设置为 "5m" 或 "1h"。 curl https://api.moonshot.cn/v1/chat/completions \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $MOONSHOT_API_KEY" \ --data '{ "model": "kimi-k3", "messages": [ {"role": "system", "content": "你是一个产品文档问答助手。\n\n产品文档：……"}, {"role": "user", "content": "这个产品支持哪些认证方式？"} ], "prompt_cache_options": {"mode": "implicit", "ttl": "1h"} }' ``` `prompt_cache_options.mode` 当前仅支持 `implicit`，`ttl` 支持 `5m` 和 `1h`。Responses API 使用相同的参数，详见 [Responses API](/docs/api/responses)。 Anthropic Messages API 使用顶层 `cache_control` 控制缓存写入。传入该字段时，请求前缀会按指定 TTL 写入缓存；省略该字段时，本次请求只读取 `5m` 缓存，不写入缓存： ```bash theme={null} # 将 cache_control.ttl 设置为 "5m" 或 "1h"。 curl https://api.moonshot.cn/anthropic/v1/messages \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $MOONSHOT_API_KEY" \ --data '{ "model": "kimi-k3", "cache_control": {"type": "ephemeral", "ttl": "1h"}, "max_tokens": 256, "messages": [{"role": "user", "content": "你好"}] }' ``` `cache_control` 只在请求顶层生效，消息体内的同名标记会被忽略。完整参数说明见 [Messages API](/docs/api/messages)。 现有请求无需改造。缓存写入拆分后，账单会新增缓存写入明细。 ## 查看缓存读写用量 不同 API 使用不同的 `usage` 字段记录缓存读写情况。依赖 `usage` 字段统计成本的应用，请按下表迁移字段： | API | 总输入 | 缓存读取 | 缓存写入 | | - | - | - | - | | Chat Completions | `usage.prompt_tokens` | `usage.prompt_tokens_details.cached_tokens` | `usage.prompt_tokens_details.cache_write_tokens` | | Responses | `usage.input_tokens` | `usage.input_tokens_details.cached_tokens` | `usage.input_tokens_details.cache_write_tokens` | | Messages | `usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens` | `usage.cache_read_input_tokens` | `usage.cache_creation_input_tokens` | 对于 Chat Completions API 和 Responses API，缓存读取、缓存写入和未缓存部分互斥，三者之和等于总输入 Token 数。Messages 的 `usage.input_tokens` 不包含缓存读取和写入部分；其中 `usage.cache_creation.ephemeral_5m_input_tokens` 和 `usage.cache_creation.ephemeral_1h_input_tokens` 分别记录两个 TTL 下的写入 Token 数。 使用 Chat Completions API 的流式请求时，需要设置 `stream_options.include_usage=true`，完整的缓存读写明细才会出现在最后一个 chunk 的 `usage` 字段中。 ## 常见问题 `kimi-k3` 支持 Cache Write；`kimi-k2.7`、`kimi-k2.7-highspeed`、`kimi-k2.6` 不支持。 相同 TTL 的相同前缀命中缓存后： * 命中部分不再收取 Cache Write 费用，仅按 Cached Input（缓存命中）价格计费，以 `kimi-k3` 为例约为缓存未命中价格的 1/10； * 缓存在有效期内被命中会自动按原 TTL 免费续期，续期不单独收费。 例如：首次请求写入 `1h` 缓存并支付一次写入费用；30 分钟后再请求且命中，缓存从该时间点自动续期 1 小时，后续请求只按缓存命中价格计费。 关键看请求间隔： * 请求间隔稳定小于 5 分钟（如连续调用的 Agent 任务）：默认 `5m` 档即可，命中会免费续期，无需选择 `1h`； * 请求间隔可能超过 5 分钟（长会话、有人工介入的任务）：选择 `1h` 档可以避免缓存过期后重复写入，显著降低成本，同时缩短首 token 延迟（TTFT）。 按定价，`1h` 写入命中 2 次即可覆盖多付的写入费用，命中越多省得越多（算账见「两档 TTL 怎么选」一节）。 `5m` 与 `1h` 是两个缓存不互通；缓存按组织（org）隔离，同一组织内共享，组织之间不共享。缓存不支持手动清除，无活动超过所选 TTL 后自动过期，例如 `5m` 档缓存至少 5 分钟无活动后过期。 不可以。缓存条目的 TTL 在首次写入时锁定，有效期内反复命中也只按原 TTL 免费续期。如需切换 TTL，等该条目完全过期后，再按新 TTL 重新写入。 缓存按块存储，不足一整块的部分无法写入缓存，会计为缓存未命中，按缓存未命中（Input）价格计费。 * 控制台「财务管理 → 账户总览」页面底部的「月账单概览」支持导出每月账单 Excel，导出的表格新增「账单明细-缓存写入」sheet，按天展示 `5m` / `1h` 各自的写入费用，以及项目、组织、API Key 等维度： 「账户总览」页面的月账单概览与导出入口 * 控制台「计费明细 → 请求明细」新增「写缓存 Tokens(5min)」和「写缓存 Tokens(1h)」两列，方便对账；输入 tokens = 缓存未命中 tokens + 缓存命中 tokens + 缓存写入 tokens： 「请求明细」中的写缓存 Tokens 列 以 Chat Completions API 为例，如需在代码中区分本次写入的 TTL，可读取响应 Header： * `Msh-Usage-Cache-Write-Tokens-5m`：本次按 `5m` 档写入的 token 数； * `Msh-Usage-Cache-Write-Tokens-1h`：本次按 `1h` 档写入的 token 数。 本次请求全部命中、没有新增写入时，对应值为 0。 有。控制台新增 [Caching 概览页](https://platform.kimi.com/console/cache)，可以查看各模型在时间范围内的缓存命中 / 未命中 / 缓存写入 tokens 构成、缓存命中率，以及缓存写入摊销倍数（缓存命中 tokens ÷ 缓存写入 tokens，数值越大代表缓存越划算）。 Caching 概览页 ## 相关文档 # 配置多轮对话参数 Source: https://platform.kimi.com/docs/guide/engage-in-multi-turn-conversations-using-kimi-api 在无状态的 Kimi API 中维护消息历史、控制上下文长度，并正确构建多轮对话请求。 与 Kimi 智能助手不同，Kimi API 是 **无状态** 的，本身没有记忆功能：多次请求之间，模型不知道你前一次请求的内容，也不会记住任何上下文——上一次你告诉它今年 27 岁，下一次请求它并不知情。要实现多轮对话，需要手动维护每次请求的上下文（Context），把历史消息随下一次请求一起发送，让模型能看到此前聊过的内容。 本页示例默认使用最新模型 `kimi-k3`。K3 使用请求顶层 `reasoning_effort` 配置推理强度（支持 `"low"` / `"high"` / `"max"`，默认 `"max"`）。换用 `kimi-k2.6` 等其他模型时，只需替换 `model` 字段，但各模型的参数配置存在差异，详见[模型参数参考](/docs/api/models-overview)。 ## 用 messages 列表为模型补上记忆 以下示例改造自上一章节，演示如何通过维护 `messages` 列表让模型拥有记忆：每轮对话把用户的新消息（role=user）和模型的回复（role=assistant）都追加到列表中，再整体随请求发送。实现要点已以注释形式标注在代码中： ```python theme={null} import os from openai import OpenAI client = OpenAI( api_key = os.environ["MOONSHOT_API_KEY"], # 运行前请设置 MOONSHOT_API_KEY 环境变量 base_url = "https://api.moonshot.cn/v1", ) # 我们定义一个全局变量 messages，用于记录我们和 Kimi 大模型产生的历史对话消息 # 在 messages 中，既包含我们向 Kimi 大模型提出的问题（role=user），也包括 Kimi 大模型给我们的回复（role=assistant） # 当然，也包括初始的 System Prompt（role=system） # messages 中的消息按时间顺序从小到大排列 messages = [ {"role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。"}, ] def chat(input: str) -> str: """ chat 函数支持多轮对话，每次调用 chat 函数与 Kimi 大模型对话时，Kimi 大模型都会"看到"此前已经 产生的历史对话消息，换句话说，Kimi 大模型拥有了记忆。 """ global messages # 我们将用户最新的问题构造成一个 message（role=user），并添加到 messages 的尾部 messages.append({ "role": "user", "content": input, }) # 携带 messages 与 Kimi 大模型对话 completion = client.chat.completions.create( model="kimi-k3", messages=messages ) # 通过 API 我们获得了 Kimi 大模型给予我们的回复消息（role=assistant） assistant_message = completion.choices[0].message # 为了让 Kimi 大模型拥有完整的记忆，我们必须将 Kimi 大模型返回给我们的消息也添加到 messages 中 messages.append(assistant_message) return assistant_message.content print(chat("你好，我今年 27 岁。")) print(chat("你知道我今年几岁吗？")) # 在这里，Kimi 大模型根据此前的上下文信息，将会知道你今年的年龄是 27 岁 ``` ```js theme={null} const OpenAI = require("openai") const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, // 运行前请设置 MOONSHOT_API_KEY 环境变量 baseURL: "https://api.moonshot.cn/v1", }); // 我们定义一个全局变量 messages，用于记录我们和 Kimi 大模型产生的历史对话消息 // 在 messages 中，既包含我们向 Kimi 大模型提出的问题（role=user），也包括 Kimi 大模型给我们的回复（role=assistant） // 当然，也包括初始的 System Prompt（role=system） // messages 中的消息按时间顺序从小到大排列 let messages = [ { role: "system", content: "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。", }, ]; async function chat(input) { /** * chat 函数支持多轮对话，每次调用 chat 函数与 Kimi 大模型对话时，Kimi 大模型都会"看到"此前已经 * 产生的历史对话消息，换句话说，Kimi 大模型拥有了记忆。 */ // 我们将用户最新的问题构造成一个 message（role=user），并添加到 messages 的尾部 messages.push({ role: "user", content: input, }); // 携带 messages 与 Kimi 大模型对话 const completion = await client.chat.completions.create({ model: "kimi-k3", messages: messages }); // 通过 API 我们获得了 Kimi 大模型给予我们的回复消息（role=assistant） const assistantMessage = completion.choices[0].message; // 为了让 Kimi 大模型拥有完整的记忆，我们必须将 Kimi 大模型返回给我们的消息也添加到 messages 中 messages.push(assistantMessage); return assistantMessage.content; } // 使用示例 (async () => { console.log(await chat("你好，我今年 27 岁。")); console.log(await chat("你知道我今年几岁吗？")); // 在这里，Kimi 大模型根据此前的上下文信息，将会知道你今年的年龄是 27 岁 })(); ``` 要点回顾： * Kimi API 本身没有上下文记忆功能，需要通过 `messages` 参数手动把"之前聊了什么"告知模型； * `messages` 中既要存用户提出的问题（role=user），也要存模型的回复（role=assistant）。 ## 截断历史消息，控制上下文长度 随着 `chat` 调用次数增多，`messages` 列表不断增长，每次请求消耗的 Tokens 也随之增加，最终列表中的消息会超出模型支持的上下文窗口。建议用某种策略把 `messages` 控制在可控范围内，例如每次只保留最新的 20 条消息作为本次请求的上下文。 以下示例演示如何用 `make_messages` 函数控制每次请求的消息数量（默认保留最新 20 条），注意它如何保证截断后 System Messages 仍然留在列表中： ```python theme={null} import os from openai import OpenAI client = OpenAI( api_key = os.environ["MOONSHOT_API_KEY"], # 运行前请设置 MOONSHOT_API_KEY 环境变量 base_url = "https://api.moonshot.cn/v1", ) # 我们将 System Messages 单独放置在一个列表中，这是因为每次请求都应该携带 System Messages system_messages = [ {"role": "system", "content": "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。"}, ] # 我们定义一个全局变量 messages，用于记录我们和 Kimi 大模型产生的历史对话消息 # 在 messages 中，既包含我们向 Kimi 大模型提出的问题（role=user），也包括 Kimi 大模型给我们的回复（role=assistant） # messages 中的消息按时间顺序从小到大排列 messages = [] def make_messages(input: str, n: int = 20) -> list[dict]: """ 使用 make_messaegs 控制每次请求的消息数量，使其保持在一个合理的范围内，例如默认值是 20。在构建消息列表 的过程中，我们会先添加 System Prompt，这是因为无论如何对消息进行截断，System Prompt 都是必不可少 的内容，再获取 messages —— 即历史记录中，最新的 n 条消息作为请求使用的消息，在大部分场景中，这样 能保证请求的消息所占用的 Tokens 数量不超过模型上下文窗口。 """ global messages # 首先，我们将用户最新的问题构造成一个 message（role=user），并添加到 messages 的尾部 messages.append({ "role": "user", "content": input, }) # new_messages 是我们下一次请求使用的消息列表，现在让我们来构建它 new_messages = [] # 每次请求都需要携带 System Messages，因此我们需要先把 system_messages 添加到消息列表中； # 注意，即使对消息进行截断，也应该注意保证 System Messages 仍然在 messages 列表中。 new_messages.extend(system_messages) # 在这里，当历史消息超过 n 条时，我们仅保留最新的 n 条消息 if len(messages) > n: messages = messages[-n:] new_messages.extend(messages) return new_messages def chat(input: str) -> str: """ chat 函数支持多轮对话，每次调用 chat 函数与 Kimi 大模型对话时，Kimi 大模型都会"看到"此前已经 产生的历史对话消息，换句话说，Kimi 大模型拥有了记忆。 """ # 携带 messages 与 Kimi 大模型对话 completion = client.chat.completions.create( model="kimi-k3", messages=make_messages(input) ) # 通过 API 我们获得了 Kimi 大模型给予我们的回复消息（role=assistant） assistant_message = completion.choices[0].message # 为了让 Kimi 大模型拥有完整的记忆，我们必须将 Kimi 大模型返回给我们的消息也添加到 messages 中 messages.append(assistant_message) return assistant_message.content print(chat("你好，我今年 27 岁。")) print(chat("你知道我今年几岁吗？")) # 在这里，Kimi 大模型根据此前的上下文信息，将会知道你今年的年龄是 27 岁 ``` ```js theme={null} const OpenAI = require("openai") const client = new OpenAI({ apiKey: process.env.MOONSHOT_API_KEY, // 运行前请设置 MOONSHOT_API_KEY 环境变量 baseURL: "https://api.moonshot.cn/v1", }); // 我们将 System Messages 单独放置在一个列表中，这是因为每次请求都应该携带 System Messages const systemMessages = [ { role: "system", content: "你是 Kimi，由 Moonshot AI 提供的人工智能助手，你更擅长中文和英文的对话。你会为用户提供安全，有帮助，准确的回答。同时，你会拒绝一切涉及恐怖主义，种族歧视，黄色暴力等问题的回答。Moonshot AI 为专有名词，不可翻译成其他语言。", }, ]; // 我们定义一个全局变量 messages，用于记录我们和 Kimi 大模型产生的历史对话消息 // 在 messages 中，既包含我们向 Kimi 大模型提出的问题（role=user），也包括 Kimi 大模型给我们的回复（role=assistant） // messages 中的消息按时间顺序从小到大排列 let messages = []; async function makeMessages(input, n = 20) { /** * 使用 make_messages 控制每次请求的消息数量，使其保持在一个合理的范围内，例如默认值是 20。在构建消息列表 * 的过程中，我们会先添加 System Prompt，这是因为无论如何对消息进行截断，System Prompt 都是必不可少的 * 内容，再获取 messages —— 即历史记录中，最新的 n 条消息作为请求使用的消息，在大部分场景中，这样 * 能保证请求的消息所占用的 Tokens 数量不超过模型上下文窗口。 */ // 首先，我们将用户最新的问题构造成一个 message（role=user），并添加到 messages 的尾部 messages.push({ role: "user", content: input, }); // newMessages 是我们下一次请求使用的消息列表，现在让我们来构建它 let newMessages = []; // 每次请求都需要携带 System Messages，因此我们需要先把 systemMessages 添加到消息列表中； // 注意，即使对消息进行截断，也应该注意保证 System Messages 仍然在 messages 列表中。 newMessages = systemMessages.concat(newMessages); // 在这里，当历史消息超过 n 条时，我们仅保留最新的 n 条消息 if (messages.length > n) { messages = messages.slice(-n); } newMessages = newMessages.concat(messages); return newMessages; } async function chat(input) { /** * chat 函数支持多轮对话，每次调用 chat 函数与 Kimi 大模型对话时，Kimi 大模型都会"看到"此前已经 * 产生的历史对话消息，换句话说，Kimi 大模型拥有了记忆。 */ // 携带 messages 与 Kimi 大模型对话 const completion = await client.chat.completions.create({ model: "kimi-k3", messages: await makeMessages(input) }); // 通过 API 我们获得了 Kimi 大模型给予我们的回复消息（role=assistant） const assistantMessage = completion.choices[0].message; // 为了让 Kimi 大模型拥有完整的记忆，我们必须将 Kimi 大模型返回给我们的消息也添加到 messages 中 messages.push(assistantMessage); return assistantMessage.content; } (async () => { console.log(await chat("你好，我今年 27 岁。")); console.log(await chat("你知道我今年几岁吗？")); // 在这里，Kimi 大模型根据此前的上下文信息，将会知道你今年的年龄是 27 岁 })(); ``` ## 生产环境还需要考虑什么 上述代码示例仅覆盖最简单的调用场景，实际业务中可能还需要处理更多场景和边界： * 并发场景下可能需要额外的读写锁； * 多用户场景需要为每个用户单独维护 `messages` 列表； * 对 `messages` 列表进行持久化； * 用更精确的方式计算 `messages` 列表中需要保留多少条消息； * 对被遗弃的消息做一次总结，生成一条新消息加入 `messages` 列表； * …… # 在 Kimi Code CLI 中使用 Kimi API Platform Source: https://platform.kimi.com/docs/guide/kimi-code-cli 使用 Kimi API Platform API Key 接入、切换和更新 Kimi Code CLI。 [Kimi Code](https://www.kimi.com/code/) 是面向开发者的智能编程服务，Kimi Code CLI 是其运行在终端中的 AI Agent。 Kimi Code CLI 可以直接使用在 [Kimi API Platform](https://platform.kimi.com/) 创建的 API Key。 本文介绍如何： * 使用 `platform.kimi.com` 的 API Key 完成接入 * 将现有 Kimi Code CLI 切换到 Kimi API Platform * 更换已经配置的 API Key 本文假设你已经安装 Kimi Code CLI。 尚未安装时，请参考 [Kimi Code CLI 官方安装方式](https://www.kimi.com/code/docs/kimi-code-cli/guides/getting-started.html)，或选择系统直接运行： ```bash theme={null} curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash ``` ```powershell theme={null} irm https://code.kimi.com/kimi-code/install.ps1 | iex ``` Windows 用户首次启动前还需要安装 [Git for Windows](https://gitforwindows.org/)。Kimi Code CLI 会使用其中的 Git Bash 作为 Shell 环境。如果 Git Bash 安装在非标准路径，请把 `KIMI_SHELL_PATH` 设为 `bash.exe` 的绝对路径。 脚本会自动下载最新版本、校验 checksum，并把 `kimi` 可执行文件放到你的 `PATH` 中。 ## 准备 API Key 打开 [Kimi API Platform](https://platform.kimi.com/)，登录后进入 [API Keys](https://platform.kimi.com/console/api-keys) 页面，创建并复制一个 API Key。 请妥善保管 API Key，不要与他人分享，也不要在截图中展示完整内容。 ## 接入 Kimi API Platform ### 1. 启动 Kimi Code CLI 进入需要使用 Kimi Code CLI 的项目目录，然后启动： ```bash theme={null} kimi ``` 进入交互界面后，在输入框中执行： ```text theme={null} /login ``` Kimi Code CLI 将打开平台选择界面。 在 Kimi Code CLI 中输入 /login ### 2. 选择 API Key 所属平台 在平台列表中，选择与 API Key 来源一致的选项： | API Key 来源 | 在 Kimi Code CLI 中选择 | | - | - | | `platform.kimi.com` | `Kimi Platform (API key · platform.kimi.com)` | 使用方向键选择平台，然后按 `Enter` 确认。 必须选择与 API Key 创建站点一致的平台，否则 API Key 校验将失败。 选择 platform.kimi.com 对应的 Kimi Platform ### 3. 输入 API Key 根据界面提示粘贴刚刚创建的 API Key，然后按 `Enter`。 Kimi Code CLI 会自动校验 API Key，并读取当前账户可用的模型。 输入 Kimi API Platform API Key ### 4. 选择模型 API Key 校验通过后，界面会显示当前账户可用的模型。选择需要使用的模型并确认。 完成后，Kimi Code CLI 会： * 切换当前会话使用的模型 * 保存本次平台和模型选择 * 在后续启动时继续使用该配置 看到配置完成提示后，即表示 Kimi API Platform 已成功接入。 选择 Kimi API Platform 模型 ### 5. 验证接入结果 执行以下命令查看当前会话状态： ```text theme={null} /status ``` 确认当前模型后，再发送一个简单任务，例如： ```text theme={null} 请查看当前项目，并简要说明目录结构。 ``` 如果 Kimi Code CLI 能够正常返回结果，即表示接入成功。 Kimi Code CLI 使用 Kimi API Platform 正常回复 ## 切换到 Kimi API Platform API Key 如果 Kimi Code CLI 已经在使用其他登录方式，无需退出程序，也无需手动修改配置。 在当前会话中重新执行： ```text theme={null} /login ``` 然后依次完成： 1. 选择 `Kimi Platform (API key · platform.kimi.com)` 2. 输入 Kimi API Platform API Key 3. 选择需要使用的模型 4. 等待配置完成提示 完成后，当前会话会直接切换到新选择的 Kimi API Platform 模型，不需要重新启动 Kimi Code CLI。 ## 更换 API Key 如果需要更换已经配置的 API Key，再次执行 `/login`，选择 `Kimi Platform (API key · platform.kimi.com)` 并输入新的 API Key 即可。 新配置完成后，Kimi Code CLI 将使用新的 API Key。 ## 常见问题 ### API Key 校验失败 请依次检查： * 是否选择了 API Key 实际创建所在的平台 * API Key 是否复制完整，是否包含多余空格 * API Key 是否仍然有效 * 对应的 Kimi API Platform 账户是否可以正常调用 API 如果 API Key 已被撤销或泄露，请在 Kimi API Platform 中创建新的 API Key，然后重新执行 `/login`。 ### 无法执行 `/login` `/login` 需要在 Kimi Code CLI 空闲时执行。如果当前正在生成内容或执行任务，请等待任务结束，或先按 `Esc` 或 `Ctrl-C` 中断，再重新执行 `/login`。 ### 没有显示可用模型 请确认 API Key 和所选平台一致，然后重新执行 `/login`。如仍然无法加载，可以先升级 Kimi Code CLI，再检查 Kimi API Platform 账户状态。 ## 了解更多 * [Kimi Code CLI 开始使用](https://www.kimi.com/code/docs/kimi-code-cli/guides/getting-started.html) * [Kimi Code CLI 斜杠命令](https://www.kimi.com/code/docs/kimi-code-cli/reference/slash-commands.html) * [Kimi Code CLI 平台与模型](https://www.kimi.com/code/docs/kimi-code-cli/configuration/providers.html) * [Kimi Code CLI 配置文件](https://www.kimi.com/code/docs/kimi-code-cli/configuration/config-files.html) * [Kimi API Platform 快速开始](/docs/get-api-key) # Kimi K2.6 Source: https://platform.kimi.com/docs/guide/kimi-k2-6-quickstart 了解 Kimi K2.6 的文本、图片与视频理解、思考模式、工具调用和 256K 上下文能力。 ## Kimi K2.6 模型介绍 Kimi K2.6 是 Kimi 的通用模型，Kimi K2.6 的通用 Agent、代码、视觉理解等综合能力得到全面提升，其中在博士级难度的完整版人类最后的考试（Humanity's Last Exam）、在考察模型真实软件工程能力的 SWE-Bench Pro、评估 Agent 深度检索能力的 DeepSearchQA 等基准测试中均取得行业领先的成绩，同时支持文本、图片与视频输入，思考与非思考模式，对话与 Agent 任务。 [技术Blog](https://www.kimi.com/blog/kimi-k2-6) 。 kimi-k2.6 ### 长程编码能力突破 * Kimi K2.6 作为国内领先的 Coding 模型，在长程代码任务中的表现取得了突破，面对不同编程语言（如 Rust、Go、Python）和任务场景（如前端、运维、性能优化）均具备更可靠的泛化能力。 ### 超长上下文支持 * `kimi-k2.7-code`、`kimi-k2.6` 模型均提供 256K 上下文窗口 ### 长思考能力 * Kimi K2.6 仍然具备超强的思考能力，支持多步工具调用和推理，擅长解决复杂问题，如复杂的逻辑推理、数学问题、代码编写等。 ## 立即开始 * [立即体验](https://platform.kimi.com/playground) ：在开发工作台，快速通过交互式操作测试模型在业务场景上的效果 * [申请 API Key](https://platform.kimi.com/console/api-keys) ：立即通过 API 调用测试 ## 调用示例 以下是完整的调用示例，帮助您快速上手 Kimi K2.6 模型。 ### 安装 OpenAI SDK Kimi API 完全兼容 OpenAI 的 API 格式，你可以通过如下方式来安装 OpenAI SDK： ```bash theme={null} pip install --upgrade 'openai>=1.0' ``` ### 验证安装结果 ```bash theme={null} python -c 'import openai; print("version =",openai.__version__)' # 输出可能是 version = 1.10.0，表示 OpenAI SDK 已经安装成功，当前 python 实际使用了 openai 的 v1.10.0 的库 ``` ### 图片理解代码示例 ```python theme={null} import os import base64 from openai import OpenAI client = OpenAI( api_key=os.environ.get("MOONSHOT_API_KEY"), base_url="https://api.moonshot.cn/v1", ) # 在这里，你需要将 kimi.png 文件替换为你想让 Kimi 识别的图片的地址 image_path = "kimi.png" with open(image_path, "rb") as f: image_data = f.read() # 我们使用标准库 base64.b64encode 函数将图片编码成 base64 格式的 image_url image_url = f"data:image/{os.path.splitext(image_path)[1].lstrip('.')};base64,{base64.b64encode(image_data).decode('utf-8')}" completion = client.chat.completions.create( model="kimi-k2.6", messages=[ {"role": "system", "content": "你是 Kimi。"}, { "role": "user", # 注意这里，content 由原来的 str 类型变更为一个 list，这个 list 中包含多个部分的内容，图片（image_url）是一个部分（part）， # 文字（text）是一个部分（part） "content": [ { "type": "image_url", # <-- 使用 image_url 类型来上传图片，内容为使用 base64 编码过的图片内容 "image_url": { "url": image_url, }, }, { "type": "text", "text": "请描述图片的内容。", # <-- 使用 text 类型来提供文字指令，例如"描述图片内容" }, ], }, ], ) print(completion.choices[0].message.content) ``` ### 视频理解代码示例 ```python theme={null} import os import base64 from openai import OpenAI client = OpenAI( api_key=os.environ.get("MOONSHOT_API_KEY"), base_url="https://api.moonshot.cn/v1", ) # 在这里，你需要将 kimi.mp4 文件替换为你想让 Kimi 识别的视频的地址 video_path = "kimi.mp4" with open(video_path, "rb") as f: video_data = f.read() # 我们使用标准库 base64.b64encode 函数将视频编码成 base64 格式的 video_url video_url = f"data:video/{os.path.splitext(video_path)[1].lstrip('.')};base64,{base64.b64encode(video_data).decode('utf-8')}" completion = client.chat.completions.create( model="kimi-k2.6", messages=[ {"role": "system", "content": "你是 Kimi。"}, { "role": "user", # 注意这里，content 由原来的 str 类型变更为一个 list，这个 list 中包含多个部分的内容，视频（video_url）是一个部分（part）， # 文字（text）是一个部分（part） "content": [ { "type": "video_url", # <-- 使用 video_url 类型来上传视频，内容为使用 base64 编码过的视频内容 "video_url": { "url": video_url, }, }, { "type": "text", "text": "请描述视频的内容。", # <-- 使用 text 类型来提供文字指令，例如"描述视频内容" }, ], }, ], ) print(completion.choices[0].message.content) ``` ### 多模态工具能力示例 Kimi K2.6 模型综合了多种能力。以下是一个展示 K2.6 视觉理解+工具调用能力的示例。 首先将这个示例视频下载到本地，比如 `/path/to/test_video.mp4`