使用指南

通过 hiapi API 使用 grok-imagine/text-to-image 生成电商产品图

2026年11月3日

大多数产品图流水线一旦遇到以下需求就会崩溃：需要把同一张照片生成三种不同形状——用于目录网格的方形图、用于移动端商品详情页（PDP）的竖版裁剪图，以及用于首页主视觉横幅的宽幅图。将一张主视觉图重新裁剪后，很少能在所有比例下都看起来合适——要么产品被裁掉，要么出现尴尬的空白区域。grok-imagine/text-to-image 规避了这个问题：它可以直接按你需要的比例原生生成，包括两种专为此类横幅工作打造的宽幅格式（2:1 和 20:9），在 hiapi API 上统一按每张图 $0.03 计价，不随分辨率变化。

本指南将介绍实际的请求结构、我们在测试中遇到的模式陷阱、一个针对单个产品简报运行完整镜头列表的批量生成脚本，以及面向目录级规模的诚实的成本核算。

价格定位

根据撰写本文时 hiapi 的定价页面核实：

模型	每张图价格	分辨率	宽高比控制
grok-imagine/text-to-image	统一 $0.03	1K 或 2K，同价	13 种比例，包括 `2:1`、`20:9`
grok-imagine-quality/text-to-image	$0.07 (1K) / $0.10 (2K)	按分辨率分级定价	相同比例集

质量档在精细细节上确实有显著提升——反光、织物纹理、小号文字——对于少量真正的核心主视觉图，值得支付额外费用。对于目录中的大部分图像（网格缩略图、生活场景变体、其他角度），基础模型已经足够接近，2-3 倍的价格差在批量场景下不值得支付。

实际可用的请求

本页所有图片都来自同一个端点：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/text-to-image",
    "input": {
      "prompt": "matte ceramic pour-over coffee dripper on a pale oak table, soft morning window light from the left, small negative space top-right, no text, no logo, product photography",
      "aspect_ratio": "1:1",
      "resolution": "2k"
    }
  }'

这会返回一个 taskId；轮询 GET /v1/tasks/{taskId} 直到 status 为 success，然后获取 output[0].url 并下载——该 URL 是带签名的且会过期，因此应立即保存字节内容，而不是直接链接到它。

测试期间有三个模式细节曾让我们踩坑，在你自行构建之前值得了解：

aspect_ratio 是严格的 13 值枚举，不是自由格式。发送其他任何值都会返回 400 并附上完整列表：2:1、20:9、19.5:9、16:9、4:3、3:2、1:1、2:3、3:4、9:16、9:19.5、9:20、1:2。横幅需要的两个比例是 2:1 和 20:9——hiapi 上的大多数图像模型最高只到 21:9，或者根本不提供超宽选项。
resolution 仅限小写——应使用 "2k"，而不是 "2K"。发送大写形式会被直接拒绝，而不是静默转换。
输入模式是严格的。多余或拼写错误的字段（残留的 negative_prompt、从其他模型示例复制来的 style 键）会导致整个请求失败，而不是被忽略。

为目录级干净图片编写提示词

获得一致目录输出的最大杠杆是明确说明你不想要什么。对于上面的白底主视觉图，有效的提示词是：

"哑光陶瓷手冲咖啡滤杯置于纯白无缝背景上，影棚柔光箱照明，居中，除柔和接触阴影外无阴影渐变，无文字，无水印，无道具，电商产品摄影，清晰对焦"

对于用于 PDP 次级图片或电子邮件横幅的生活场景变体，替换背景和光照线索，但保持同样的「无文字 / 无水印 / 除指定道具外无其他道具」纪律——正是这一点防止 grok-imagine 在产品本身上添加杂乱物体或难以辨认的标签文字：

"同一陶瓷手冲滤杯放在木质厨房台面上，旁边是一只冒热气的马克杯，温暖的晨光，浅景深，舒适的生活化厨房背景柔和虚化，无文字，无标志"

超宽横幅工作流

当需求是首页或品类横幅而非目录缩略图时，2:1 和 20:9 正是让 grok-imagine 特别值得采用的两个比例。技巧是直接提示负空间，而不是指望裁剪结果恰好合适——描述产品在画面中何处，以及哪些区域应为空白：

"哑光陶瓷手冲咖啡滤杯置于画面右侧三分之一处，黄金时刻户外光线，图像左侧三分之二区域留出充裕的空白负空间用于叠加标题文字，电影感宽幅构图，无文字，无标志"

{
  "model": "grok-imagine/text-to-image",
  "input": {
    "prompt": "matte ceramic pour-over coffee dripper positioned in the right third of frame, golden-hour outdoor light, generous empty negative space across the left two-thirds of the image for headline text overlay, cinematic wide composition, no text, no logo",
    "aspect_ratio": "20:9",
    "resolution": "2k"
  }
}

如果你的 CMS 需要精确像素尺寸而不是比例，请按最接近的受支持比例生成，然后从该图无损裁剪——具体填充计算请参阅我们的通过 API 实现精确尺寸的笔记。

批量生成完整镜头列表

单个产品简报通常需要不止一张图。以下脚本复现了用于生成本页四张图片的实际脚本——每张图提交一个任务，轮询至完成，然后保存到磁盘：

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

SHOTS = [
    {
        "name": "hero",
        "prompt": "matte ceramic pour-over coffee dripper on a pure white seamless "
                  "background, studio softbox lighting, centered, e-commerce product "
                  "photography, no text, no watermark",
        "aspect_ratio": "1:1",
    },
    {
        "name": "lifestyle",
        "prompt": "same ceramic pour-over dripper on a wooden kitchen counter next to "
                  "a steaming mug, warm morning light, shallow depth of field, no text",
        "aspect_ratio": "4:3",
    },
    {
        "name": "banner",
        "prompt": "ceramic pour-over dripper in the right third of frame, soft studio "
                  "light, empty negative space across the left two-thirds for headline "
                  "text, no text, no logo",
        "aspect_ratio": "2:1",
    },
]


def create_task(shot):
    payload = {
        "model": "grok-imagine/text-to-image",
        "input": {"prompt": shot["prompt"], "aspect_ratio": shot["aspect_ratio"], "resolution": "2k"},
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_result(task_id, poll_interval=5, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


for shot in SHOTS:
    task_id = create_task(shot)
    url = wait_for_result(task_id)
    image_bytes = requests.get(url, timeout=120).content
    with open(f"{shot['name']}.jpg", "wb") as f:
        f.write(image_bytes)
    print(f"{shot['name']}: saved {len(image_bytes)} bytes")

如果你要运行完整的多 SKU 批次，请先提交所有三个任务，然后并发轮询它们（一个小型 asyncio 或线程池即可）——每个任务通常在一分钟内完成，串行运行只会无故增加空闲等待时间。

真实目录运行的成本

按每张图统一 $0.03 计算，上面的三图组合（主视觉 + 生活场景 + 横幅）成本为每个 SKU $0.09。放大规模后：

50 个 SKU × 3 张图 = 150 张图 → $4.50
500 个 SKU × 3 张图 = 1,500 张图 → $45
仅为 2K 主视觉图添加 grok-imagine-quality 升级（$0.10 而非 $0.03），500 个 SKU 总计变为 $80——与单次传统产品拍摄相比仍只是零头。

grok-imagine 与其余产品线的对比

如果一张图需要动起来——比如用于社交广告的 6 秒产品动态短片而非静态横幅——同一系列可通过 grok-imagine-image-to-video 覆盖，它以这些静态图之一作为起始帧；我们在短视频指南中单独介绍了该工作流。对于与基于 Nano-Banana 的目录流水线进行对比的团队，我们的 Nano-Banana 电商指南是最接近的并排参考——相同的任务 API 结构，不同的模型优势。