为什么模型不可用？

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

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

常见原因

1. 模型名称拼写错误

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

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

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

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

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

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

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

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

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

替代方案：切换相似模型

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

Claude 系列替代

如果 claude-opus 不可用，可尝试 claude-sonnet 或 claude-haiku

GPT 系列替代

如果 gpt-4o 不可用，可尝试 gpt-4o-mini 或 gpt-4-turbo

Gemini 系列替代

如果 gemini-pro 不可用，可尝试 gemini-flash

图片生成替代

如果 DALL-E 3 不可用，可尝试其他支持的图像生成模型

进一步排查

• 查看 如何选择模型 了解各模型的详细能力和适用场景
• 查看 模型不可用排错指南 获取完整诊断流程

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

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

常见原因

1. 模型名称拼写错误

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

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

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

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

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

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

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

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

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

替代方案：切换相似模型

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

Claude 系列替代

如果 claude-opus 不可用，可尝试 claude-sonnet 或 claude-haiku

GPT 系列替代

如果 gpt-4o 不可用，可尝试 gpt-4o-mini 或 gpt-4-turbo

Gemini 系列替代

如果 gemini-pro 不可用，可尝试 gemini-flash

图片生成替代

如果 DALL-E 3 不可用，可尝试其他支持的图像生成模型

进一步排查

• 查看 如何选择模型 了解各模型的详细能力和适用场景
• 查看 模型不可用排错指南 获取完整诊断流程

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