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

TL;DR

• Imagen 4（imagen-4.0）是文生图模型，一张 $0.06：写一句提示词、选好画幅就出图，适合人像摄影、自然特写和产品静物。打开模型页就能在线试，新用户注册送 200 积分。
• 同一个系列还有两档：imagen-4.0-fast 一张 $0.03 用来大量试稿，imagen-4.0-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。）

imagen-4.0，16:9，1280×720，$0.06。

用这个提示词生成 →

三个模型怎么选

	imagen-4.0-fast	imagen-4.0（标准）	imagen-4.0-ultra
每张	$0.03	$0.06	$0.09
定位	大量试稿、挑方向	日常生产	成品细节、材质和文字排版
$10 约出	333 张	166 张	111 张
适合	选题会、草图轮	常规出图交付	定稿、对细节敏感的画面

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

三个模型调用方式一样，只换 model 字段；参数结构一致，只有 seed 的类型有差异（见参数表）。Fast 和 Ultra 各有一篇英文版接入教程：Imagen 4 Fast API guide、Imagen 4 Ultra API guide。按场景挑提示词看提示词大全；三档的完整价格表和月预算见价格页，与 Nano Banana 2.1 的两组同提示词对比见对比页。

两条上手路线

浏览器 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": "imagen-4.0",
  "input": {
    "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
    "aspect_ratio": "16:9"
  }
}'

换档只改 model：imagen-4.0-fast 或 imagen-4.0-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": "imagen-4.0",
    "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")

参数表

字段	必填	取值	说明
prompt	是	1–5000 字符	画面内容描述
aspect_ratio	是	1:1 / 16:9 / 9:16 / 3:4 / 4:3 / auto	输出画幅，必填
negative_prompt	否	≤5000 字符	不希望出现的内容
seed	否	标准档和 Ultra：字符串（≤500 字符）；Fast：整数	同参数同 seed 复现画面

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

你会遇到的报错

状态码	含义	怎么处理
400 INVALID_REQUEST	请求体不合法（缺 prompt 或 aspect_ratio、枚举值传错、传了表外字段）	对照参数表改请求体
402 INSUFFICIENT_QUOTA	余额不足（不扣费）	充值后重试
429 RATE_LIMITED	触发限流	降低提交频率
409 / 422 IDEMPOTENCY_KEY_*	同一个幂等键重复提交（处理中 / 参数不一致）	换新的 Idempotency-Key
415 UNSUPPORTED_MEDIA_TYPE	请求格式不对	检查 Content-Type: application/json

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

上线前注意

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

常见问题

三个模型的调用方式一样吗？

一样，只改 model 字段，其他代码不用动。

能指定像素尺寸或输出格式吗？

不能。没有像素尺寸和格式参数，输出画幅由 aspect_ratio 决定，每次 1 张。

失败会扣费吗？

不会。预扣的积分在失败终态后全额退还。

画面里的文字可靠吗？

要放大核对。海报类出图偶尔会多一个字母或少一撇，发布前把文字部分放大检查一遍。

三个档的图能混在一个项目里吗？

能。提示词和画幅逻辑通用。

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