教程

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

2026年11月3日

HiAPI 为你提供的 imagen-4.0 能力

imagen-4.0 是一个文本生成图像模型：你发送一段自然语言提示词，它返回一张生成的图像。作为集成开发者，真正重要的不是模型的架构，而是围绕它的接口约定。通过 HiAPI，该约定就是一个 HTTP 端点——它接受 JSON，并用法 bearer 密钥进行认证——这与你从 chat completion 和 embedding 调用中已经熟悉的模式完全一致。

使用 HiAPI 而不是直接接入模型的实际好处：

统一的认证方案。 同一个 API 密钥适用于平台上的所有模型，因此你无需在多个提供商的凭证之间来回切换。
统一的请求格式。 一个包含模型标识和提示词的 JSON 请求体。无需学习特定 SDK 的请求结构。
同步返回。 imagen-4.0 在同一个 HTTP 响应中返回结果，因此在基础场景下无需构建轮询循环或 webhook。

本指南将带你从零开始，用 curl 和 Python 各构建一个可用请求，然后讲解如何读取响应，以及在上线生产环境之前需要做哪些准备。

获取 API 密钥并设置认证

HiAPI 上每一次 imagen-4.0 调用都使用 bearer token 进行认证。你在 HiAPI 账户中创建一个 API 密钥，此后该密钥就是请求所需的唯一凭证——无需单独的项目 ID，也无需签名请求头。

能避免大多数事故的原则：密钥应放在环境变量中，绝不能提交到源代码里。 粘贴到脚本中并推送到代码仓库的密钥，就是你不得不轮换的密钥。

本地设置

在 shell 会话中导出密钥：

export HIAPI_API_KEY="your-key-here"

如果你希望该变量持久生效，可将这一行添加到 shell 配置文件中；或者使用 .env 文件，将其列入 .gitignore，并在应用启动时加载。

已部署环境

在 CI 和生产环境中，通过平台的密钥管理器设置 HIAPI_API_KEY——在运行时注入环境变量，而不是将文件烘焙到镜像中。这样应用代码在本地和已部署环境中完全一致，只有变量的来源不同。

请求头

每个请求都携带：

Authorization: Bearer $HIAPI_API_KEY

如果你看到 401，首先要检查的是请求头是否真的被发送，以及变量是否解析为非空值。一个从未导出该变量的 shell 会照常发送 Bearer ，后面什么都没有。

发送之前先理解请求结构

imagen-4.0 请求体小到可以记在脑子里，这正是关键——一旦你理解了其结构，就可以用任何语言构造请求，而不必翻译一段复制粘贴的代码片段。

至少需要发送：

{
  "model": "imagen-4.0",
  "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
}

两个字段承担了主要工作：

model 标识由哪个模型处理请求。它是一个字符串，也是平台在所有列出 imagen-4.0 的地方使用的同一标识符。写错了会得到错误响应，而不是静默回退。
prompt 是你想要的图像的描述。像向人描述画面那样写：主体、场景、风格、光线。具体的提示词比单个词的提示词产生更可预测的结果。

请求以 POST 方式发送，Content-Type: application/json，指向平台的图像生成端点。该模型可能还有额外的可选参数，但上面的两字段请求体是一个完整、有效的请求——从这里开始，只在需要时才添加选项。

由于请求体是纯 JSON，curl、Python、Node 以及任何具备 HTTP 客户端的工具都是一等公民。接下来两节将展示同一个请求的两种写法。

可用的 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",
    "prompt": "A weathered lighthouse on a cliff at dusk, long exposure, muted colors"
  }'

逐行解释：

-sS 静默进度条但仍显示错误，这样输出可读又不隐藏失败。
-X POST 设置请求方法。图像生成会创建内容，所以是 POST。
URL 是平台上的图像生成端点，由你的基础 URL 加上路径构成。将基础 URL 保存在变量中，这样同一命令可在不同环境中使用。
第一个请求头携带你的 bearer key，从之前导出的环境变量中读取。
Content-Type: application/json 告诉服务器如何解析请求体。
-d 提供 JSON 请求体。单引号防止 shell 解释大括号和引号；其中的 JSON 是字面量。

如果想检查输出，可通过 JSON 格式化工具处理：

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","prompt":"A weathered lighthouse on a cliff at dusk"}' \
  | python -m json.tool

如果响应中包含图像引用，说明请求成功了。下一节将把它转为应用代码。

用 Python 写同样的请求

curl 调用可以直接转换。唯一真正的选择是 HTTP 客户端；标准库的 urllib 到处都能用，但 requests 代码更短，也是大多数代码库已经依赖的库。

可复用的辅助函数

import os
import requests

HIAPI_BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")


def generate_image(prompt: str, model: str = "imagen-4.0") -> dict:
    api_key = os.environ["HIAPI_API_KEY"]
    response = requests.post(
        f"{HIAPI_BASE_URL}/images/generations",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json={"model": model, "prompt": prompt},
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


result = generate_image("A weathered lighthouse on a cliff at dusk")
print(result)

三点值得注意：

os.environ["HIAPI_API_KEY"] 在变量缺失时立即抛出 KeyError，从而快速且响亮地失败，而不是发送空 token。
json= 自动序列化字典并设置内容类型，因此请求行为与 curl 版本完全一致。
timeout=120 限制调用时长。图像生成比文本补全耗时更长，因此使用宽松的超时而非默认的无超时。

该函数接受提示词作为参数并返回解析后的 JSON，这意味着你代码的其余部分无需接触 HTTP 细节。在将其接入任何东西之前，先在 REPL 中测试。

读取同步响应并处理错误

imagen-4.0 同步响应：生成的图像在同一个 HTTP 响应的正文中返回。基础场景下没有作业 ID 需要轮询，也没有轮询循环需要编写——像对待任何其他请求-响应交互一样对待这次调用。

返回内容

成功响应是一个 JSON 对象。在 Python 中用 response.json() 解析，或将 curl 输出通过 JSON 格式化工具处理，然后在返回结构中定位图像数据——通常是 URL 或编码的图像负载，以及关于生成的元数据。从真实响应中读取确切的字段名一次，然后据此编写代码。

需要防范的问题

包装调用并在解析前检查状态：

try:
    result = generate_image("A weathered lighthouse on a cliff at dusk")
except requests.HTTPError as e:
    print("HTTP error:", e.response.status_code, e.response.text)
except requests.Timeout:
    print("Request timed out")

值得显式处理的失败模式：

401 — 密钥缺失或无效。修复环境变量，而不是代码。
一般的 4xx — 请求体格式错误、模型标识错误或提示词被拒绝。响应体通常会说明是哪一种。记录日志。
5xx — 服务器端故障。这些是值得通过退避重试的。
超时 — 视为结果未知而非成功；不要假设图像已生成。

失败时始终记录状态码和截断后的响应体。没有这些信息进行调试就是猜测。

从第一个请求走向生产环境

请求已经能用了。在扩大规模之前，请逐项检查：

配置。 基础 URL 和 API 密钥都来自环境。源代码中没有字面量，镜像中没有密钥。
超时。 每次图像调用都有超时。没有超时，一个停滞的请求可能无限期占用一个工作进程。
重试。 仅对 5xx 和超时进行重试，使用指数退避并设上限。绝不要重试 401 或请求体格式错误的 4xx——它们会以完全相同的方式失败。
日志记录。 记录每次调用的模型、提示词长度、状态码和延迟。不要记录密钥，如果提示词可能包含用户数据，也不要记录完整提示词。
成本意识。 图像生成按产生的输出计费，因此追踪每个用户或每个作业请求了多少张图像，并在应用层设置上限。当前费率参见平台的定价面板，而非本指南。
并发。 图像调用比文本调用慢。以此为依据设定工作进程池大小，而不是假设 chat-completion 的延迟。

这些就绪后，同一个 generate_image 辅助函数无需修改即可用于批处理作业、面向用户的功能和内部工具。更多集成细节，请参阅平台文档。

查看全部文章 →