> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hhapi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 当 HHAPI 请求返回模型不可用错误时，了解如何通过 GET /v1/models 获取实时可用列表，区分模型 ID 错误、模型下线和权限不足等情况并逐步排查。

调用 HHAPI 时，若遇到模型相关的错误，通常有以下几种情况：模型 ID 拼写错误、所请求的模型已下线或暂时不可用、或当前账户无权限访问该模型。本文帮助你快速定位原因并切换到可用模型。

<Warning>
  每次调用 `GET /v1/models` 或 `POST /v1/chat/completions` 均会消耗账户额度（待确认模型列表接口是否计费）。排查过程中请避免在循环中频繁请求，以免意外耗尽配额。
</Warning>

<AccordionGroup>
  <Accordion title="模型 ID 拼写错误">
    ### 原因说明

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

    ### 解决方法

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

    ```bash theme={null}
    curl <API_BASE_URL>/v1/models \
      -H "Authorization: Bearer <YOUR_API_KEY>"
    ```

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

    ```json theme={null}
    {
      "object": "list",
      "data": [
        { "id": "<MODEL_ID>", "object": "model" }
      ]
    }
    ```

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

  <Accordion title="模型已下线或暂时不可用">
    ### 原因说明

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

    ### 解决方法

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

  <Accordion title="账户无权限访问该模型">
    ### 原因说明

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

    ### 解决方法

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

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

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

```bash theme={null}
curl <API_BASE_URL>/v1/models \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

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

```python theme={null}
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)
```

## 处理建议

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

```python theme={null}
import os

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

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

***

**相关资源**

* [模型列表](/models/list)
* [API 参考 — 模型接口](/api-reference/models)
* [获取技术支持](/support)