hiapi“模型不可用”/“模型未找到”错误：原因与修复方法

如果 POST https://api.hiapi.ai/v1/tasks 因为模型不可用或请求无效而拒绝请求，则任务不会被创建。重试前，请对照当前的模型文档核对准确的模型名称和请求字段。

常见原因

1. 模型名称已过时或不完整。HiAPI 的模型名称并非全部采用相同的形式。有些是裸名称，另一些则包含模态路径。GPT Image 2 的文本生图请求使用 gpt-image-2/text-to-image。
2. 拼写错误、大小写差异或隐藏空白改变了名称。请从当前文档复制模型名称，不要凭记忆输入，并去除从环境变量加载的值的空白。
3. 模型或路由已被停用或重命名。来自旧文章或已保存片段的名称可能已不可用。请以当前的模型页面和变更日志为准。
4. 请求混用了路由格式。当模型提供多条路由时，请使用文档中说明的顶层 route 字段或受支持的 @route 形式，但不要发送相互冲突的值。
5. 在路由之前认证失败。401 表示 API 密钥缺失或无效。403 表示密钥没有权限。请将这些情况与模型字段分开处理。

修复步骤

1. 打开当前的 GPT Image 2 文档或相关模型页面，复制准确的模型名称。
2. 保留作为文档名称一部分的模态后缀。对于 GPT Image 2 的文本生图，请使用 gpt-image-2/text-to-image。
3. 将 input 中的每个字段与该模型的参数表进行比较。即使模型名称有效，当输入字段不受支持时，仍可能返回 400 INVALID_REQUEST。
4. 在调用处去除空白。在 Python 中，使用 model = os.environ["MODEL"].strip()；在 Node.js 中，使用 model.trim()。
5. 如果模型有多条路由，请传入文档中说明的顶层 route 值，并使用该路由对应的参数结构。
6. 记录完整的 HTTP 状态码和响应体。不要从模型校验错误推断出密钥问题，也不要从 401/403 推断出模型问题。

用最小请求进行验证

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {
      "prompt": "a small ceramic mug on a wooden table, soft window light",
      "aspect_ratio": "1:1",
      "resolution": "1K"
    }
  }'

返回 HTTP 200 且包含 data.taskId，表示任务已被接受。轮询 GET /v1/tasks/:id，直到 data.status 为 success 或 fail，或者为生产环境配置回调。如果返回 400，请阅读校验消息并重新检查模型页面。如果返回 401 或 403，请修复密钥或其权限。

相关内容

• GPT Image 2 模型文档
• 创建任务 API 参考
• 认证指南
• HiAPI 模型概览

常见问题

我应该从每个模型名称中去掉 /text-to-image 吗？ 不。模型命名因系列而异。请从当前的模型文档中复制固定值。对于 GPT Image 2 的文本生图，/text-to-image 是模型名称的一部分。

模型错误是否意味着我的密钥有误？ 不一定。请求校验和认证是分开的。401 表示密钥缺失或无效；403 表示密钥缺少权限。400 指向请求结构、模型名称、路由或输入字段。

我可以在客户端中规范化所有模型名称吗？ 请避免自行制定规范化规则。请存储并发送当前模型文档中公布的准确名称。