如何通过 HiAPI API 使用 imagen-4.0-ultra：curl、Python 与可运行的请求示例

imagen-4.0-ultra 是什么，以及何时选择它

imagen-4.0-ultra 是 imagen-4.0 系列中保真度最高的层级，HiAPI 将它作为图像生成模型暴露在与聊天及其他模型系列相同的 OpenAI 兼容端点上。心智模型很简单：你发送一个描述图像的结构化 JSON 请求体，拿回的是图像数据——而不是聊天补全结果。

在各层级之间做选择，主要取决于任务，而不是排名：

• 草稿与迭代。 如果你在探索提示词、测试构图，或生成缩略图以确定方向，更轻量的图像模型返回更快、每次生成成本更低。把 ultra 留到真正重要的那一轮。
• 最终素材。 主视觉图、营销视觉，以及任何人类会以原始尺寸查看的内容，都能从 ultra 层级的细节、提示词遵循度，以及处理包含多个主体或类文字元素的复杂场景的能力中受益。
• 带质量门槛的批量流水线。 一种常见模式是先用轻量模型广泛出草稿，然后只对选中的提示词在 imagen-4.0-ultra 上重新运行。由于 HiAPI 将模型 ID 放在请求体中，切换层级只需改一个字符串，而不是做一次新的集成。

有几点预期需要提前设定。图像生成不是瞬时的；单次 ultra 请求的耗时可能明显长于文本补全，因此设计客户端时要设置宽裕的超时，不要假设亚秒级延迟。而且由于响应携带的是二进制图像数据而不是 choices 数组，任何为聊天模型编写的解析代码都无法沿用——请尽早为此做好规划。

如果你不确定是否需要 ultra，先对它发一个最小请求，按你实际计划交付的分辨率检查输出，然后再与更轻量的层级对比。通过缩小后的预览图判断图像质量会产生误导。

前置条件与鉴权设置

在发出第一个请求之前，确认三件事：你有 HiAPI API 密钥，你知道 OpenAI 兼容 API 端点的基础 URL，并且你的工具能发起 HTTPS 请求（curl，或带 requests 的 Python，甚至 httpx）。

让密钥远离你的代码

把密钥存放在环境变量中，而不是粘贴到脚本里：

export HIAPI_API_KEY="your_api_key_here"

在生产环境中，使用平台的密钥管理器并在运行时注入该值。把密钥提交到代码仓库是凭证泄漏最常见的方式，而轮换密钥远比从环境变量读取要痛苦得多。

鉴权请求头

每个请求都携带标准的 Bearer 令牌头：

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

两个请求头都很重要。缺少 Content-Type 可能导致服务器拒绝或错误解析请求体，有时会表现为令人困惑的通用错误，而不是清晰的校验信息。

同一个密钥和同样的请求头模式在 HiAPI 上的各个模型系列中都适用，这正是统一端点的实际收益：一份凭证、一个客户端、多个模型。

快速健全性检查

如果你手边有一个支持聊天的模型 ID，先发送一个简单的文本请求，是在调试图像请求体之前低成本确认密钥和请求头正确的方式。把鉴权问题与请求体问题区分开能真正节省时间。如果文本请求成功而图像请求失败，你就知道问题出在图像请求体上。

构建请求体

从能生成图像的最小请求体开始：模型 ID 加一个提示词。其余一切都是可选的优化。

{
  "model": "imagen-4.0-ultra",
  "prompt": "A sunlit reading room with tall windows, a wooden desk, and shelves of worn books, soft dust motes in the light"
}

两条原则能让它保持可维护。第一，模型 ID 必须与 HiAPI 为此模型记录的完全一致——没有空格，没有你自创的版本后缀。第二，提示词是纯自然语言；像向摄影师描述图像那样来写，倾向于使用具体的名词以及光线或构图线索，而不是抽象形容词。

通常有效的提示词形态

• 先主体，再场景，再风格。 "A fox in a snowy birch forest, morning light, shallow depth of field" 比一堆风格关键词更可靠。
• 对构图要具体。 当相机角度、取景或布局对你的用例重要时，要提及。
• 避免矛盾。 在同一句话里要求"极简"和"繁复的装饰细节"，往往会产出你不想要的妥协结果。

尺寸与宽高比

图像模型通常接受宽度/高度或宽高比选项，但确切的参数名和支持的值因模型而异。不要猜，查阅 HiAPI 上该模型的参数文档，只使用其中列出的值。如果你传入模型不支持的尺寸或比例，预期会得到校验错误——而不是静默回退。

安全的工作流是：先用默认值开始，确认一次成功响应，然后一次添加一个尺寸参数并检查输出。如果添加参数后请求开始失败，你就把原因定位到了最后一次改动。

在第一个请求中完全不要加入可选参数。一个只有两个字段且能工作的请求体，比一个有十个字段却失败的请求体是更好的基础。

一个可运行的 curl 请求

导出密钥后，这是可以复制并改编的请求形态：

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-ultra",
    "prompt": "A sunlit reading room with tall windows, a wooden desk, and shelves of worn books, soft dust motes in the light"
  }'

各部分的作用：

• -X POST —— 图像生成是创建操作，不是读取操作。
• URL —— HiAPI OpenAI 兼容端点上的图像生成路由。将 HIAPI_BASE_URL 设置为 HiAPI 文档中显示的基础 URL，这样即使主机变化，路径也能保持正确。
• 两个请求头 —— 如上所述的 Bearer 鉴权和 JSON 内容类型。
• -d 请求体 —— 与你在 Python 中将要复用的同一 JSON。引号很重要：用单引号包裹负载，防止 shell 展开其中的任何内容。

调试技巧

加上 -i 以包含响应头，这样即使请求体很大，你也能看到 HTTP 状态。如果你想确认实际发送了什么，加上 -v 并阅读发出的请求行——它能快速暴露格式错误的 URL 或缺失的请求头。

如果终端里的输出是一大片 base64 或二进制噪声，这说明请求成功了。不要把它管道到日志中；请参阅响应处理部分以获得更干净的做法。将原始响应重定向到文件（> out.json）对于一次性检查是可以的。

一旦 curl 返回成功状态和可解析的请求体，你就有了一个经过验证的契约。Python 步骤应该逐字节（结构上）复现这个确切的 JSON，这样以后任何失败都可归因于代码，而不是不同的请求。

Python 中的同一请求

使用 requests，等价的调用与 curl 版本保持接近，这让交叉检查变得轻而易举：

import os
import requests

base_url = os.environ["HIAPI_BASE_URL"]
api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "imagen-4.0-ultra",
    "prompt": (
        "A sunlit reading room with tall windows, a wooden desk, "
        "and shelves of worn books, soft dust motes in the light"
    ),
}

response = requests.post(
    f"{base_url}/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
result = response.json()

实践中重要的几点说明：

• json=payload 会序列化字典并为你设置内容类型。为了清晰或与 curl 保持一致，你仍然可以显式传入请求头。
• timeout=120 不是装饰。图像生成可能很慢；没有显式超时，你会继承库的默认值，它可能比你预期的更短，而客户端中止看起来像服务器故障。
• raise_for_status() 会把 4xx 和 5xx 响应变成异常，而不是让格式错误的错误响应体流入你的解析代码。

封装以便复用

把调用放进一个小函数，接受提示词和可选参数，返回解析后的结果，并且只记录模型 ID、提示词长度、状态码和耗时。这一行日志足以调试大多数问题，而不必在日志聚合器中存储数兆字节的图像数据。

由于请求体是纯 JSON，同一个函数可用于 HiAPI 上的其他图像模型——替换模型 ID，如有需要再替换支持的尺寸参数。在测试脚本中保留几个示例提示词，这样在任何客户端升级后你都能重新运行一个已知可用的请求并快速获得信号。

处理图像响应

响应是图像负载，不是聊天补全。不要去找 choices[0].message.content——编写与图像路由实际返回内容相匹配的解析代码，如 HiAPI 文档所述。

防御性解析

响应通常以 base64 字符串形式携带图像数据，有时还附带元数据。只在确认字段存在后才解码：

import base64

item = result["data"][0]
image_b64 = item.get("b64_json")
if image_b64 is None:
    # 某些响应可能携带 URL 或其他格式；请查阅文档
    raise ValueError(f"Unexpected image payload keys: {list(item)}")

image_bytes = base64.b64decode(image_b64)
with open("output.png", "wb") as f:
    f.write(image_bytes)

错误消息中的 list(item) 是有用的部分：当负载发生变化时，它会告诉你实际的键，而不是让你去猜。

记录日志而不倾倒二进制

绝不要记录图像请求的原始响应体——它很大且大多不可读。记录状态码、内容长度、模型 ID，以及解码后图像的哈希或字节数。这足以验证每个提示词得到了不同的图像，而不会让存储膨胀。

运维习惯

• 存储前先校验。 确认解码后的字节以可识别的图像签名开头，并在写文件的地方捕获解码错误。
• 原子写入。 保存到临时路径并在成功后重命名，这样写入中途崩溃不会留下看似有效的截断文件。
• 将提示词与输出一起保存。 在每张图像旁保存提示词、模型 ID 和任何尺寸参数。当事后利益相关者要求变体时，你需要原始请求。
• 设置保留规则。 生成的图像会不断累积；尽早决定它们存放在哪里以及保留多久。

排查失败的请求

大多数首次请求失败可归入三类。在改动提示词之前，按此顺序检查它们。

鉴权失败

401 或 403 几乎总是意味着请求头有误。验证方案恰好是 Bearer，后跟一个空格和密钥，没有尾随空白或多余引号。确认环境变量确实在你运行请求的 shell 或进程中已设置——在一个终端中导出的密钥在另一个终端中并不存在。如果你最近轮换了密钥，确保旧值没有仍然缓存在配置文件或部署密钥中。

模型 ID 错误

模型未找到的响应意味着 model 字段与 HiAPI 注册的 ID 不匹配。从 HiAPI 模型文档中复制标识符，而不是重新输入；一个错误的字符或自创的版本后缀就足以导致失败。如果你切换模型 ID 以比较层级，检查替换是否落在了请求体中，而不只是落在注释里。

参数被拒绝

指明某个字段的校验错误通常意味着不支持的尺寸、宽高比，或模型不接受的可选参数。移除所有可选字段，确认最小两字段请求成功，然后一次一个地加回参数。这能立即隔离问题所在。

其他症状

• 200 但请求体为空或无法解析 —— 你可能读错了字段。在索引到负载内部之前先检查顶层键。
• 客户端超时但服务器端已计费 —— 你的超时可能太短；提高它并用相同提示词重试一次，再认定失败。
• curl 和 Python 中的 JSON 不同 —— 在 Python 中打印序列化后的负载，并与 curl 的 -d 字符串比较。这里的差异解释了大多数"在 curl 中能工作"的报告。

按顺序逐项排查，你就能在不改动提示词一个字的情况下解决绝大多数首次集成问题。之后，在每次客户端或 SDK 升级后，用一个小测试脚本运行一个已知可用的提示词，以便及早发现回归。