Imagen 4 API 怎么用？5 分钟跑通第一张图

TL;DR

• Imagen 4（Google-Imagen4）是文生图模型，一张 $0.06：写一句提示词、选好画幅就出图，适合人像摄影、自然特写和产品静物。打开模型页就能在线试，新用户注册送 200 积分。
• 同一个系列还有两档：imagen4-fast 一张 $0.03 用来大量试稿，imagen4-ultra 一张 $0.09 用来出成品细节。
• 调用走 HiAPI /v1/tasks 接口：提交任务拿 taskId，再查询结果，成功后从 output[0].url 下载图片。

它能做什么

• 文字直接出图：不接收参考图，画面全由提示词描述，aspect_ratio 必填（1:1、16:9、9:16、3:4、4:3、auto 六种）。
• 三种定位一个系列：Fast 试稿、标准档日常生产、Ultra 提升细节，三个模型 ID 在同一项目里分阶段用。
• 每次固定 1 张：没有张数、像素尺寸和输出格式参数，重跑就换 seed。

下面是标准档的真实成品：

Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography

（中文意思：阳光充足的北欧风客厅，亚麻沙发、橡木搁板和一株龟背竹；杂志感室内摄影。画幅选 16:9。）

Google-Imagen4，16:9，1280×720，$0.06。

用这个提示词生成 →

三个模型怎么选

预算参考：全用标准档、月产 1,000 张约 $60.00；试稿量挪到 Fast 越多，账单压得越低，定稿量留给 Ultra。

三个模型调用方式一样，只换 model 字段；参数结构一致，只有 seed 的类型有差异（见参数表）。Fast 和 Ultra 各有一篇英文版接入教程：Imagen 4 Fast API guide、Imagen 4 Ultra API guide。按场景挑提示词看提示词大全。

两条上手路线

浏览器 3 步：打开模型页 → 粘贴提示词、选画幅 → 点生成，标准档一张 $0.06。第一次建议先在浏览器跑一张，确认画面风格合预期，再动手写代码。

API 3 步：POST /v1/tasks 提交 → 拿 taskId → GET /v1/tasks/<taskId> 查到 success 后下载。

curl：第一张

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "Google-Imagen4",
  "input": {
    "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
    "aspect_ratio": "16:9"
  }
}'

换档只改 model：imagen4-fast 或 imagen4-ultra。返回里的 taskId 就是查询凭证。

Python：提交、轮询、下载

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "Google-Imagen4",
    "input": {
        "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
        "aspect_ratio": "16:9",
    },
}

# 提交：带 Idempotency-Key，网络重试不会重复建任务
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# 轮询：queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 临时地址，尽快下载保存
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # 扩展名按实际返回的格式命名
        f.write(img.content)
    print("saved")

参数表

三个模型共用同一张参数表。请求体里出现表外字段会直接 400。

你会遇到的报错

任务终态如果失败，错误码还有 CONTENT_POLICY_VIOLATION、TASK_FAILED、TASK_TIMEOUT 等；失败不扣费，预扣积分全额退还。

上线前注意

• 回调：请求体顶层传 "callback": {"url": "https://..."}，任务到终态会通知你的服务，省掉轮询。
• 及时转存：output[0].url 是临时地址，拿到就下载存进自己的存储。
• 显式写画幅：aspect_ratio 是必填项，别依赖默认值；竖版社媒内容选 9:16。
• seed 类型分模型：Fast 传整数，标准档和 Ultra 传字符串；跨档复用构图时注意先转换类型。

常见问题

• 是的，三个模型同一个调用方式，只改 model 字段，其他代码不用动。
• 不是，没有像素尺寸和格式参数，输出画幅由 aspect_ratio 决定，每次 1 张。
• 是的，失败不扣费，预扣的积分在失败终态后全额退还。
• 是的，画面里的文字要放大核对：海报类出图偶尔会多一个字母或少一撇，发布前把文字部分放大检查一遍。
• 是的，三个档的图可以混在一个项目里，提示词和画幅逻辑通用；跨档复用构图时，把 Fast 的整数 seed 转成字符串再传给标准档或 Ultra。

下一步：复制上面的客厅提示词去模型页试一张，然后按场景挑提示词大全里的模板批量出图。