HHAPI 模型不可用：错误模型 ID、模型下线与权限不足排查

模型 ID 拼写错误

原因说明

模型 ID 区分大小写，且必须与 HHAPI 支持的模型标识符完全一致。常见的拼写错误包括：多余的空格、连字符与下划线混淆、版本号格式不符等。

解决方法

通过 GET /v1/models 接口获取准确的模型 ID 列表，并与你代码中使用的模型 ID 逐字核对：

curl <API_BASE_URL>/v1/models \
  -H "Authorization: Bearer <YOUR_API_KEY>"

返回示例（实际可用模型以接口返回为准）：

{
  "object": "list",
  "data": [
    { "id": "<MODEL_ID>", "object": "model" }
  ]
}

将代码中的模型 ID 替换为返回列表中的准确值后重试。

模型已下线或暂时不可用

原因说明

随着上游模型提供商的更新，部分模型可能被下线或替换为新版本。此外，服务端维护期间特定模型也可能临时不可用。

解决方法

查看更新日志确认是否有模型下线通知
通过 GET /v1/models 确认该模型当前是否在可用列表中
若模型临时不可用，可切换到同系列的替代模型；若问题持续，请联系技术支持

账户无权限访问该模型

原因说明

部分模型可能仅对特定套餐或白名单账户开放（待确认）。即使模型 ID 正确，也可能因权限不足而返回错误。

解决方法

登录控制台（<CONSOLE_URL>）确认当前套餐所包含的模型权限范围
如需访问受限模型，请参阅套餐升级说明或联系技术支持申请开通权限（待确认）

如何获取当前可用模型列表

随时通过以下命令查询当前账户可用的完整模型列表：

curl <API_BASE_URL>/v1/models \
  -H "Authorization: Bearer <YOUR_API_KEY>"

你也可以在代码中动态调用该接口，在运行时获取最新的可用模型：

import os
import openai

client = openai.OpenAI(
    api_key=os.environ.get("HHAPI_API_KEY"),
    base_url="<API_BASE_URL>/v1"
)

# 动态获取可用模型列表
models = client.models.list()
available_model_ids = [model.id for model in models.data]
print("当前可用模型：", available_model_ids)

处理建议

不建议在代码中硬编码模型 ID（除非你已确认该模型长期稳定可用）。推荐将模型 ID 写入配置文件或环境变量，以便在模型发生变更时快速切换，而无需修改代码逻辑。

import os

# ✅ 推荐：从环境变量读取模型 ID，便于灵活切换
MODEL_ID = os.environ.get("HHAPI_MODEL", "<MODEL_ID>")

response = client.chat.completions.create(
    model=MODEL_ID,
    messages=[{"role": "user", "content": "你好"}]
)

相关资源

​原因说明

​解决方法

​原因说明

​解决方法

​原因说明

​解决方法

​如何获取当前可用模型列表

​处理建议

原因说明

解决方法

原因说明

解决方法

原因说明

解决方法

如何获取当前可用模型列表

处理建议