HiAPI 400 Bad Request：如何修复任务 API 的参数错误

统一异步任务接口返回 400 Bad Request，意味着你的请求已经到达 HiAPI，但在任何模型运行之前就被拒绝了——因为 JSON 本身或 input 对象不符合该模型的 schema。响应长这样：

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:4', '16:9', '9:16'"
}

最有用的字段是 message：它会指明具体是哪个参数、错在哪里。400 是请求本身的问题，不是鉴权或余额问题——而且因为根本没有创建任务，被拒的 400 不会计费。

哪些情况会触发 400（按命中概率从高到低）

下面每一种都会返回 HTTP 400。schema 问题的 error_code 是 INVALID_REQUEST，模型 id 不存在时是 MODEL_UNAVAILABLE。以下都是 HiAPI 真实返回的报错文案：

注意 schema 校验器到底在抓什么：枚举值（aspect_ratio、resolution 等取值超出该模型允许的集合）、类型（该传字符串的地方传了数字，或该传数组的地方传了裸字符串）、字段名（像 promptt 这样的拼写错误，或被改名、移除的字段——校验器会同时报出「缺失的必填字段」和「多出来的未知字段」），以及模型 id 本身（取值不是任务接口上的在线模型）。

怎么从响应体里诊断

1. 先看 HTTP 状态码。 400 = 你的请求有问题。如果看到的是 401、402、403、429 或 504，那是另一类问题——见文末「相关阅读」。状态码其实是 401 时，别去改参数当成 400 来修。
2. 再看 error_code。 INVALID_REQUEST 表示请求体 / input 没通过 schema 校验；MODEL_UNAVAILABLE 表示 model 的取值在 /v1/tasks 上解析不到。
3. 逐字读 message。 它是字段级的：invalid input: <字段>: <原因>。invalid input: 后面那个词就是要修的参数。如果写着 value must be one of ...，允许的取值就印在那里——原样照抄一个即可。
4. 遇到 additional properties '<x>' not allowed， 说明你传了该模型 schema 没定义的字段——通常是拼写错误，或从别的模型复制过来的参数。删掉它，或改成正确的字段名。

这种字段级的报错值得单独说一句：很多图像、视频 API 面对一个坏请求只会回一个光秃秃的 400 Bad Request，不给任何细节。HiAPI 会拿你的 input 对照每个模型各自的 schema 校验，并告诉你是哪个字段、期望什么——于是你能一次改对一个字段，而不是靠猜。

修复步骤（checklist）

1. 先修 JSON 格式。 如果 message 以 invalid json body 开头，说明 payload 本身就不是合法 JSON——检查有没有没闭合的大括号、方括号，多余的逗号，或没转义的引号。发送前先用 jq 或 python -m json.tool 校验一遍字符串。
2. 确认 model 是裸的在线 id。 用 z-image、gpt-image-2 这样的纯 id——不要自己发明路由后缀。对照模型列表或模型页核一下。id 不存在会返回 MODEL_UNAVAILABLE。
3. 对齐该模型的 schema。 每个模型都声明自己的 input 字段。把生成参数放进 input 里，而不是放在顶层。删掉 schema 没列出的字段（那正是 additional properties ... not allowed 的来源）。
4. 枚举值原样照抄。 当 message 打印 value must be one of ... 时，逐字符照抄其中一个值（例如 "aspect_ratio": "1:1"）。
5. 传对类型。 prompt 是字符串；参考图放进数组字段（例如 image_urls）；数字字段必须是数字，不能是加引号的字符串。不同模型字段名可能不同（如参考图用 input_urls / image_urls / image_input，宽高比用 aspect_ratio / ratio / size，时长可能是字符串也可能是整数），一律以该模型 schema 为准。
6. 重发再读。 如果还是 400，message 这次会指向下一个字段。一次修一个，直到调用返回带 taskId 的 200。

最小可用请求

这是最小的、格式正确的文生图调用。如果它返回带 data.taskId 的 200，说明你的 key、接入地址和请求结构都没问题——你之前遇到的 400 是参数问题，不是连接问题：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "a red ceramic mug on a wooden table, soft daylight",
      "aspect_ratio": "1:1"
    }
  }'

提交成功后，data 里会带一个 taskId。随后轮询 GET https://api.hiapi.ai/v1/tasks/<taskId>，直到 data.status 变成 success（或 fail），再从 data.output 读结果。调试期间请保持请求最小化：把可选字段一个一个加回去，这样新冒出来的 400 就能精确指向你刚加的那个字段。完整字段列表见模型页，任务生命周期见 API 文档。

相关阅读

• API Key 无效报错：成因、修复与接入 checklist —— 状态码是 401 而非 400 时看这篇。
• 修复 HiAPI 的「Model Not Found」 —— 针对 MODEL_UNAVAILABLE 和模型 id 问题。
• 如何修复 HiAPI 限流（429）报错 —— 针对节流，而非请求校验。
• HiAPI 失败请求会扣费吗？ —— 400 与「任务跑起来后才失败」在计费上的区别。
• 定价页与仪表盘：查积分、拿 key。

FAQ

error_code: INVALID_REQUEST 是什么意思？ 你的请求体或 input 对象没通过 schema 校验。message 字段会点名是哪个参数出错。它不是鉴权问题（那是 401），也不是余额问题（那是 402）。

为什么会出现 additional properties '<字段>' not allowed？ 你传了该模型 schema 没定义的字段——通常是拼写错误（把 prompt 写成 promptt）、属于别的模型的字段，或把参数放在了顶层而不是 input 里。删掉或改名即可。

400 Bad Request 会扣积分吗？ 不会。400 在校验阶段就被拒了，根本没有创建任务，也就无从计费。只有真正被接收并运行的任务才会扣费。

我确定 JSON 没错，但还是 400，怎么办？ 逐字读 message。它是字段级的，会告诉你确切的参数和期望的取值或类型。如果写着 value must be one of ...，说明你的取值不在允许的枚举里——原样照抄一个允许值。如果点的是类型（got number, want string），把类型改对。

模型 id 写错时是同一个报错吗？ 仍然是 HTTP 400，但 error_code 是 MODEL_UNAVAILABLE，文案为 model not available via /v1/tasks。用裸的、当前在线的模型 id，别加自造的路由后缀。

怎么查一个模型到底接受哪些字段？ 每个模型的页面都列了它的 input schema 和一个示例请求。从上面的最小可用请求起步，再按模型页文档把字段一个一个加上去。