想把 Hy Image3.5 preview 从网页端搬到接口批量出图，卡住的地方通常不在模型，而在两处：请求里到底放哪些字段、返回里到底取哪个值。可控的做法是先只发一条最小请求，把鉴权方式、必填字段和图片在返回体里的位置逐个对上，再谈批量。

先用一条最小请求换回一份完整响应，是比较省事的排错路径：请求体只留必填项，响应原样打印，确认图片是链接、内联数据还是任务标识，再决定要不要轮询。地址、鉴权头、字段名一律以接口文档为准，本文只给占位骨架；同步还是异步、能不能轮询，需要结合文档和当前环境确认，不要凭记忆拼参数。

在接口文档里抄下四类信息

动手之前先把文档里的硬信息抄到一处，最好是一个照着就能填的表格，避免一边写请求一边回忆。建议按下面四项记录，每项都注明出处位置，后续改参数时方便回溯。

• 请求地址：完整 URL、请求方法、是否需要版本号或路径参数。
• 鉴权方式与请求头字段：是 Bearer、自定义头还是查询参数携带密钥；请求头字段名的大小写、是否有额外必填头。
• 必填参数：字段名、类型、取值范围，以及哪些参数有默认值可以省略。出图场景通常包括模型标识、提示词、画幅或尺寸。
• 返回结构说明：响应是同步一次返回，还是先返回任务标识；图片以链接、内联数据还是任务结果的形式给出。

这四项里，本文不提供也不猜测具体接口路径和参数名，你从文档里抄到什么就用什么，下面的示例全部写成占位符。

写一个只出单张图的最小请求

字段越少，报错时越容易定位。先只保留模型标识、一句提示词和画幅这三类必填项，其余可选参数一律不加，用一条 curl 先发出去。

curl -i -X {{METHOD}} "{{BASE_URL}}{{IMAGE_PATH}}" \
  -H "{{AUTH_HEADER}}: {{AUTH_VALUE}}" \
  -H "Content-Type: application/json" \
  -d '{
    "{{FIELD_MODEL}}": "{{MODEL_NAME}}",
    "{{FIELD_PROMPT}}": "一只白猫坐在窗台上",
    "{{FIELD_SIZE}}": "{{SIZE_VALUE}}"
  }'

占位符的替换来源：{{METHOD}} 与 {{BASE_URL}}{{IMAGE_PATH}} 换成文档给出的请求方法和地址；{{AUTH_HEADER}}、{{AUTH_VALUE}} 换成文档要求的鉴权头字段名与密钥；三个 {{FIELD_*}} 换成文档中对应的字段名，{{MODEL_NAME}}、{{SIZE_VALUE}} 换成文档列出的合法取值。如果文档注明还有必填参数而这里没写，先补齐，再看报错是否消失。

密钥不要硬编码进脚本后直接提交到仓库，可以先放进环境变量，用 "$AUTH_ENV" 这类形式引用。

打印完整返回体确认图片位置

只看状态码不够，图片藏在哪一层，往往决定后面怎么写保存逻辑。用 curl -i 可以一次把状态行、响应头和响应体都打出来；响应体很长时，改成先落盘再查看。

curl -s -o body.json -w "status=%{http_code}\n" \
  -X {{METHOD}} "{{BASE_URL}}{{IMAGE_PATH}}" \
  -H "{{AUTH_HEADER}}: {{AUTH_VALUE}}" \
  -H "Content-Type: application/json" \
  -d @request.json

head -c 500 body.json

拿到响应后按三种形态判断：

如果状态码是 4xx，先对照前面抄下的必填参数与请求头字段逐项核对；5xx 则多半与参数无关，把完整响应体和请求 ID 记下来再排查。

区分同步返回和异步任务再决定是否轮询

判断依据就是上一步的响应体：里面出现任务标识和状态字段，说明这是一次异步提交，图片还没生成；响应里直接带图片链接或内联数据，就是同步返回，再轮询只是白跑请求。

即使是异步，也要先确认文档是否提供查询接口或轮询支持：文档里有查询任务状态的接口、有建议的查询间隔，才按它的说明去查；文档没写，就不要自己猜一个地址去轮询。查询时同样先打印状态码和任务状态字段，确认状态从处理中变为完成或失败，再决定下一步。

把跑通的一次请求固化成可复用骨架

这条请求跑通之后，把它另存成脚本，后续批量只改参数、不动结构。做法是把提示词、画幅、保存路径三样外置成参数或配置文件，请求体的键名和层级保持不变。

PROMPT="${1:-一只白猫坐在窗台上}"
SIZE="${2:-{{SIZE_VALUE}}}"
OUT_DIR="${3:-./out}"

# 请求结构不动，只替换上面三个变量
# ... 与最小请求相同的 curl 调用 ...

echo "status=$STATUS request_id=$REQUEST_ID file=$OUT_FILE" >> run.log

日志里至少要留三项：HTTP 状态码、响应中的请求标识或任务标识字段、本次生成文件的实际保存路径。任务标识是后续对账和排查异常响应的关键，少了它，批量出图出错时很难把某张图对应回哪一次请求。鉴权头不要写进日志。

扩量时建议一次只改一个变量，比如先把提示词换成列表，跑通后再换画幅，这样出错时能立刻判断是新参数的问题，还是请求结构被改坏了。