简介:调用免费大模型API失败,多数源于额度耗尽、base_url写错和返回内容为空。本文按报错特征、根因和排查步骤逐项说明,给出可直接运行的curl命令与容错调用代码,并整理免费额度的限制清单。读完后,你能快速判断问题出在账户、地址还是模型输出,少走弯路。
免费大模型能跑通原型验证,但开发者常卡在三个地方:额度悄悄用完,接口地址多写或少写一个路径,请求成功却拿不到内容。下面分五节说明每类问题的报错特征、根因和排查步骤,最后给出可直接运行的代码和免费额度的限制清单。
本文适合个人开发者和小团队,主要场景是原型验证和功能试跑。示例以兼容 OpenAI 接口格式的平台为准。具体地址、模型名和错误码请以各平台文档和控制台为准,不同平台可能不同。
调用时返回的典型报错如下:
{"error":{"code":"1113","message":"余额不足或无可用资源包,请充值。"}}
该报错码和文案来自某些平台,其他平台可能返回不同的错误码或 HTTP 状态码。
很多人看到这个报错,第一反应是”我明明有免费额度”,于是反复修改代码。这类问题属于账户侧,代码改得再多也无法解决。常见原因有四个:
排查顺序如下:
model 字段,检查是否完全一致,包括大小写和版本后缀。code 和 message 字段,不要只打印异常字符串,否则容易丢掉关键信息。base_url 写错是高频问题,常见形态有两种:版本号重复,或者把接口路径也写进了 base_url。
# 错误:版本号重复base_url = "https://api.example.com/v1/v1"# 错误:把接口路径写进了 base_url,SDK 会再拼一次路径base_url = "https://api.example.com/v1/chat/completions"# 正确:base_url 只写到版本号,路径交给 SDKbase_url = "https://api.example.com/v1"
检查 base_url 时可以逐项核对四类问题:版本号重复、路径重复、末尾多出或缺少斜杠、从其他平台照抄的代理或网关地址。不同平台的版本前缀并不统一,有的使用 /v1,有的使用 /v2,照抄其他平台的教程很容易出错。
判断问题是否出在 SDK 封装上,可以用 curl 发一次最小请求,直接查看原始返回。密钥只放在环境变量中:
export LLM_API_KEY="你的密钥" # 只在本地终端设置,不要写进代码或提交到仓库curl -sS "https://api.example.com/v1/chat/completions" \-H "Authorization: Bearer $LLM_API_KEY" \-H "Content-Type: application/json" \-w "\nHTTP %{http_code}\n" \-d '{"model": "your-model-name","messages": [{"role": "user", "content": "你好,请只回复一个字:好"}],"max_tokens": 20}'
根据 HTTP 状态码决定下一步:
base_url 和路径是否重复或缺失。model 名称和 JSON 结构是否正确。HTTP 状态码是 200,但 content 为空字符串或 null,这类情况最容易被误判为”接口没问题”。常见根因如下:
finish_reason 为 length:max_tokens 设置过小。带推理过程的模型会先消耗 Token 做推理,正文可能还没输出就被截断。finish_reason 为 content_filter:内容触发了平台的安全策略被拦截。reasoning_content 或 tool_calls,代码却只读取了 content。delta.content 拼接起来。choices 是否为空数组。finish_reason,判断是长度截断、内容过滤还是正常结束。message 中是否还有其他字段,例如推理内容或工具调用结果。max_tokens 调大后复测。下面的代码使用 OpenAI 官方 Python SDK 的调用方式,适用于兼容该格式的平台。运行前先安装依赖,并设置环境变量:
pip install openaiexport LLM_API_KEY="你的密钥"export LLM_BASE_URL="https://api.example.com/v1"export LLM_MODEL="your-model-name"
Windows PowerShell 中使用 $env:LLM_API_KEY="你的密钥" 设置。代码如下:
import osimport sysimport timefrom openai import (OpenAI,APIConnectionError,APIStatusError,APITimeoutError,)API_KEY = os.environ.get("LLM_API_KEY")BASE_URL = os.environ.get("LLM_BASE_URL", "https://api.example.com/v1")MODEL = os.environ.get("LLM_MODEL", "your-model-name")if not API_KEY:sys.exit("缺少环境变量 LLM_API_KEY")client = OpenAI(api_key=API_KEY,base_url=BASE_URL,timeout=30.0,max_retries=0, # 重试次数由下面的循环控制)def ask(prompt: str, max_retries: int = 3) -> str:for attempt in range(1, max_retries + 1):try:resp = client.chat.completions.create(model=MODEL,messages=[{"role": "user", "content": prompt}],max_tokens=512,)except APITimeoutError:print(f"[第{attempt}次] 请求超时", file=sys.stderr)except APIConnectionError as e:print(f"[第{attempt}次] 连接失败: {e}", file=sys.stderr)except APIStatusError as e:request_id = getattr(e, "request_id", None)print(f"[第{attempt}次] HTTP {e.status_code}, "f"message={e.message}, request_id={request_id}",file=sys.stderr,)# 400、401、403、404 重试没有意义,直接抛出if e.status_code in (400, 401, 403, 404):raiseelse:choice = resp.choices[0]content = (choice.message.content or "").strip()if content:return contentprint(f"[第{attempt}次] 返回内容为空, "f"finish_reason={choice.finish_reason}",file=sys.stderr,)time.sleep(2 ** attempt) # 指数退避raise RuntimeError("多次调用后仍未拿到有效内容")if __name__ == "__main__":try:print(ask("用一句话介绍你自己"))except Exception as e:print(f"调用失败: {e}", file=sys.stderr)sys.exit(1)
这段代码做了四件事:从环境变量读取密钥,设置超时,区分超时、连接失败和状态码错误,并在返回为空时打印 finish_reason 便于定位。日志中只打印状态码、错误信息和请求编号,不打印密钥。
下表列出免费额度中常见的限制项。具体数值、有效期和规则请以各平台文档和控制台为准,平台可能随时调整。
| 项目 | 常见情况 | 排查方式 |
|---|---|---|
| 有效期 | 到期后自动失效,提醒可能不及时 | 在控制台查看到期时间 |
| 绑定模型 | 资源包可能只能用于指定模型 | 对照代码中的 model 字段 |
| Token 扣减 | 输入和输出通常都计入,长上下文消耗快 | 查看每笔用量 |