imagen-4.0-fast API：一个可用的文生图请求

Imagen 4 Fast 是 Google Imagen 4 系列中的速度档，而在 hiapi 上，它通过与其他所有图像模型相同的统一异步任务 API 完成文生图。本指南给你一个真正能跑通的请求——一次真实的 curl 调用、一段 Python 轮询循环、精确的封闭式输入 schema，以及经过线上运行验证的错误情况。以下所有内容均在发布前针对生产端点执行过；示例中的 taskId 和输出 URL 就来自那次运行。

你将实现的内容

一次调用，把文本提示词变成一张完成的图像：向 POST /v1/tasks 提交任务，轮询直到完成，然后读取图像 URL。你需要一个 hiapi API key（在控制台创建一个，并让账户里保有一些按量付费额度——参见 定价）。无需 SDK；这里每个示例都是纯 HTTP。

最小可用请求（curl）

创建任务。模型 id 是 imagen-4.0-fast，并且在这一档上 aspect_ratio 是必填的（下面会详细说明）：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "input": {
      "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
      "aspect_ratio": "16:9"
    }
  }'

创建调用只返回一个任务句柄——不是图像：

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A" }, "message": "success" }

轮询结果（Python）

拿到 taskId 后，轮询 GET /v1/tasks/<id>，直到状态进入终态。这就是我实际运行过的循环：

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

# 1. create the task
created = requests.post(API, headers=HEADERS, json={
    "model": "imagen-4.0-fast",
    "input": {
        "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
        "aspect_ratio": "16:9",
    },
}).json()
task_id = created["data"]["taskId"]

# 2. poll until the task reaches a terminal state
while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
    status = data["status"]
    if status == "success":
        print(data["output"][0]["url"])   # the finished image
        break
    if status == "fail":
        raise RuntimeError(data)
    time.sleep(3)

在我那次运行中，状态在大约 12 秒内依次经过 handling → archiving → success，终态响应如下：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A",
    "model": "imagen-4.0-fast",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5D4ZD2X353AHHW3SW8X8N0A-0.webp",
        "expireAt": 1793121346
      }
    ]
  },
  "message": "success"
}

一个任务返回一张 WebP 图像。archiving 状态是正常的——它会短暂停留，然后翻转为 success。

输入 schema（服务器实际接受的内容）

input 对象是封闭式 schema。它只接受以下字段：

字段	类型	必填	说明
prompt	string	是	非空；空字符串会返回 minLength: got 0, want 1。
aspect_ratio	enum	是	1:1、16:9、9:16、3:4、4:3、auto 之一。无默认值。
seed	integer	否	用于可复现的运行。必须是 JSON 数字，不能是字符串。
negative_prompt	string	否	描述希望图像中避免出现的内容。

该模型没有 resolution 或 size 字段——输出尺寸跟随 aspect_ratio。此表之外的任何字段都会被拒绝。

已验证的错误情况（那些坑）

这些不是猜测——每一个都是针对线上端点捕获的真实 400 响应。

1. 缺少 aspect_ratio。 当你从基础 Imagen 4 或 Ultra 档复制代码片段时，这是第一大陷阱，因为那边 aspect_ratio 默认是 1:1。在 Fast 上没有默认值：

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: missing required field \"aspect_ratio\"; prompt: minLength: got 0, want 1" }

2. seed 以字符串形式发送。 请以数字形式传入：

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: seed: got string, want integer" }

3. 未知字段（这里是 resolution）——封闭式 schema 会拒绝任何多余内容：

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'resolution' not allowed" }

注意其形态：校验失败是 HTTP 400，带 error_code: "INVALID_REQUEST"，没有 taskId，并且 message 会把每个字段错误聚合成一个以 ; 分隔的字符串——所以要读完整段内容，而不只是第一句。

Fast 与 Imagen 4 系列其他档位的对比

hiapi 在完全相同的任务 API 上托管三个 Imagen 4 档位；只有 model id 不同，因此上面的请求体在所有档位之间通用：

• imagen-4.0-fast——速度档（模型页面），也是该系列中成本最低的选项。适合提示词迭代、概念探索和批量方向探索，即生成大量候选、保留少数几个。
• imagen-4.0——标准 Imagen 4 档。
• imagen-4.0-ultra——最高细节档，用于交付级成片。

一个实用的工作流：在 Fast 上做原型，然后把 model 字符串换成 imagen-4.0-ultra 做最终渲染，无需改动任何其他代码。在定价页面比较当前每张图像的价格。

生产环境注意事项

• 轮询 vs. webhook。 上面的循环是轮询。生产环境中，hiapi 的任务 API 也支持 webhook：添加一个顶层 callback 对象（与 model/input 同级），包含 url 和 when: "final"，hiapi 会在任务到达终态时 POST 任务详情。在依赖它之前，先阅读异步 API 文档了解投递与重试约定。
• 网络不稳定时不要重新提交。 每次创建任务都会返回新的 taskId——提示词没有去重。如果某次轮询请求短暂失败，请重新轮询你已经保存的 taskId；只有在你从未收到 taskId 时才需要重新 POST。
• 输出 URL 会过期。 output[].url 位于 temp.hiapi.ai，其 expireAt 大约在 7 天后（上面的示例于 2026-10-28 过期）。请立即把字节下载到你自己的存储；不要热链。

相关内容

• Imagen 4 Fast 模型页面
• Imagen 4 Ultra——最高细节档，请求结构相同
• Imagen 4（基础版）
• 统一异步任务 API 文档
• 定价

常见问题

Imagen 4 Fast 需要不同的端点或 SDK 吗？ 不需要。就是 POST /v1/tasks 加上 "model": "imagen-4.0-fast"——与 hiapi 所有图像和视频模型使用的同一个端点。通过更改模型 id 来切换档位。

为什么我的请求返回 400 并提示“missing required field aspect_ratio”？ Fast 没有默认宽高比（与基础版和 Ultra 档不同）。始终从枚举 1:1 | 16:9 | 9:16 | 3:4 | 4:3 | auto 中发送 aspect_ratio。

我可以设置分辨率或图像尺寸吗？ 不可以——该模型没有 resolution 或 size 字段；输出尺寸跟随 aspect_ratio。发送 resolution 会返回 additional properties 'resolution' not allowed。

seed 是字符串还是数字？ 数字。"seed": 7 可用；"seed": "7" 会返回 seed: got string, want integer。

输出 URL 的有效期是多久？ 大约 7 天（expireAt）。请立即下载并存储。