免费API排查:报错、地址与空返回全解析

作者:宇宙中心我曹县2026.11.17 03:33浏览量:0

简介:调用免费大模型API失败,多数源于额度耗尽、base_url写错和返回内容为空。本文按报错特征、根因和排查步骤逐项说明,给出可直接运行的curl命令与容错调用代码,并整理免费额度的限制清单。读完后,你能快速判断问题出在账户、地址还是模型输出,少走弯路。

免费大模型能跑通原型验证,但开发者常卡在三个地方:额度悄悄用完,接口地址多写或少写一个路径,请求成功却拿不到内容。下面分五节说明每类问题的报错特征、根因和排查步骤,最后给出可直接运行的代码和免费额度的限制清单。

本文适合个人开发者和小团队,主要场景是原型验证和功能试跑。示例以兼容 OpenAI 接口格式的平台为准。具体地址、模型名和错误码请以各平台文档和控制台为准,不同平台可能不同。

一、额度问题:报错 1113

调用时返回的典型报错如下:

  1. {"error":{"code":"1113","message":"余额不足或无可用资源包,请充值。"}}

该报错码和文案来自某些平台,其他平台可能返回不同的错误码或 HTTP 状态码。

很多人看到这个报错,第一反应是”我明明有免费额度”,于是反复修改代码。这类问题属于账户侧,代码改得再多也无法解决。常见原因有四个:

  • 免费额度有有效期,到期后失效,平台不一定提前提醒。
  • 资源包可能绑定特定模型。调用其他模型时,平台会判定为”无可用资源包”。
  • 额度按 Token 扣减,一次上下文很长的请求就可能消耗大量额度。
  • 子用户或项目没有被授权,或者额度发放在另一个账号下。

排查顺序如下:

  1. 登录控制台,在用量明细中按时间和模型名称筛选,确认剩余额度和资源包有效期。
  2. 对照资源包绑定的模型名与代码中的 model 字段,检查是否完全一致,包括大小写和版本后缀。
  3. 确认调用所用的 API Key 属于拿到额度的那个账号或项目。
  4. 打印完整响应中的 code 和 message 字段,不要只打印异常字符串,否则容易丢掉关键信息。

二、地址问题:base_url 多写或少写

base_url 写错是高频问题,常见形态有两种:版本号重复,或者把接口路径也写进了 base_url。

  1. # 错误:版本号重复
  2. base_url = "https://api.example.com/v1/v1"
  3. # 错误:把接口路径写进了 base_url,SDK 会再拼一次路径
  4. base_url = "https://api.example.com/v1/chat/completions"
  5. # 正确:base_url 只写到版本号,路径交给 SDK
  6. base_url = "https://api.example.com/v1"

检查 base_url 时可以逐项核对四类问题:版本号重复、路径重复、末尾多出或缺少斜杠、从其他平台照抄的代理或网关地址。不同平台的版本前缀并不统一,有的使用 /v1,有的使用 /v2,照抄其他平台的教程很容易出错。

判断问题是否出在 SDK 封装上,可以用 curl 发一次最小请求,直接查看原始返回。密钥只放在环境变量中:

  1. export LLM_API_KEY="你的密钥" # 只在本地终端设置,不要写进代码或提交到仓库
  2. curl -sS "https://api.example.com/v1/chat/completions" \
  3. -H "Authorization: Bearer $LLM_API_KEY" \
  4. -H "Content-Type: application/json" \
  5. -w "\nHTTP %{http_code}\n" \
  6. -d '{
  7. "model": "your-model-name",
  8. "messages": [{"role": "user", "content": "你好,请只回复一个字:好"}],
  9. "max_tokens": 20
  10. }'

根据 HTTP 状态码决定下一步:

  • 404:检查 base_url 和路径是否重复或缺失。
  • 401:检查 Key 是否有效,是否多了空格或换行。
  • 403:检查模型权限、项目权限或访问地区限制。
  • 429:请求过于频繁或额度受限,降低并发并加入退避重试。
  • 400:检查 model 名称和 JSON 结构是否正确。
  • 5xx:服务端暂时异常,稍后重试。

三、返回内容为空怎么排查

HTTP 状态码是 200,但 content 为空字符串或 null,这类情况最容易被误判为”接口没问题”。常见根因如下:

  • finish_reason 为 length:max_tokens 设置过小。带推理过程的模型会先消耗 Token 做推理,正文可能还没输出就被截断。
  • finish_reason 为 content_filter:内容触发了平台的安全策略被拦截。
  • 内容出现在其他字段,例如 reasoning_content 或 tool_calls,代码却只读取了 content。
  • 流式输出时,只读取了某个分片,没有把所有 delta.content 拼接起来。
  • 超时或连接中断,返回的数据并不完整。

免费大模型API返回空内容,应该按什么顺序检查?

  1. 打印完整的 JSON 响应,确认 choices 是否为空数组。
  2. 查看 finish_reason,判断是长度截断、内容过滤还是正常结束。
  3. 查看 message 中是否还有其他字段,例如推理内容或工具调用结果。
  4. 把 max_tokens 调大后复测。
  5. 换一条简单的提示词测试,排除输入内容触发过滤的可能。
  6. 流式场景下,确认已经累计了全部分片,并处理最后一个结束分片。

四、可直接运行的容错调用代码

下面的代码使用 OpenAI 官方 Python SDK 的调用方式,适用于兼容该格式的平台。运行前先安装依赖,并设置环境变量:

  1. pip install openai
  2. export LLM_API_KEY="你的密钥"
  3. export LLM_BASE_URL="https://api.example.com/v1"
  4. export LLM_MODEL="your-model-name"

Windows PowerShell 中使用 $env:LLM_API_KEY="你的密钥" 设置。代码如下:

  1. import os
  2. import sys
  3. import time
  4. from openai import (
  5. OpenAI,
  6. APIConnectionError,
  7. APIStatusError,
  8. APITimeoutError,
  9. )
  10. API_KEY = os.environ.get("LLM_API_KEY")
  11. BASE_URL = os.environ.get("LLM_BASE_URL", "https://api.example.com/v1")
  12. MODEL = os.environ.get("LLM_MODEL", "your-model-name")
  13. if not API_KEY:
  14. sys.exit("缺少环境变量 LLM_API_KEY")
  15. client = OpenAI(
  16. api_key=API_KEY,
  17. base_url=BASE_URL,
  18. timeout=30.0,
  19. max_retries=0, # 重试次数由下面的循环控制
  20. )
  21. def ask(prompt: str, max_retries: int = 3) -> str:
  22. for attempt in range(1, max_retries + 1):
  23. try:
  24. resp = client.chat.completions.create(
  25. model=MODEL,
  26. messages=[{"role": "user", "content": prompt}],
  27. max_tokens=512,
  28. )
  29. except APITimeoutError:
  30. print(f"[第{attempt}次] 请求超时", file=sys.stderr)
  31. except APIConnectionError as e:
  32. print(f"[第{attempt}次] 连接失败: {e}", file=sys.stderr)
  33. except APIStatusError as e:
  34. request_id = getattr(e, "request_id", None)
  35. print(
  36. f"[第{attempt}次] HTTP {e.status_code}, "
  37. f"message={e.message}, request_id={request_id}",
  38. file=sys.stderr,
  39. )
  40. # 400、401、403、404 重试没有意义,直接抛出
  41. if e.status_code in (400, 401, 403, 404):
  42. raise
  43. else:
  44. choice = resp.choices[0]
  45. content = (choice.message.content or "").strip()
  46. if content:
  47. return content
  48. print(
  49. f"[第{attempt}次] 返回内容为空, "
  50. f"finish_reason={choice.finish_reason}",
  51. file=sys.stderr,
  52. )
  53. time.sleep(2 ** attempt) # 指数退避
  54. raise RuntimeError("多次调用后仍未拿到有效内容")
  55. if __name__ == "__main__":
  56. try:
  57. print(ask("用一句话介绍你自己"))
  58. except Exception as e:
  59. print(f"调用失败: {e}", file=sys.stderr)
  60. sys.exit(1)

这段代码做了四件事:从环境变量读取密钥,设置超时,区分超时、连接失败和状态码错误,并在返回为空时打印 finish_reason 便于定位。日志中只打印状态码、错误信息和请求编号,不打印密钥。

五、免费额度限制清单

下表列出免费额度中常见的限制项。具体数值、有效期和规则请以各平台文档和控制台为准,平台可能随时调整。

项目 常见情况 排查方式
有效期 到期后自动失效,提醒可能不及时 在控制台查看到期时间
绑定模型 资源包可能只能用于指定模型 对照代码中的 model 字段
Token 扣减 输入和输出通常都计入,长上下文消耗快 查看每笔用量