使用指南

通过 hiapi API 使用 z-image 生成电商产品图片

2026年11月3日

大多数图像模型都能画出产品。但能同时把产品画好并把价格拼写正确的模型要少得多。对于电商场景——价签、促销横幅、折扣卡、包装标签——图片上的文字才是关键，一个乱码字符就意味着素材被拒。

z-image 是 hiapi 上的一款 Turbo 级文生图模型，正是为这一细分场景而生：快速生成照片级写实图像，图片内文字（英文和中文）准确，价格为每张图 $0.008——不到大多数替代方案价格的三分之一。本指南中的每张图片都是用它旁边展示的完全相同提示词生成的，通过你将在下文复制的同一套 /v1/tasks 调用完成，每次渲染端到端大约耗时 30–60 秒。

为什么产品图选择 z-image

对电商流水线来说有三个重要属性，z-image 在三方面都表现优异：

文字渲染。 在遵循下文提示词规则后，促销卡、物流横幅和瓶子标签返回时每个单词都拼写正确。
速度。 这是一个 Turbo 调优模型；我们的测试渲染每次都在远少于一分钟内完成，这使得数百个 SKU 图片的批处理可以在喝杯咖啡的时间内搞定。
价格。 按 $0.008/图计算（已在定价页面核实），1,000 张图片的目录刷新成本为 $8。同样的任务用 gpt-image-2（$0.03/图）则需 $30。

如果你想了解该模型更全面的概览——密钥设置、通用示例、何时不该使用它——请参阅Z-Image API：定价、API 密钥、示例及适用场景。本指南聚焦于电商工作流。

已核实的 API 接口

z-image 运行在 hiapi 的异步任务端点上。你提交任务、轮询直到成功，然后下载输出。我们对照线上 API 确认了两项 schema 事实（二者均与平台上的某些其他模型不同）：

input 仅接受 prompt 和 aspect_ratio。 发送 resolution 字段会返回 HTTP 400（additional properties not allowed）——不同于 gpt-image-2，后者要求该字段。
aspect_ratio 必须是 1:1、4:3、3:4、16:9、9:16 之一。 其他任何值（我们试过 3:2）都会被 400 拒绝，并列出有效值。

输出分辨率按比例固定——我们的渲染结果返回为 PNG：1536×1536（1:1）、1344×768（16:9）、928×1232（3:4）和 1728×1296（4:3）。

提交任务

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "Studio e-commerce product photo: a matte black insulated steel water bottle on a seamless light-gray background...",
      "aspect_ratio": "1:1"
    }
  }'

响应会携带一个任务 id：

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG"}}

轮询并下载

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG \
  -H "Authorization: Bearer $HIAPI_API_KEY"

每隔几秒轮询一次，直到 data.status 为 success 且 data.output 存在；将 fail 视为终态。一个实用提示：生成后不久，任务可能会短暂报告一个中间状态（我们观察到过 archiving），然后 output 数组才出现，因此你的循环应以输出 URL 是否存在为条件，而不仅仅是状态字符串。

import os, time, requests

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

def generate(prompt: str, ratio: str = "1:1") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "z-image",
        "input": {"prompt": prompt, "aspect_ratio": ratio},
    }, timeout=60)
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        output = task.get("output") or []
        if output and output[0].get("url"):
            return requests.get(output[0]["url"], timeout=120).content
        if task.get("status") == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...your product prompt...", "1:1")
open("product.png", "wb").write(png)

立即下载。 output[0].url 是一个带有 expireAt 时间戳的临时链接——任务成功后立即将字节持久化到你自己的存储（S3/R2/CDN）。如果任务看起来卡住了，这里介绍如何诊断挂起或超时的 hiapi 任务。

五个电商配方，附真实输出

以下所有图片都是根据所示完全相同提示词生成的真实 z-image 渲染结果。未做任何修饰。

1. 带价签的主图

Studio e-commerce product photo: a matte black insulated steel water bottle centered
on a seamless light-gray background with soft shadow. A rectangular coral paper card
leans against the bottle. The card contains ONLY these two lines of bold clean
sans-serif text and no other words: "SUMMER SALE" on line one, "$19.99" on line two.
Text flat-on to camera, large, perfectly legible. Photorealistic.

注意措辞：展示文字放在引号内，提示词说卡片只包含这些词。我们第一次尝试时将文字内联描述（“...reads exactly: SUMMER SALE on the first line and $19.99 on the second line”），模型忠实地在两行之间排版了单词“ON”——指令词泄漏到了渲染结果中。请引用字面字符串；将指令放在引号外。

2. 宽幅促销横幅

Wide e-commerce promo banner, photorealistic flat-lay of white sneakers and a kraft
shipping box on a pastel blue background. On the right side, bold navy sans-serif
text with exactly these four words and amount, nothing else: "FREE SHIPPING OVER $50".
All four words must appear. Text large, straight, perfectly legible. Clean commercial
studio lighting.

16:9 会给你一张 1344×768 的横幅，可直接放入店铺首页主视觉位。

3. 社交媒体竖版折扣卡

Vertical social-media product card: a small brown glass cosmetic dropper bottle on a
warm beige podium, soft daylight. Above the bottle, bold black modern sans-serif
headline text reads exactly: 30% OFF TODAY ONLY. Text flat to camera, large and
perfectly legible. Minimalist premium e-commerce style, photorealistic.

3:4（928×1232）是最接近信息流帖子格式的比例；如果你的平台要求，可在下游裁剪为 4:5。

4. 可读的包装标签

Macro e-commerce product photo of a frosted glass skincare bottle with a clean white
label. The label text, printed in elegant dark sans-serif, reads exactly: GLOW SERUM
on the first line and VITAMIN C 10% on the second line. Straight-on angle, label
fully visible and sharp, soft studio lighting, photorealistic, white background.

这是本组中最难的测试——曲面玻璃上的小字——标签返回时很干净，包括“10%”。

5. 配色阵容（无文字）

E-commerce catalog photo: three identical ceramic coffee mugs lined up left to right
in sage green, terracotta orange, and navy blue, on a plain white studio background
with soft even shadows. No text anywhere in the image. Photorealistic, consistent
product geometry across all three mugs.

各变体之间一致的几何形状正是使其可用作目录条带的关键——z-image 在一次生成中保持了三个颜色马克杯形状完全相同。

让文字存活的提示词规则

从我们实际运行中有效（和失败）的经验浓缩而来：

将字面字符串放在引号中。 text reads exactly: "SUMMER SALE"——模型会将未加引号的周围词语视为候选文案。
加上“and no other words”（且无其他文字）。 否则模型可能会编造额外的徽章文案来填充空间。
保持文字正对镜头。 我们唯一一次乱码渲染是吊牌上呈角度悬挂的文字；同样文案放在平直卡片上则完美。透视变形是字形最先崩坏的地方。
每张图一到两个文本块。 每增加一个文本块都会使失败概率倍增；复杂布局请在下游合成。
发布前验证。 以这个价格，你可以负担得起重试循环：渲染、OCR 或目检文字、不匹配时重新生成。即使每张失败图片重试一次，成本也只是替代模型的一小部分。

批量成本

一个具体场景：200 个 SKU × 每个 3 个素材（商品列表图、促销横幅、社交卡片）= 600 张图片。

模型	价格/图	600 张图片	备注
z-image	$0.008	$4.80	Turbo 速度，图片内文字表现强
flux-schnell	$0.005	$3.00	最便宜，但不侧重文字渲染
qwen-image-2.0	$0.025	$15.00	通用质量强
gpt-image-2	$0.03	$18.00	需要 `resolution` 字段；电商指南见此