Imagen 4 Ultra API：参数、代码与生成案例

TL;DR

• Imagen 4 Ultra 已在 HiAPI 上线，API 调用名为 imagen-4.0-ultra。打开 Imagen 4 Ultra，输入文字即可生成图片。
• 每次输出 1 张，价格 $0.09/张（180 积分），失败退费。Imagen 4 价格说明。
• prompt 和 aspect_ratio 必填，seed 使用字符串，最长 500 字符。通过 HiAPI /v1/tasks 接口提交任务拿 taskId，再查询结果。

在线试用与 API 接入怎么选？

想先确认提示词和画幅，可以在模型页输入下方案例提示词，手动选择 aspect_ratio 后生成。需要接入自己的应用，则准备 API Key 和请求体，提交后保存 taskId，后续查询始终使用这个任务编号。

标准档接入指南介绍标准档；系列提示词案例提供三档案例。Fast 每张 $0.03、标准档 $0.06、Ultra $0.09。可以用同一条提示词分别生成候选，按最终用途检查画面；不同模型使用相同 seed 也不应当作像素级一致的保证。切换方法见另一档接入指南。

请求要填写哪些参数？

请求只传支持的参数；不要添加 num_images、width、height、output_format 或参考图字段。标准档和 Ultra 的 seed 是字符串，Fast 的 seed 是整数。更换 model 后，也要对应修改 seed 的类型。

提交任务并查询结果

cURL 和 Python 使用相同请求参数，每次请求价格 $0.09。请把示例密钥替换成自己的密钥。Python 中的 600 秒是本地等待上限，不是生成时长；到时仍未结束，应保留 taskId 继续查询，不要自动再创建同一任务。

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "imagen-4.0-ultra",
  "input": {
    "prompt": "Macro photograph of a dew-covered spider web at sunrise with intricate detail; cinematic lighting",
    "aspect_ratio": "16:9",
    "seed": "7"
  }
}'

import os
import time
import requests

base = "https://api.hiapi.ai/v1/tasks"
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
payload = {
    "model": "imagen-4.0-ultra",
    "input": {
        "prompt": "Macro photograph of a dew-covered spider web at sunrise with intricate detail; cinematic lighting",
        "aspect_ratio": "16:9",
        "seed": "7"
    }
}
response = requests.post(base, headers=headers, json=payload, timeout=30)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{base}/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    task = response.json()["data"]
    if task["status"] == "success":
        print(task["output"][0]["url"])
        break
    if task["status"] == "fail":
        raise RuntimeError(task)
    time.sleep(2)
else:
    raise TimeoutError(f"Local wait ended; keep taskId {task_id} for later queries")

返回数据中的 data.taskId 用于查询；当 data.status 为 success，从 data.output[0].url 获取图片。任务失败时检查返回的错误信息，修正输入后再决定是否重试。图片结果地址应及时下载并保存到自己的存储。

画幅与案例

图注尺寸是这些展示文件的尺寸，不是每次请求的固定输出承诺。预填链接只带入提示词，仍需在页面选择图注中的画幅。

Imagen 4 Ultra：露珠蛛网微距

Macro photograph of a dew-covered spider web at sunrise with intricate detail; cinematic lighting

用这个提示词生成 →

aspect_ratio: "16:9" · 1280 × 720 · $0.09/张。

Imagen 4 Ultra：丝绸礼服肖像

High-fashion portrait of a woman in an emerald silk gown; studio lighting; ultra detailed skin texture

用这个提示词生成 →

aspect_ratio: "3:4" · 864 × 1152 · $0.09/张。

Imagen 4 Ultra：机械腕表

Luxury mechanical watch on black velvet; macro product photography with reflections

用这个提示词生成 →

aspect_ratio: "1:1" · 1024 × 1024 · $0.09/张。

常见问题

Fast 和 Ultra 的 seed 能直接共用吗？

Fast 使用整数，例如 7；Ultra 和标准档使用字符串，例如 "7"。切换时应转换类型。

一次请求能返回多张吗？

每次固定输出一张。需要多张候选时分别提交请求，并记录每个 taskId。

可以上传参考图或蒙版吗？

这个接口只接收文字描述，不接受参考图或蒙版。需要编辑已有图片时，应选择支持图生图的模型。

失败和本地等待超时有什么区别？

终态 fail 会按失败处理并退费；本地计时结束不等于服务器任务失败。程序停止等待后，可用原 taskId 继续查询。

复制第一条案例提示词，打开 Imagen 4 Ultra，选择 16:9 开始。