这类免费大模型 API 到底能不能用值不值得投入时间关键不是看宣传而是看它能不能在你的开发环境里稳定跑起来以及能解决什么具体问题。最近围绕 Kimi K3、GLM-5.2 这类 API 的讨论很多但很多信息是零散的比如怎么调用、常见的报错怎么处理、免费额度到底够不够用。我花时间把几个主流平台的 API 都实测了一遍这篇文章就围绕“能用”和“怎么用”这两个核心把环境准备、调用流程、参数避坑、以及遇到400、连接中断、上下文超长这些典型问题时的排查顺序从头到尾拆解清楚。如果你正在找免费或低成本的大模型 API 来集成到自己的项目里或者想对比 Kimi、DeepSeek、通义千问这些服务的实际调用差异那这篇文章就是为你准备的。我会直接给出可运行的代码示例并解释每个参数背后的逻辑让你不仅能跑通还能知道出了问题该从哪里查起。1. 先搞清楚“免费API”到底指什么额度、速率和功能边界很多人一看到“免费”就冲但没搞清楚免费的具体规则结果代码刚跑起来就触发限流或者额度用尽。在动手写代码之前必须先弄明白三件事调用额度、速率限制和模型能力边界。1.1 免费额度与速率限制不是无限畅用目前提供免费 API 调用的服务其“免费”通常指在一个周期内如每月提供一定量的免费 Token 或调用次数。例如Kimi (Moonshot AI)通常通过其开放平台提供新注册用户会获得一定量的免费额度用于体验其kimi-*系列模型如kimi-latest。这个额度用完后调用会失败或需要充值。DeepSeek在其官方平台注册后也会提供免费 API 额度可用于deepseek-chat等模型。智谱 AI (GLM)对 GLM-3 或 GLM-4 系列模型通常也有类似的免费体验额度。通义千问阿里云的通义千问 API新用户也有免费套餐。关键点这个免费额度是按 Token 消耗计算的不是按调用次数。你发送的提示词Prompt和模型返回的内容都算 Token。一段长对话会快速消耗额度。因此在测试和开发初期一定要先通过平台的控制台或接口查询剩余额度。速率限制Rate Limit是另一个隐形门槛。它规定了你在单位时间如每秒、每分钟内能发起的请求数。即使你额度充足短时间内发送大量请求也会被拒绝返回429 Too Many Requests错误。对于免费 tier这个限制通常比较严格。我的建议拿到 API Key 后第一件事不是写业务逻辑而是写一个最简单的GET请求去查询余额和速率限制详情。这能让你对“免费”的尺度有直观认识。1.2 模型能力与上下文长度选择匹配任务的模型“打爆了”这种说法容易让人误解为模型无所不能。实际上每个模型都有其设计侧重点和硬性限制。上下文长度 (Context Length)这是 Kimi 早期的一个主要宣传点支持超长上下文如 128K、甚至更长。这意味着你可以给它一篇很长的文档比如一篇论文、一份长报告让它总结或问答。但是这同时也是最容易触发400 Bad Request错误的地方之一。错误信息常为“this model‘s maximum context length is X tokens. However, your messages resulted in Y tokens.”。你必须确保你发送的消息总 Token 数小于模型支持的最大值。模型类型kimi-latest、deepseek-chat、glm-4这些都是对话模型适合通用聊天、问答、分析和写作。它们通常不支持图像输入多模态。如果你需要视觉理解需要寻找特定的多模态模型 API。代码能力像 DeepSeek 的deepseek-coder系列、Kimi 的代码理解功能在代码生成、解释、调试上表现更好。如果你的任务是代码相关应该优先选择这类模型。行动指南根据你的任务类型长文本分析、编程、创意写作和输入大小去选择最匹配的模型而不是盲目追求最新的模型名称。1.3 API 与网页版的区别稳定性和可控性网页版聊天如kimi.ai和 API 调用是两种不同的使用方式。网页版交互方便适合手动探索和单次任务。但你无法集成到自动化流程中也受限于网页的会话长度限制这就是为什么你会看到“你和 kimi 聊得太长啦新建会话后再聊天试试吧”的提示。API提供了程序化调用的能力可以嵌入你的应用、脚本或服务中。你必须自己管理上下文在请求中携带历史消息自己处理错误和重试同时也获得了更高的灵活性和自动化潜力。很多人遇到的“聊得太长”问题在 API 使用中不会以同样形式出现但会转化为上下文超长400错误或生成中断连接关闭等技术问题需要你用代码逻辑去处理。2. 从零开始获取、配置并测试你的第一个 API 调用理论清楚了我们开始实操。目标是跑通一个最简单的对话请求并确认环境是通的。2.1 第一步获取 API Key 并设置环境注册与获取访问目标平台的开放平台官网如platform.moonshot.cn对应 Kimi。完成注册、实名认证部分平台需要。在控制台找到“API Keys”或“密钥管理”页面创建一个新的 API Key。创建后立即复制保存因为它通常只显示一次。环境变量配置安全最佳实践永远不要将 API Key 硬编码在代码中尤其是打算公开的代码。使用环境变量。Linux/macOS在终端执行export MOONSHOT_API_KEY‘你的key’临时或写入~/.bashrc/~/.zshrc文件。Windows (PowerShell)$env:MOONSHOT_API_KEY‘你的key’在代码中读取import os api_key os.getenv(‘MOONSHOT_API_KEY’) if not api_key: raise ValueError(“请设置 MOONSHOT_API_KEY 环境变量”)2.2 第二步安装必要的 HTTP 请求库大多数大模型 API 都提供标准的 HTTP RESTful 接口。Python 里最常用的是requests库。pip install requests如果你打算使用官方 SDK如果有安装方式会不同例如pip install openai某些平台兼容 OpenAI SDK 格式。但为了理解原理我们先从最原始的requests开始。2.3 第三步编写并发送第一个请求我们以 Kimi API 为例其他平台结构类似主要是base_url和model参数不同。API 调用核心是构造一个符合平台要求的 JSON 请求体。import requests import json import os # 1. 配置 api_key os.getenv(‘MOONSHOT_API_KEY’) base_url “https://api.moonshot.cn/v1” # Kimi API 地址 model “kimi-latest” # 指定模型 # 2. 构造请求头 headers { “Authorization”: f“Bearer {api_key}”, “Content-Type”: “application/json” } # 3. 构造请求数据 data { “model”: model, “messages”: [ {“role”: “user”, “content”: “你好请用一句话介绍你自己。”} ], “temperature”: 0.7, # 控制随机性0-1越高回答越多样 “max_tokens”: 1024 # 控制回复的最大长度 } # 4. 发送请求 try: response requests.post( f“{base_url}/chat/completions”, headersheaders, jsondata, timeout30 # 设置超时避免长时间等待 ) response.raise_for_status() # 如果状态码不是200抛出异常 result response.json() # 5. 提取回复 reply result[“choices”][0][“message”][“content”] print(“模型回复”, reply) # 打印使用的 Token 数便于监控额度 usage result.get(“usage”, {}) print(f“消耗 Token: 输入{usage.get(‘prompt_tokens’, 0)} 输出{usage.get(‘completion_tokens’, 0)}”) except requests.exceptions.RequestException as e: print(f“请求失败: {e}”) if response is not None: print(f“状态码: {response.status_code}”) print(f“错误信息: {response.text}”)运行这个脚本。如果一切正常你会看到模型的回复和 Token 消耗。这个简单的成功意味着你的 API Key、网络、基础环境都是正确的。3. 深入核心处理复杂对话、流式响应与常见参数单次调用跑通只是第一步。真实应用场景往往涉及多轮对话、处理长内容、或者需要流式输出以提升用户体验。3.1 管理多轮对话上下文API 本身是无状态的。你需要自己在客户端维护对话历史并在每次请求时将所有相关消息发送过去。# 初始化一个对话历史列表 conversation_history [] def chat_with_model(user_input): global conversation_history # 1. 将用户输入加入历史 conversation_history.append({“role”: “user”, “content”: user_input}) # 2. 构造请求数据发送整个历史 data { “model”: “kimi-latest”, “messages”: conversation_history, # 发送全部历史 “temperature”: 0.7, “max_tokens”: 1024 } # ... (发送请求的代码同上) ... # 3. 将模型回复加入历史 if response.status_code 200: result response.json() assistant_reply result[“choices”][0][“message”][“content”] conversation_history.append({“role”: “assistant”, “content”: assistant_reply}) return assistant_reply else: # 处理错误注意错误响应不要加入历史 print(f“请求出错: {response.text}”) return None # 模拟对话 print(chat_with_model(“Python里怎么读取文件”)) print(chat_with_model(“我指的是JSON文件具体怎么做”)) # 模型能基于上文理解“JSON文件”关键点随着对话轮数增加conversation_history会越来越长Token 消耗会快速上升最终可能触发上下文长度限制。在实际应用中需要设计上下文窗口管理策略例如只保留最近 N 轮对话或者对早期历史进行总结压缩。3.2 启用流式响应 (Streaming)默认的请求是“阻塞”的即等待模型完全生成完毕后才一次性返回结果。对于生成时间较长的回复用户体验不好。流式响应允许你像打字机一样逐块接收生成的文本。import requests headers {“Authorization”: f“Bearer {api_key}”, “Content-Type”: “application/json”} data { “model”: “kimi-latest”, “messages”: [{“role”: “user”, “content”: “写一个关于春天的短故事。”}], “stream”: True # 关键参数开启流式 } response requests.post(f“{base_url}/chat/completions”, headersheaders, jsondata, streamTrue) if response.status_code 200: for line in response.iter_lines(): if line: decoded_line line.decode(‘utf-8’) if decoded_line.startswith(‘data: ‘): json_str decoded_line[6:] # 去掉 ‘data: ‘ 前缀 if json_str ‘[DONE]‘: break try: chunk json.loads(json_str) delta chunk[“choices”][0][“delta”] if “content” in delta: print(delta[“content”], end‘’, flushTrue) # 逐块打印 except json.JSONDecodeError: continue else: print(f“流式请求失败: {response.status_code} - {response.text}”)处理流式响应更复杂因为你需要解析 Server-Sent Events (SSE) 格式的数据。上面的代码提供了一个基本框架。使用流式时网络稳定性更重要中途连接断开可能导致回复不完整。3.3 关键参数详解与调优请求体中的参数直接影响模型行为和结果model最重要。必须使用平台支持的模型名称列表中的名字。例如 Kimi 可能是kimi-latest,moonshot-v1-8k等DeepSeek 是deepseek-chat,deepseek-coder等。传错了会直接报400错误提示“the supported api model names are ... but you requested ...”。messages消息列表。每个元素是一个字典包含role(system,user,assistant) 和content。system消息用于设定模型的行为指令如“你是一个有帮助的助手”通常在对话开头设定一次。temperature(0~2)控制随机性。0表示确定性最高相同输入总是得到相似输出1左右是常用值接近2则回答非常随机、有创意。对于需要事实准确性的任务如代码生成、总结建议调低0.1~0.3对于创意写作可以调高0.8~1.2。max_tokens限制模型单次回复的最大长度。必须设置防止模型“自言自语”生成过长内容耗尽你的 Token。根据任务需要设置一般问答 512-1024 足够长文生成可能需要 2048 或更多。top_p(0~1)另一种控制随机性的方式核采样。通常与temperature二选一即可不需要同时调整。stream布尔值是否启用流式响应如上所述。4. 避坑指南解码高频错误与稳定性实战调用 API 时成功是暂时的报错是永恒的。能否快速定位和解决错误是“能用”和“好用”的分水岭。4.1400 Bad Request系列错误这是最常见的客户端错误意味着你的请求格式或内容有问题。“type‘ must be in [”enabled“, ”disabled“, ”auto“]原因这个错误通常出现在请求的某个参数里你传了一个不在允许列表里的值。可能是stream_options或类似扩展参数里的type字段。某些 SDK 或代码示例可能包含了过时或实验性的参数。解决简化你的请求。先只保留最基础的参数model,messages,max_tokens去掉任何非必需的、特别是你不理解的参数。跑通后再逐个添加。“this model‘s maximum context length is ... tokens. However, your messages resulted in ... tokens.”原因你的输入messages里所有内容的 Token 总数超过了模型支持的上限。解决计算 Token在发送前用平台的 Tokenizer 工具如果有或tiktokenOpenAI 格式等库估算 Token 数。不要依赖“字符数”来判断。缩减上下文实施上下文窗口管理。丢弃最早的消息或者对长文档进行分块处理每次只发送相关块。选择更长上下文的模型如果任务必须长上下文确认你调用的模型是否支持例如 Kimi 的某些模型支持 128K。“invalid_parameter_error”原因请求体 JSON 格式错误或某个必需字段缺失、类型不对例如messages不是列表content不是字符串。解决使用json.dumps(data)打印出你的请求体仔细检查结构。确保messages是列表列表里每个元素是字典字典里有role和content键。4.2 连接与超时错误“unable to connect to api (econnreset)”或“connection closed mid-response”原因网络连接不稳定或者在流式响应过程中服务器或客户端主动关闭了连接。解决增加超时时间在requests.post()中设置timeout(10, 30)第一个是连接超时第二个是读取超时。对于长生成任务读取超时要设得足够大。实现重试逻辑对于非流式请求可以使用tenacity等库实现指数退避重试。from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def call_api_with_retry(data): response requests.post(..., jsondata, timeout60) response.raise_for_status() return response流式响应中断需要客户端代码更健壮记录已接收的数据并允许用户手动重试或从断点继续但这需要服务器支持通常较难。4.3 服务端与额度错误429 Too Many Requests原因触发了速率限制。解决降低调用频率。在代码中加入延迟如time.sleep(1)。如果是批量任务使用队列和速率控制器。401 Unauthorized原因API Key 错误、过期或没有权限调用该模型。解决检查 API Key 是否正确是否设置了环境变量以及该 Key 是否有权限访问你请求的模型。5xx服务器错误原因服务端内部错误。解决这不是客户端能解决的。等待一段时间后重试。如果是生产服务需要有告警和降级策略。4.4 免费额度的监控与管理免费额度用完会返回429或402等错误。你必须主动监控在控制台查看定期登录平台控制台查看使用量和剩余额度。通过 API 查询部分平台提供查询额度的 API 接口可以集成到你的监控脚本中。在代码中估算每次调用后解析返回的usage字段累加计算已消耗的 Token并与已知的免费额度对比设置预警阈值。5. 进阶与生产化思考从“跑通”到“好用”当基本调用和错误处理都搞定后要考虑如何将其用于更稳定、更高效的生产环境或复杂项目。5.1 构建一个健壮的客户端类将上述所有逻辑封装成一个类便于管理配置、处理错误、维护上下文和记录日志。import requests import json import time import logging from typing import List, Dict, Optional, Iterator logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) class RobustAIClient: def __init__(self, api_key: str, base_url: str, model: str “kimi-latest”): self.api_key api_key self.base_url base_url.rstrip(‘/’) self.model model self.session requests.Session() self.session.headers.update({ “Authorization”: f“Bearer {api_key}”, “Content-Type”: “application/json” }) self.conversation_history: List[Dict] [] def _make_request(self, endpoint: str, data: Dict, stream: bool False, max_retries: int 3): url f“{self.base_url}/{endpoint.lstrip(‘/’)}” for attempt in range(max_retries): try: resp self.session.post(url, jsondata, streamstream, timeout(10, 60)) resp.raise_for_status() return resp except requests.exceptions.RequestException as e: logger.warning(f“请求失败 (尝试 {attempt 1}/{max_retries}): {e}”) if attempt max_retries - 1: raise wait_time 2 ** attempt # 指数退避 time.sleep(wait_time) return None def chat(self, user_message: str, reset_history: bool False) - Optional[str]: if reset_history: self.conversation_history [] self.conversation_history.append({“role”: “user”, “content”: user_message}) data { “model”: self.model, “messages”: self.conversation_history, “max_tokens”: 1024, “temperature”: 0.7 } try: response self._make_request(“chat/completions”, data) if response: result response.json() assistant_msg result[“choices”][0][“message”] self.conversation_history.append(assistant_msg) logger.info(f“Token 使用: {result.get(‘usage’, {})}”) return assistant_msg[“content”] except Exception as e: logger.error(f“对话失败: {e}”) # 失败时移除刚才添加的用户消息避免污染历史 self.conversation_history.pop() return None # 可以继续添加流式聊天、上下文总结、额度查询等方法 # 使用示例 client RobustAIClient(api_keyos.getenv(‘API_KEY’), base_url“https://api.moonshot.cn/v1”) reply client.chat(“你好”) if reply: print(reply)5.2 上下文长度管理与优化策略对于长文档处理直接塞进messages是不可行的。策略一分块处理 (Chunking)将长文档按段落、章节或固定 Token 数分割成多个块。对每个块单独调用 API 进行总结、问答或提取信息最后再综合结果。策略二摘要递归 (Summarization Recursion)对长文本先进行分段摘要然后将摘要组合起来再进行更高层次的摘要最终得到一个精简的上下文。这需要多次 API 调用但能有效压缩信息。策略三向量检索 (Retrieval)将文档切片后存入向量数据库如 Chroma, FAISS。当用户提问时先从向量库中检索出最相关的几个片段只将这些片段作为上下文发送给模型。这是构建知识库问答系统的核心思路。5.3 多模型路由与降级策略不要绑定死一个模型或一个服务商。路由根据任务类型创意、代码、长文本、推理选择最合适的模型 API。降级当主服务如 Kimi API返回错误或超时时自动切换到备用服务如 DeepSeek API。这能极大提升你应用的可用性。实现思路定义一个统一的客户端接口背后封装多个供应商的客户端。在调用时根据配置和错误情况动态选择。5.4 成本与性能监控即使是免费额度也需要监控。记录日志记录每次调用的时间戳、模型、输入输出 Token 数、耗时、是否成功。这有助于分析使用模式和排查问题。设置预算告警如果使用付费额度设置每日或每周的预算上限和告警。性能评估除了成功率还要关注响应延迟 (Latency) 和吞吐量 (Throughput)。对于批量任务异步调用可以显著提升效率。回到最初的问题这玩意儿真能用吗答案是肯定的但“能用”不等于“无脑用”。免费 API 是快速验证想法、构建原型、学习 LLM 集成技术的绝佳资源。关键在于你要像对待任何外部服务一样对待它理解其限制管理好密钥和额度用健壮的代码处理错误和重试并为生产环境设计好降级和扩展方案。从今天给出的代码和排查思路开始把它集成到你的下一个项目里试试看。