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

电商商品目录的成败全在于一致性。一个有 40 个 SKU 的卖家不需要 40 次不同的拍摄——他们需要一个好看的背景，以及一种能快速把每件商品放进去的方法。这正是参考图驱动图像编辑的真实用例，也正是 hiapi API 上的 grok-imagine/image-to-image 所擅长的：给它一个场景和一张产品图，它会把两者合成为一张干净、符合品牌调性的图像——无需手动蒙版，也无需单独的抠图步骤。

本指南涵盖该模型真实且经过测试的请求 schema（不是营销文案）、你实际会被计费的定价、一个用于将整个商品目录套用同一背景的批处理脚本，以及一个实用技巧：在所有都要求不同裁剪比例的各家电商平台之间控制输出宽高比。

该模型实际做什么

grok-imagine/image-to-image 接收一段文本提示词和少量参考图，把它们融合成一张新的图像。对于产品摄影而言，这意味着：

• 背景统一 —— 把每张 SKU 照片都放到同一个风格化场景前（一张桌子、一个货架、一块影棚背景布），无需重新拍摄任何东西。
• 场景合成 —— 将产品抠图与环境参考图结合，使光线和构图相匹配。
• 参考图之间的风格迁移 —— 把一张图的调色或道具带入另一张图，同时保持产品本身不被编辑。

所有这些都在一次任务调用中完成，按每张输出图像计费，外加你每发送一张参考图的小额费用。

真实的 schema（对照线上 API 验证，而非定价页面）

我们直接用 grok-imagine/image-to-image 探测了 POST /v1/tasks，该模型的输入 schema 恰好接受两个字段：

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "string, required",
    "image_urls": ["array of public image URLs, required, max 3"]
  }
}

仅此而已——没有 resolution，没有 aspect_ratio，也没有 strength 参数。payload 中的其他任何内容都会被严格的 schema 拒绝。

有一处需要更正的错误值得指出：hiapi 定价页面目前声称该模型支持“最多 6 张”参考图。我们在同一请求中分别发送 6 个和 7 个图像 URL 进行了直接测试，两者都被拒绝：

{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 6, want 3"}
{"error_code":"INVALID_REQUEST","message":"invalid input: image_urls: maxItems: got 7, want 3"}

截至本文撰写时，实际执行的限制是每次调用 3 张图像，而不是 6 张。如果你要围绕该模型构建流水线，请按 3 张来规划，并把任何与此不符的营销文案视为过时内容——在发布依赖该限制的自动化之前，务必先通过一次实时的 POST /v1/tasks 调用进行确认，因为这些限制会随着平台演进而变化。

自动宽高比：输出比例跟随你的第一张参考图

该模型没有 aspect_ratio 输入字段，那么输出的形状从何而来？我们做了一次受控测试来找出答案：相同的提示词、相同的两张参考图，只交换 image_urls 的顺序。

在这次渲染中，产品照片（背包）被列在 image_urls 的第一位，后面跟着背景场景。输出返回为 1248×832——一个与产品照片自身比例相符的 3:2 横向图像。

相同的提示词、相同的两张图像——但这次背景场景被列在第一位。输出返回为 1024×1024，一个与场景参考图自身宽高比相符、而非与产品相符的方形裁剪。

规则是：grok-imagine/image-to-image 的输出宽高比继承自 image_urls 中排在最前面的那个 URL。它并不会从你的提示词中读取构图提示（“产品照”还是“宽场景”）——它纯粹是位置性的。一旦你知道这一点，它就是一个真正有用的杠杆：要针对某个特定电商平台偏好的裁剪，只需重新排列参考图数组。对 Instagram 风格的方形商品列表，把方形参考图放在最前面；对宽横幅位，把横向参考图放在最前面。

定价（对照线上价目表核对）

模型	调用类型	价格
grok-imagine/text-to-image	文本 → 图像	$0.03 / 图像
grok-imagine/image-to-image	参考图驱动编辑（本指南）	$0.03 / 图像 + 每张参考图 $0.003
grok-imagine-quality/text-to-image	文本 → 图像，高级档	$0.07 / 图像（1K）
grok-imagine-quality/image-to-image	参考图驱动编辑，高级档	$0.08 / 图像（1K），$0.10 / 图像（2K），+ 每张参考图 $0.015

本指南中使用的 grok-imagine/image-to-image 基础档不随分辨率变化，为统一费率——你不会像在 -quality 档那样支付 2K/4K 附加费。对于将数十个 SKU 合成到同一场景上的商品目录更新，每张图像 $0.036（一张产品照片加一张场景参考图）就是你应据以做预算的数字。在大批量运行前务必重新查看 /en/pricing，因为费率可能会变化。

如果你需要每张图更锐利的细节，并能接受约 3 倍的价格上涨，grok-imagine-quality 档是相同工作流程的更高保真版本。对于完全没有参考照片的纯文本到图像产品效果图，请参阅基础档文本到图像演练。

批处理脚本：一个场景，一整套目录

下面是一个极简的 Python 循环，它接收一张可复用的背景场景，将其与文件夹中的每张产品照片合成，把每张作为独立任务提交，并轮询直到完成。它使用上文确认的 schema，并把产品图放在第一位，这样每个输出都会继承产品照片自身的宽高比——如果你想要场景的比例，就交换顺序。

import os
import time
import requests

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

SCENE_URL = "https://static.hiapi.ai/blog/grok-imagine-image-to-image-ecommerce/scene-base.jpg"
PROMPT = (
    "Composite the product from the first reference photo naturally into the "
    "second reference's studio scene, matching its lighting and shadow direction. "
    "Keep the product's shape, color, and texture unchanged."
)


def submit(product_url: str) -> str:
    payload = {
        "model": "grok-imagine/image-to-image",
        "input": {
            "prompt": PROMPT,
            "image_urls": [product_url, SCENE_URL],  # product first -> output follows its ratio
        },
    }
    resp = requests.post(f"{API_BASE}/tasks", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


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


if __name__ == "__main__":
    product_urls = [
        "https://your-storage.example.com/catalog/dripper-raw.jpg",
        "https://your-storage.example.com/catalog/sneaker-raw.jpg",
        "https://your-storage.example.com/catalog/backpack-raw.jpg",
    ]
    for url in product_urls:
        task_id = submit(url)
        output_url = wait_for_result(task_id)
        print(f"{url} -> {output_url}")

对于生产流水线，在任务上注册一个 callback.url，而不是在循环中轮询——完整的回调 payload 结构请参见 hiapi 模型目录。将 taskId 与你的产品 SKU 一起存储，以便失败的任务可以重试，而无需重新提交整个批次。

真实产品照片示例

这两张都使用同一张背景场景参考图生成，仅在调用之间更换了产品照片——光线、桌面和背景植物在整个“目录”中保持一致，这正是可复用场景工作流程的全部意义所在。

常见问题

一次调用中可以使用超过 3 张参考图吗？ 不能。线上 schema 对 image_urls 强制 maxItems: 3——这是通过直接 API 测试确认的，无论其他地方营销文案怎么说。请围绕最多 3 张参考图来设计提示词（通常为：产品 + 场景，或产品 + 场景 + 风格参考）。

如何控制输出的宽高比？ 该模型没有 aspect_ratio 参数。输出继承 image_urls 中第一位那张图像的宽高比——重新排列你的参考图以针对你需要的比例。

它支持无参考图的纯文本生成吗？ 不支持——image_urls 是必填字段。对于纯文本产品效果图，请改用 grok-imagine/text-to-image，价格为 $0.03/图像。

该模型有更高保真版本吗？ 有，grok-imagine-quality/image-to-image 以 $0.08/图像（1K）或 $0.10/图像（2K），外加每张参考图 $0.015 的价格运行相同的参考图驱动工作流程，以提供更锐利的细节。

立即尝试

从你的 hiapi 仪表盘获取一个 API 密钥，准备好一张背景场景，先对少量 SKU 运行你的第一批任务，再决定是否全面更换整个商品目录——按每张图像 $0.036 计算，在 10 个产品上测试该工作流程的成本不到一美元。