免费大模型 API 调用实战：额度、限流与空返回排查

在个人项目或中小型应用中，把免费大模型 API 作为兜底能力是一种常见做法：主链路使用付费或自建模型，异常时降级到免费模型保证可用性。然而免费额度往往伴随着一系列隐性约束，官方文档与公开资料之间的信息差也不小。本文基于一次完整的实测过程，记录免费模型调用的真实表现、典型坑位与排查方法，所有结论均可通过文末脚本复现。

需要先明确范围：本文的实测数据来自单一云厂商的可用密钥，其余厂商仅记录状态，不做横向评测。文中涉及的模型 ID、耗时、报错信息均为特定时间点的实测结果，读者应以自己环境的复测为准。

一、免费模型清单：接口查不到，只能翻文档

第一个坑出现在模型发现环节。多数厂商的模型列表接口只返回当前主推的付费模型，免费模型 ID 并不在列表中。也就是说，如果按照“先调列表接口、再筛选免费项”的思路找模型，结果会一无所获。

# 典型模型列表请求（示意）
curl https://{api-host}/v4/models \
  -H "Authorization: Bearer $KEY"

返回结果通常是一串付费主力模型，名称中不含任何免费标识。免费模型的 ID 只能从文档页面逐个翻找，或者从社区汇总文章中收集——而后者恰恰是错误信息的高发区。

对公开资料中提到的免费模型 ID 逐一实测后，结果可以归纳为几类：

模型 ID 特征	可调用性	典型耗时	说明
基础 flash 版	可用	0.7–1.7s	最稳定，适合日常主力
带日期后缀的 flash 版	可用	约 0.7s	与基础版行为一致
flashx 变体	不可用	—	返回余额不足，实际为付费模型
旧版本 flash	可用	18–42s	延迟显著偏高
新版 flash	受限	7–10s	可用但限流频繁
推理型 flash	可用	5.5–6s	适合需要推理链的场景
视觉理解 flash	可用	约 1.1s	图像理解任务
视觉推理 flash	可用	约 1.9s	图像推理任务

这里最值得警惕的是 flashx 变体。它的命名与免费 flash 极为相似，许多汇总文章将其误列入免费清单，但实际调用返回的是明确的计费错误：

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

多一个字母，性质就从免费变成了付费。这类“命名近似但计费不同”的模型是免费清单中最容易踩的坑，建议在接入前对每个候选 ID 做一次最小化调用验证，而不是信任任何第三方清单。

二、最隐蔽的坑：HTTP 200 但内容为空

比报错更危险的是“不报错但没结果”。在实际项目中曾遇到这样的现象：调用某 flash 模型，HTTP 状态码 200，响应结构完整，但 choices[0].message.content 是空字符串。当时的结论是“该模型有问题，换基础 flash”，并把这个结论沿用了很久。

后续逐项复测发现，模型本身没有问题，问题出在调用参数上。关键在于 max_tokens 的取值：部分模型在生成回答前会先输出一段内部推理内容，如果 max_tokens 设置过小，预算会被推理部分消耗殆尽，最终返回的正式回答就是空字符串。

对照实验可以清晰说明这一点：同一模型、同一问题，仅调整 max_tokens：

# 参数对照（示意）
payload_small = {
    "model": "glm-4.5-flash",
    "messages": [{"role": "user", "content": "用一句话解释什么是幂等性"}],
    "max_tokens": 32          # 预算过小，推理内容耗尽预算
}
payload_large = {
    "model": "glm-4.5-flash",
    "messages": [{"role": "user", "content": "用一句话解释什么是幂等性"}],
    "max_tokens": 512         # 预留足够预算，正常返回
}

小预算请求返回空内容，大预算请求正常返回。这说明空返回不是模型故障，而是预算分配问题。排查此类问题的正确顺序应该是：

1. 先确认 HTTP 状态码与响应结构是否正常；
2. 检查 finish_reason 字段，若为 length 则基本可判定为预算不足；
3. 检查是否存在推理内容字段（如 reasoning_content）占用预算；
4. 逐步放大 max_tokens 复测，观察返回内容是否恢复；
5. 最后才怀疑模型本身。

这个坑的危险性在于它会误导架构决策：把“参数配置问题”误判为“模型能力问题”，进而错误地排除掉一个本可用的免费模型。

三、限流与超时：免费额度的真实成本

免费模型的“免费”体现在计费上，但成本会转移到稳定性上。实测中，新版 flash 模型在连续调用时约有六成请求被限流，表现为返回限流错误码或长时间排队；旧版本 flash 虽然可用，但耗时达到 18–42 秒，远超交互式场景的可接受范围。

应对策略可以分三层：

第一层，请求侧控制。 对免费模型设置独立的并发上限，避免与主链路共享连接池；为单次请求设置合理超时（建议不低于 60 秒，覆盖长尾延迟），并对限流错误实现指数退避重试。

import time, random
def call_with_retry(fn, max_retries=3, base_delay=1.0):
    for i in range(max_retries):
        try:
            return fn()
        except RateLimitError:
            delay = base_delay * (2 ** i) + random.uniform(0, 0.5)
            time.sleep(delay)
    raise RuntimeError("重试耗尽")

第二层，模型侧分级。 把免费模型按实测稳定性排序，优先使用基础 flash 与带日期后缀的版本作为兜底；限流频繁的模型仅作为最后备选；推理型与视觉型模型按任务类型单独路由，不与通用文本请求混用。

第三层，架构侧隔离。 免费模型调用应放在独立线程池或独立队列中，失败时不阻塞主链路；对返回空内容的情况设置显式检查，触发降级而非直接透传空结果给上层。

四、可复现的验证脚本

为避免结论依赖单一时间点，建议自建一个最小验证脚本，覆盖三类检查：模型可调用性、空返回检测、限流统计。

import json, time, statistics
def probe(client, model_id, prompt="用一句话说明什么是缓存穿透", max_tokens=512):
    start = time.time()
    try:
        resp = client.chat(model=model_id, prompt=prompt, max_tokens=max_tokens)
        elapsed = time.time() - start
        content = resp["choices"][0]["message"].get("content", "")
        finish = resp["choices"][0].get("finish_reason")
        return {
            "model": model_id,
            "ok": bool(content.strip()),
            "elapsed": round(elapsed, 2),
            "finish_reason": finish,
            "empty": not content.strip()
        }
    except Exception as e:
        return {"model": model_id, "ok": False, "error": str(e)}
def batch_probe(client, model_ids, rounds=10):
    stats = {}
    for mid in model_ids:
        results = [probe(client, mid) for _ in range(rounds)]
        ok = sum(1 for r in results if r.get("ok"))
        empty = sum(1 for r in results if r.get("empty"))
        errors = [r["error"] for r in results if "error" in r]
        stats[mid] = {
            "success_rate": f"{ok}/{rounds}",
            "empty_count": empty,
            "error_samples": list(set(errors))[:3],
            "avg_elapsed": round(statistics.mean(
                [r["elapsed"] for r in results if "elapsed" in r] or [0]), 2)
        }
    return stats

脚本的关键设计点在于：每轮都记录 finish_reason 与内容是否为空，而不是只看是否抛异常；错误信息去重后保留样本，便于区分“余额不足”与“限流”两类问题；耗时取均值而非单次值，避免长尾延迟误导判断。

五、接入免费 API 的检查清单

结合上述实测，接入免费大模型 API 前建议逐项确认：

1. 模型 ID 从文档获取，不从列表接口推断，并对每个 ID 做一次最小化调用验证；
2. 警惕命名近似的变体，凡是名字多一个字母或后缀的，先确认计费属性；
3. 空返回优先查参数，检查 max_tokens 与 finish_reason，再判断模型是否可用；
4. 为免费链路设置独立并发与超时，实现退避重试，避免拖垮主链路；
5. 对空内容做显式校验，触发降级而不是透传；
6. 定期复测，免费模型的可用性与限流策略会随平台调整而变化，历史结论需要定期刷新。

免费模型的价值在于降低兜底成本，但它的隐性成本在于排查与运维。把上述检查固化为接入流程的一部分，才能让“免费”真正可用，而不是在故障时才发现问题所在。