• AI 应用
• 后端

本篇技术指南以 README.md 为主线，系统讲解 kimi-free-api 的接入准备、多平台部署、OpenAI 兼容接口的完整调用方式（对话补全、文档解读、图像解析、Token 存活检测），并结合仓库源码深入剖析其 access_token 刷新、会话生命周期、多轮对话合并、文件上传与流式输出等底层实现。读完本文，你将能够独立完成 kimi-free-api 的部署，并基于/v1/chat/completions接口将 KIMI 长文本能力接入任意 OpenAI 兼容客户端。

项目概览：能做什么、边界在哪里

kimi-free-api 是一个基于 KIMI（月之暗面 Moonshot AI）网页端接口实现的逆向 API 服务，将 KIMI 的长文本解读与整理能力包装为标准的 OpenAI 兼容接口。根据 README.md 的说明，它支持以下核心能力：

• 高速流式输出：兼容 SSE 流式响应，逐字返回生成内容；
• 多轮对话：基于消息合并实现多轮上下文，同时支持通过conversation_id接续原生会话；
• 联网搜索：kimi-search模型可实时检索网页；
• 智能体对话：支持以智能体 ID 作为 model 调用官方智能体；
• 探索版（research）、K1 思考模型、数学模型；
• 长文档解读：支持可访问文件 URL 或 BASE64 数据上传解析；
• 图像解析（OCR）：兼容 gpt-4-vision-preview 格式；
• 零配置部署、多路 Token 支持、自动清理会话痕迹；
• 与 ChatGPT 接口完全兼容，可直接对接 dify 等线上服务及各类 OpenAI 兼容客户端。

需要特别强调的是，README 中的免责声明同样适用于本文介绍的一切用法：逆向 API 是不稳定的，官方推荐前往 MoonshotAI 开放平台付费使用以避免封禁风险；项目为纯粹研究交流学习性质，不接受任何资金捐助和交易；仅限自用，禁止对外提供服务或商用，避免对官方造成服务压力，否则风险自担。

从仓库看，本项目基于 TypeScript + Koa 构建（见 package.json，依赖 koa、axios、eventsource-parser、koa-router 等），通过 tsup 编译打包，入口为 src/index.ts，路由统一注册于 src/api/routes/index.ts，其中/ping提供存活探活，/v1/models返回 OpenAI 兼容的模型列表，核心对话逻辑集中在 src/api/controllers/chat.ts。

效果示例：验证可用性与真实响应

README 提供了多组真实运行截图，用于「验明正身」与功能演示。其中验明正身 Demo 展示了服务端正确返回 Kimi 自我介绍、模型名与 usage 信息：

其余示例还包括多轮对话 Demo（doc/example-6.png）、联网搜索 Demo（doc/example-2.png）、使用翻译通智能体的智能体对话 Demo（doc/example-7.png）、长文档解读 Demo（doc/example-5.png）以及图像 OCR Demo（doc/example-3.png）。这些截图对应的请求与响应格式，将在下文「接口列表与调用实战」一节中给出完整可复现的 JSON 示例。

接入准备：获取 refresh_token 与多账号配置

访问 kimi.moonshot.cn，随便发起一个对话，按 F12 打开开发者工具，在 Application > Local Storage 中找到refresh_token的值。该值将作为请求头Authorization: Bearer TOKEN的 Bearer Token 使用：

Authorization: Bearer TOKEN

如果你看到的refresh_token是一个数组，请使用.拼接后再使用（见 README 配图 doc/example-8.jpg）。

多账号接入：突破频率限制

README 指出，Kimi 限制普通账号每 3 小时内只能进行 30 轮长文本问答（短文本不限）。kimi-free-api 支持一次提供多个账号的 refresh_token，使用英文逗号,拼接：

Authorization: Bearer TOKEN1,TOKEN2,TOKEN3

每次请求服务会从中随机挑选一个 Token 使用。在源码中，这一逻辑由tokenSplit与 lodash 的_.sample实现（见 src/api/routes/chat.ts）：tokenSplit将Bearer前缀剥离并按逗号切分 Token 列表，随后随机抽取一个用于本次请求，从而实现多账号负载分摊。

部署方案：Docker / Compose / 云平台 / 原生四选一

README 提供了五种部署方式，任选其一即可。所有方式均要求设备或服务器能够访问网络，并开放8000 端口。

Docker 部署

拉取镜像并启动服务（设置时区为上海）：

docker run -it -d --init --name kimi-free-api -p 8000:8000 -e TZ=Asia/Shanghai vinlic/kimi-free-api:latest

日常运维命令：

# 查看服务实时日志 docker logs -f kimi-free-api # 重启服务 docker restart kimi-free-api # 停止服务 docker stop kimi-free-api

仓库内的 Dockerfile 采用两阶段构建：第一阶段在 node:lts 中执行yarn install与yarn run build编译产出 dist；第二阶段使用 node:lts-alpine 精简镜像，仅拷贝 public、configs、package.json、dist 与 node_modules，暴露 8000 端口并以npm start启动。

Docker-compose 部署

version: '3' services: kimi-free-api: container_name: kimi-free-api image: vinlic/kimi-free-api:latest restart: always ports: - "8000:8000" environment: - TZ=Asia/Shanghai

Render 部署

按 README 步骤操作：

1. fork 本项目到你的 GitHub 账号下；
2. 访问 Render 并登录 GitHub 账号；
3. 构建 Web Service（New+ -> Build and deploy from a Git repository -> Connect 你 fork 的项目 -> 选择部署区域 -> 选择实例类型为 Free -> Create Web Service）；
4. 等待构建完成后，复制分配的域名并拼接 URL 访问即可。

注意事项：部分部署区域可能无法连接 Kimi，若容器日志出现请求超时或无法连接（新加坡实测不可用），请切换其他区域部署；免费账户的容器实例在一段时间不活动时会自动停止，导致下次请求遇到 50 秒或更长的延迟，建议参考 free-api-hub 中的容器保活方案。

Vercel 部署

注意：Vercel 免费账户的请求响应超时时间为 10 秒，而接口响应通常较久，可能遇到 Vercel 返回的 504 超时错误。

请先确保本地安装了 Node.js 环境，然后依次执行：

npm i -g vercel --registry http://registry.npmmirror.com vercel login git clone https://github.com/LLM-Red-Team/kimi-free-api cd kimi-free-api vercel --prod

仓库根目录的 vercel.json 即为平台部署的适配配置文件。

Zeabur 部署

注意：免费账户的容器实例可能无法稳定运行。可通过 Zeabur 模板一键部署（官方模板页提供 Deploy on Zeabur 按钮）。

原生部署（Node.js + PM2）

请准备一台具有公网 IP 的服务器并开放 8000 端口，先安装好 Node.js 环境并确认node命令可用：

# 安装依赖 npm i # 安装 PM2 进行进程守护 npm i -g pm2 # 编译构建，看到 dist 目录即构建完成 npm run build # 启动服务 pm2 start dist/index.js --name "kimi-free-api"

日常运维命令：

# 查看服务实时日志 pm2 logs kimi-free-api # 重启服务 pm2 reload kimi-free-api # 停止服务 pm2 stop kimi-free-api

与 package.json 中的脚本对应：npm run build即tsup src/index.ts --format cjs,esm --sourcemap --dts --clean --publicDir public，产出dist/index.js（CJS）与dist/index.mjs（ESM）两个入口；npm start使用node --enable-source-maps --no-node-snapshot dist/index.js启动。

服务配置：端口与时区

默认端口 8000 由 configs/dev/service.yml 定义：

# 服务名称 name: kimi-free-api # 服务绑定主机地址 host: '0.0.0.0' # 服务绑定端口 port: 8000

系统级配置（请求日志、日志目录、公共目录、临时文件有效期等）见 configs/dev/system.yml，对应默认值由 src/lib/configs/system-config.ts 中的构造函数兜底（如requestLog默认 false、logWriteInterval默认 200ms、tmpFileExpires默认 86400000ms）。服务配置加载逻辑见 src/lib/configs/service-config.ts：读取 YAML 后与环境变量合并，name/host/port均可通过环境变量覆盖。

推荐使用客户端

README 推荐使用以下二次开发客户端接入 free-api 系列项目，它们更快更简单，且支持文档/图像上传：

• 由 Clivia 二次开发的 LobeChat 分支；
• 由 时光@ 二次开发的 ChatGPT Web（chatgpt-web-sea）分支。

此外，由于接口与 OpenAI 兼容，也可以直接使用任何 OpenAI 兼容客户端，或通过 dify 等线上服务编排接入。

接口列表与调用实战

目前服务支持与 OpenAI 兼容的/v1/chat/completions接口，请求与响应格式与 OpenAI 官方文档保持一致。所有接口均需在 header 中设置：

Authorization: Bearer [refresh_token]

对话补全

POST /v1/chat/completions

请求数据（README 原文，含注释说明）：

{ // 模型名称 // kimi：默认模型 // kimi-search：联网检索模型 // kimi-research：探索版模型 // kimi-k1：K1模型 // kimi-math：数学模型 // kimi-silent：不输出检索过程模型 // search/research/k1/math/silent：可自由组合使用 // 如果使用kimi+智能体，model请填写智能体ID，就是浏览器地址栏上尾部的一串英文+数字20个字符的ID "model": "kimi", // 目前多轮对话基于消息合并实现，某些场景可能导致能力下降且受单轮最大Token数限制 // 如果您想获得原生的多轮对话体验，可以传入首轮消息获得的id，来接续上下文，注意如果使用这个，首轮必须传none，否则第二轮会空响应！ // "conversation_id": "cnndivilnl96vah411dg", "messages": [ { "role": "user", "content": "测试" } ], // 是否开启联网搜索，默认false "use_search": true, // 如果使用SSE流请设置为true，默认false "stream": false }

响应数据：

{ // 如果想获得原生多轮对话体验，此id，你可以传入到下一轮对话的conversation_id来接续上下文 "id": "cnndivilnl96vah411dg", "model": "kimi", "object": "chat.completion", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "你好！我是Kimi，由月之暗面科技有限公司开发的人工智能助手。我擅长中英文对话，可以帮助你获取信息、解答疑问，还能阅读和理解你提供的文件和网页内容。如果你有任何问题或需要帮助，随时告诉我！" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2 }, "created": 1710152062 }

模型组合规则：README 说明search/research/k1/math/silent这些后缀可以自由组合，例如使用kimi-search时开启联网检索。在源码 src/api/controllers/chat.ts 中，请求体里的use_search若为 true 会被路由层强制改写为kimi-search模型（见 src/api/routes/chat.ts）；而模型名称则通过indexOf判断是否包含math、search、research、k1等关键字来分别控制use_math、use_research、use_search标志位，K1 模型内部会映射为固定的 kimiplus_idcrm40ee9e5jvhsn7ptcg，若 model 是 20 位英文数字混合的智能体 ID 则直接作为 kimiplus_id 使用。

流式输出：当stream: true时，服务通过 src/api/controllers/chat.ts 中的createTransStream将 Kimi 网页端的 SSE 事件（cmpl/req/length/search_plus/all_done/error等）转换为 OpenAI 格式的chat.completion.chunk数据块，并以data: [DONE]结尾，响应 Content-Type 为text/event-stream。联网搜索时，搜索过程会以【检索 N】 标题的形式作为增量内容输出；若使用kimi-silent模型则静默检索，不输出检索过程。

文档解读

提供一个可访问的文件 URL 或者 BASE64 数据进行解析。

POST /v1/chat/completions

请求数据：

{ // 模型名称 // kimi：默认模型 // kimi-search：联网检索模型 // kimi-research：探索版模型 // kimi-k1：K1模型 // kimi-math：数学模型 // kimi-silent：不输出检索过程模型 // search/research/k1/math/silent：可自由组合使用 // 如果使用kimi+智能体，model请填写智能体ID，就是浏览器地址栏上尾部的一串英文+数字20个字符的ID "model": "kimi", "messages": [ { "role": "user", "content": [ { "type": "file", "file_url": { "url": "https://mj101-1317487292.cos.ap-shanghai.myqcloud.com/ai/test.pdf" } }, { "type": "text", "text": "文档里说了什么？" } ] } ], // 建议关闭联网搜索，防止干扰解读结果 "use_search": false }

响应数据（摘要节选）：

{ "id": "cnmuo7mcp7f9hjcmihn0", "model": "kimi", "object": "chat.completion", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "文档中包含了几个古代魔法咒语的例子，这些咒语来自古希腊和罗马时期的魔法文本，被称为PGM（Papyri Graecae Magicae）。以下是文档中提到的几个咒语的内容：……" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2 }, "created": 100920 }

底层实现：当消息 content 中出现type: "file"时，extractRefFileUrls会提取其中的file_url.url；随后uploadFile依次完成：预检查 URL 可用性（checkFileUrl，HEAD 请求校验状态码与 100MB 大小上限）、通过/api/pre-sign-url获取预签名上传地址、将文件 PUT 上传到目标对象存储、轮询/api/file获取文件 ID 并等待解析完成（parse_process），最终得到refs文件 ID 列表随对话请求一起提交给 Kimi。BASE64 数据（data:协议开头）会被识别后解码为 Buffer 再走同一流程。

图像解析（OCR）

提供一个可访问的图像 URL 或者 BASE64 数据进行解析。此格式兼容 gpt-4-vision-preview API 格式，你也可以用这个格式传送文档进行解析。

POST /v1/chat/completions

请求数据：

{ // 模型名称 // kimi：默认模型 // kimi-search：联网检索模型 // kimi-research：探索版模型 // kimi-k1：K1模型 // kimi-math：数学模型 // kimi-silent：不输出检索过程模型 // search/research/k1/math/silent：可自由组合使用 // 如果使用kimi+智能体，model请填写智能体ID，就是浏览器地址栏上尾部的一串英文+数字20个字符的ID "model": "kimi", "messages": [ { "role": "user", "content": [ { "type": "image_url", "image_url": { "url": "https://www.moonshot.cn/assets/logo/normal-dark.png" } }, { "type": "text", "text": "图像描述了什么？" } ] } ], // 建议关闭联网搜索，防止干扰解读结果 "use_search": false }

响应数据：

{ "id": "cnn6l8ilnl92l36tu8ag", "model": "kimi", "object": "chat.completion", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "图像中展示了“Moonshot AI”的字样，这可能是月之暗面科技有限公司（Moonshot AI）的标志或者品牌标识。通常这样的图像用于代表公司或产品，传达品牌信息。由于图像是PNG格式，它可能是一个透明背景的logo，用于网站、应用程序或其他视觉材料中。" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2 }, "created": 1710123627 }

在源码中，type: "image_url"与type: "file"是同一套上传管道：extractRefFileUrls同时识别两种格式并提取url，上传时依据 MIME 类型判断是走 image 还是 file 通道（见 src/api/controllers/chat.ts 中的uploadFile）。

refresh_token 存活检测

检测 refresh_token 是否存活，如果存活live为 true，否则为 false。请不要频繁（小于 10 分钟）调用此接口。

POST /token/check

请求数据：

{ "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..." }

响应数据：

{ "live": true }

该路由定义于 src/api/routes/token.ts，内部调用chat.getTokenLiveStatus：它会真实地向 Kimi 的/api/auth/token/refresh发起一次刷新请求，若能同时取回access_token与refresh_token则判定为存活（见 src/api/controllers/chat.ts）。

原理剖析：一次对话请求的完整链路

结合 src/api/controllers/chat.ts，可以还原一次请求在 kimi-free-api 内部的处理流程：

1. Token 刷新与缓存：acquireToken以 refresh_token 为键查询内存缓存accessTokenMap，未命中或超过有效期（ACCESS_TOKEN_EXPIRES = 300秒）时调用requestToken向/api/auth/token/refresh换取 access_token，并顺带请求/api/user获取用户 ID（作为后续请求的X-Traffic-Id）。并发场景下同一 refresh_token 的刷新请求会进入队列等待，避免短时间重复刷新。

2. 创建会话：createConversation调用POST /api/chat创建临时会话（会话名为「未命名会话」），除非传入conversation_id复用已有会话。

3. 消息预处理与多轮合并：messagesPrepare将多条消息合并为一条 user 消息（格式如user:旧消息1\nassistant:旧消息2\nuser:新消息）；从第二轮开始会在最新消息前注入 system prompt（如「关注用户最新的消息」，若最新消息含文件/图片则注入「关注用户最新发送文件和消息」）以提升模型对尾部内容的注意力；用户消息中的 URL 会被wrapUrlsToTags包装为<url>标签以模拟网页版行为，否则 Kimi 端无法成功解析。

4. 并行预调用：preN2s（联网搜索预处理）、getSuggestion（获取建议）、tokenSize（Token 计数）等请求并行发出但错误被吞掉，用于模拟真实浏览行为（另有fakeRequest随机调用一批用户接口进行伪装访问）。

5. 模型路由与额度检查：若为探索版模型，先请求/api/chat/research/usage检查剩余额度，已用完则抛出「探索版使用量已达到上限」异常。

6. 流式补全：请求POST /api/chat/{convId}/completion/stream，同步模式由receiveStream聚合为完整响应；流式模式由createTransStream实时转换为 OpenAI chunk 格式。

7. 超长续写与自动清理：若finish_reason == 'length'（生成达到 max_tokens），会用返回的segment_id继续请求拼接完整响应（同步模式，最多通过MAX_RETRY_COUNT = 3、RETRY_DELAY = 5000毫秒进行失败重试）；流传输结束后异步调用DELETE /api/chat/{convId}移除临时会话，这就是 README 所述「自动清理会话痕迹」的实现——除非使用了conversation_id引用会话，此时会话保留以支持后续多轮接续。

注意事项与运维优化

Nginx 反代优化

若使用 Nginx 反向代理 kimi-free-api，README 建议添加以下配置以优化流式输出的体验：

# 关闭代理缓冲。当设置为off时，Nginx会立即将客户端请求发送到后端服务器，并立即将从后端服务器接收到的响应发送回客户端。 proxy_buffering off; # 启用分块传输编码。分块传输编码允许服务器为动态生成的内容分块发送数据，而不需要预先知道内容的大小。 chunked_transfer_encoding on; # 开启TCP_NOPUSH，这告诉Nginx在数据包发送到客户端之前，尽可能地发送数据。这通常在sendfile使用时配合使用，可以提高网络效率。 tcp_nopush on; # 开启TCP_NODELAY，这告诉Nginx不延迟发送数据，立即发送小数据包。在某些情况下，这可以减少网络的延迟。 tcp_nodelay on; # 设置保持连接的超时时间，这里设置为120秒。如果在这段时间内，客户端和服务器之间没有进一步的通信，连接将被关闭。 keepalive_timeout 120;

Token 统计说明

由于推理侧不在 kimi-free-api（Token 统计由 Kimi 官方端完成），服务无法获知真实的 Token 消耗。因此响应中的usage字段将以固定数字返回（源码中固定为prompt_tokens: 1, completion_tokens: 1, total_tokens: 2），README 明确提示：不要将其当作真实用量依据。

其他使用提示

• 多轮对话基于消息合并实现，某些场景可能导致能力下降且受单轮最大 Token 数限制；若需原生多轮体验，请将首轮响应中的id作为下一轮请求的conversation_id传入——注意：使用 conversation_id 时首轮必须传 none，否则第二轮会空响应；
• 文档解读与图像解析建议关闭use_search，防止联网搜索干扰解读结果；
• 服务启动后可通过GET /ping返回pong进行健康检查（见 src/api/routes/ping.ts），GET /v1/models则返回 OpenAI 格式的模型列表（见 src/api/routes/models.ts）。

总结

kimi-free-api 以极低的门槛将 Kimi 的长文本、联网搜索、文档与图像解析能力包装为 OpenAI 兼容接口：接入只需从网页端 Local Storage 获取一个 refresh_token，部署既可选择 Docker/Compose 一行命令启动，也可通过 Render、Vercel、Zeabur 等云平台或原生 PM2 方式运行；接口层完整覆盖对话补全、文档解读、图像解析与 Token 存活检测四类能力，并在源码层面实现了 Token 自动刷新缓存、多账号随机轮换、临时会话自动清理、超长续写与失败重试等健壮性机制。需要注意的是，逆向接口存在不稳定性与账号封禁风险，请遵守 README 免责声明，仅限自用与学习研究，生产环境优先使用官方开放平台。

• AI 应用
• 后端