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

# 为什么模型不可用？

> 模型返回不可用或不存在错误时的常见原因和转刀替代模型的建议。

调用接口时如果收到模型不可用或模型不存在的错误，不要慌张。以下是导致该问题的最常见原因，以及对应的排查和替代方案。

## 常见原因

### 1. 模型名称拼写错误

这是最容易出现的问题。Sub2API 对模型名称是大小写敏感的，任何拼写差异都会导致请求失败。

<Info>
  例如 `gpt-4o` 是正确的，但 `GPT-4O`、`gpt4o` 或 `gpt-4-o` 都会被认为是无效模型。
</Info>

建议在发送请求前，先对照控制台或文档中的模型列表核对名称。

### 2. 当前账户未开通该模型

部分模型可能需要单独开通权限。如果你的账户所在层级不包含某个模型，调用时会返回不可用错误。

> TODO：请在后台确认实际配置后填写。

### 3. 上游模型已下线或临时不可用

Sub2API 对接了多个上游服务商（OpenAI、Anthropic、Google、xAI 等）。当某一家临时维护或模型下架时，即使你的请求格式完全正确，也可能收到不可用响应。

<Note>
  Sub2API 与 OpenAI、Anthropic、Google、xAI 均无关联。模型可用性取决于这些上游服务商的状态。
</Note>

## 替代方案：切换相似模型

当目标模型不可用时，你可以尝试使用功能相近的替代模型：

<CardGroup cols={2}>
  <Card title="Claude 系列替代" icon="arrows-rotate">
    如果 `claude-opus` 不可用，可尝试 `claude-sonnet` 或 `claude-haiku`
  </Card>

  <Card title="GPT 系列替代" icon="arrows-rotate">
    如果 `gpt-4o` 不可用，可尝试 `gpt-4o-mini` 或 `gpt-4-turbo`
  </Card>

  <Card title="Gemini 系列替代" icon="arrows-rotate">
    如果 `gemini-pro` 不可用，可尝试 `gemini-flash`
  </Card>

  <Card title="图片生成替代" icon="arrows-rotate">
    如果 DALL-E 3 不可用，可尝试其他支持的图像生成模型
  </Card>
</CardGroup>

## 进一步排查

* 查看 [如何选择模型](/models/how-to-choose) 了解各模型的详细能力和适用场景
* 查看 [模型不可用排错指南](/troubleshooting/model-unavailable) 获取完整诊断流程

<Tip>
  在正式项目中，建议实现模型降级逻辑：优先调用首选模型，失败时自动回退到备选模型。
</Tip>

调用接口时如果收到模型不可用或模型不存在的错误，不要慌张。以下是导致该问题的最常见原因，以及对应的排查和替代方案。

## 常见原因

### 1. 模型名称拼写错误

这是最容易出现的问题。Sub2API 对模型名称是大小写敏感的，任何拼写差异都会导致请求失败。

<Info>
  例如 `gpt-4o` 是正确的，但 `GPT-4O`、`gpt4o` 或 `gpt-4-o` 都会被认为是无效模型。
</Info>

建议在发送请求前，先对照控制台或文档中的模型列表核对名称。

### 2. 当前账户未开通该模型

部分模型可能需要单独开通权限。如果你的账户所在层级不包含某个模型，调用时会返回不可用错误。

> TODO：请在后台确认实际配置后填写。

### 3. 上游模型已下线或临时不可用

Sub2API 对接了多个上游服务商（OpenAI、Anthropic、Google、xAI 等）。当某一家临时维护或模型下架时，即使你的请求格式完全正确，也可能收到不可用响应。

<Note>
  Sub2API 与 OpenAI、Anthropic、Google、xAI 均无关联。模型可用性取决于这些上游服务商的状态。
</Note>

## 替代方案：切换相似模型

当目标模型不可用时，你可以尝试使用功能相近的替代模型：

<CardGroup cols={2}>
  <Card title="Claude 系列替代" icon="arrows-rotate">
    如果 `claude-opus` 不可用，可尝试 `claude-sonnet` 或 `claude-haiku`
  </Card>

  <Card title="GPT 系列替代" icon="arrows-rotate">
    如果 `gpt-4o` 不可用，可尝试 `gpt-4o-mini` 或 `gpt-4-turbo`
  </Card>

  <Card title="Gemini 系列替代" icon="arrows-rotate">
    如果 `gemini-pro` 不可用，可尝试 `gemini-flash`
  </Card>

  <Card title="图片生成替代" icon="arrows-rotate">
    如果 DALL-E 3 不可用，可尝试其他支持的图像生成模型
  </Card>
</CardGroup>

## 进一步排查

* 查看 [如何选择模型](/models/how-to-choose) 了解各模型的详细能力和适用场景
* 查看 [模型不可用排错指南](/troubleshooting/model-unavailable) 获取完整诊断流程

<Tip>
  在正式项目中，建议实现模型降级逻辑：优先调用首选模型，失败时自动回退到备选模型。
</Tip>