gpt-image-2.5-flare 用于电商产品图：基于 hiapi API 的批量工作流

产品摄影通常是上架商品目录中最慢的一环：每个 SKU 都要棚拍一次，每个季节性背景都要重拍一次，每个平台的不同宽高比规则还要再拍一次。hiapi 上的 gpt-image-2.5-flare 将其中大部分工作浓缩为一个模型 ID——它既能根据文本提示词生成产品图，也能编辑已有照片（替换背景、布置到生活场景中、为不同渠道调整尺寸），而无需改动产品本身。本指南将通过三个真实工作流和未经编辑的 API 输出进行演示，然后展示如何将其批量应用于整个商品目录，而不是一次只处理一张图片。

下图中展示的产品（一瓶标有“MOSS”的绿色玻璃瓶，以及一只标有“AER”的钴蓝色水壶）是用于演示此技术的概念道具，并非真实的客户摄影——但每张图片都是 hiapi API 的真实、未经编辑的输出，而非模拟图。

为什么关键是一个模型 ID

gpt-image-2.5-flare 会根据你传入的内容处理两种不同的任务：

• 省略 image_urls，它仅根据你的文本提示词生成图片（文生图）。
• 添加 image_urls，它会改为编辑提供的照片（图生图）——同一个模型、同一个端点、同样的定价。

对于商品目录而言，这比听起来更重要：无论你是首次拍摄产品，还是复用现有照片，都不必在两个模型 ID 或两套定价方案之间来回切换。另外两个细节使其特别适合批量处理：

• 质量档位，而非单一固定成本。 你可以按请求选择 low / medium / high / xhigh / max，因此 500 个 SKU 的缩略图批次和首页的十几张主图不必按相同的单张成本计费。
• 灵活的宽高比。 每次请求可选择 1:1、4:5、9:16、16:9 等比例，因此同一张产品图无需重拍即可裁切为方形市场网格、竖版移动端信息流或宽幅横幅。

每次调用都通过 hiapi 的异步任务 API 进行：POST /v1/tasks 提交任务，然后轮询 GET /v1/tasks/{id}（或使用回调）直到状态为 success。没有同步的“响应中直接返回图片”调用——生成和编辑都需要数秒时间。

第 1 步：从零生成干净的棚拍图

从一张简单、光线充足的棚拍照片开始——这是你后续步骤中要编辑的基础素材。

import os
import time
import requests

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


def create_task(prompt, quality="medium", aspect_ratio="1:1", image_urls=None, idempotency_key=None):
    payload = {"model": "gpt-image-2.5-flare",
               "input": {"prompt": prompt, "quality": quality, "aspect_ratio": aspect_ratio}}
    if image_urls:
        payload["input"]["image_urls"] = image_urls
    headers = dict(HEADERS)
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    resp = requests.post(BASE, headers=headers, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]


def wait_for_task(task_id, timeout_s=300, poll_every=5):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        if task["status"] == "success":
            return task["output"][0]["url"]  # download or re-upload immediately — it expires
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")


studio_shot_url = wait_for_task(create_task(
    "Photorealistic square studio product photograph. Center exactly one translucent forest-green "
    "glass perfume bottle with a brushed silver cylindrical cap on a pale ivory stone pedestal. A "
    "small rectangular cream label reads \"MOSS\" in a thin serif font. Soft diffused studio lighting, "
    "seamless pale warm-gray background, subtle reflection, no props, no text elsewhere in frame.",
    quality="medium",
    aspect_ratio="1:1",
))

quality="medium" 是首轮处理的合理默认值——本文中每张图片都使用同一档位。仅在额外细节值得成本时，才将个别 SKU 提升到 high（见下方定价表）。

第 2 步：重新设计背景而不重新生成产品

这才是真正节省目录工作量的工作流：将棚拍图作为 image_urls 传回，仅描述你想要的更改，产品本身保持像素级一致——同样的瓶形、同样的瓶盖、同样的标签——而背景发生变化。

seasonal_variant_url = wait_for_task(create_task(
    "Edit the supplied product photograph. Change ONLY the seamless background from pale warm gray "
    "to muted terracotta orange. Preserve the exact bottle shape and green glass color, the silver "
    "cap, the cream label and all its text, the lighting direction, and the camera angle exactly.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=[studio_shot_url],
))

同样的模式也适用于完全不同的产品——这里是一只钴蓝色水壶，其背景被替换为温暖的桃色棚拍背景布，生成方式相同：

这就是“季节性焕新”或“新市场主题”任务的核心：每个 SKU 一次编辑调用，产品不受影响，背景改变。运行 500 次，你就在无需重拍的情况下为整个商品目录换上了新主题。

第 3 步：将产品布置到生活场景中

棚拍图适合市场网格展示；生活场景则能在落地页或广告中推销产品。同样的编辑模式，更宏大的提示词——模型会将确切的产品放入一个合理的真实世界场景中，而不仅仅是改变背景颜色。

lifestyle_url = wait_for_task(create_task(
    "Create a photorealistic square lifestyle product photograph using the supplied blue kettle as "
    "the exact product reference. Keep the original cobalt-blue kettle, black handle and base, "
    "brushed-metal spout and lid, black knob, and all lettering completely unchanged. Place it on a "
    "sunlit kitchen countertop with soft natural morning light, a few blurred kitchen props in the "
    "background, shallow depth of field.",
    quality="medium",
    aspect_ratio="1:1",
    image_urls=["<your kettle product photo URL>"],
))

在每个编辑提示词中保留约束性语言（“keep the original ... completely unchanged”）——正是它阻止模型在改变周围一切的同时使产品发生漂移。

面向完整商品目录的批量自动化

单次编辑调用很有用；在目录规模下，价值在于无人值守地对每个 SKU 运行相同的模式。在生产环境中行之有效的结构如下：

import concurrent.futures
import csv

QUALITY_BY_USE = {"thumbnail": "low", "listing": "medium", "hero": "high"}


def process_row(row):
    idem_key = f"{row['sku']}-{row['use']}-{row['background']}"
    prompt = (
        f"Edit the supplied product photograph. Change ONLY the seamless background to "
        f"{row['background']}. Preserve the exact product shape, color, materials, label text, "
        f"lighting direction, and camera angle."
    )
    try:
        task_id = create_task(
            prompt,
            quality=QUALITY_BY_USE[row["use"]],
            aspect_ratio=row["aspect_ratio"],
            image_urls=[row["source_photo_url"]],
            idempotency_key=idem_key,
        )
        return row["sku"], wait_for_task(task_id)
    except Exception as exc:
        return row["sku"], f"ERROR: {exc}"


with open("catalog.csv") as f:
    rows = list(csv.DictReader(f))  # sku,source_photo_url,background,use,aspect_ratio

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(process_row, rows))

当处理超过少量图片后，以下几点很重要：

• 逐行幂等键。 为每个 SKU/变体发送一个不同的 Idempotency-Key 请求头，这样超时后重试的请求不会创建——并重复计费——重复任务。
• 限制并发数，不要一次性全部发出。 小型线程池（或异步信号量）可避免触发速率限制；在遇到 429 时退避并重试，而不是将其视为硬性失败。
• 根据图片用途选择质量档位，而非统一标准：缩略图和网格列表通常只需 low/medium，而首页主图或广告创意则值得使用 high 或 xhigh。
• 从同一张已编辑的源图衍生不同宽高比，而不是从原图衍生——先运行一次背景替换编辑，然后从该结果请求 1:1、4:5 和 9:16 的裁切版本，使每个渠道展示完全相同的产品呈现。
• 立即下载或重新上传输出 URL。 任务输出会过期；不要将临时 URL 作为你的永久图片来源。

定价

gpt-image-2.5-flare 按输出图片数量、根据质量档位计费——无论是从零生成还是编辑，费率相同：

质量	每张图片价格
low	$0.0172
medium	$0.0672
high	$0.1829
xhigh	$0.3572
auto	$0.3572
max	$0.7143

在 medium 档位下，为 500 个 SKU 的目录重新设计主题、每个产品一次背景替换编辑，成本约为 $33.60。请查看定价页面了解所有模型的完整最新费率表。

常见问题

编辑会意外改变我的产品吗？ 将编辑提示词限定为单一更改（“仅更改背景……”），并明确列出必须保持不变的内容（形状、颜色、标签文字、相机角度）。上述示例显示产品在每次编辑中都保持不变。

同一个模型既能生成又能编辑吗？ 可以——gpt-image-2.5-flare 是一个模型 ID。包含 image_urls 可编辑现有照片；省略它则仅根据提示词生成。

一次编辑调用可以传入多少张源图片？ 通过 image_urls 最多可传入 16 张，不过大多数产品目录编辑只需一张——即你要重新设计的那张照片。

如何避免重试时重复计费？ 为每个请求发送唯一的 Idempotency-Key 请求头。使用相同键的重试请求会返回原始任务，而不是创建新任务。

相关阅读

如果你正在设置第一次调用，请从 gpt-image-2.5-flare API 指南开始，获取最小工作示例并更深入地了解异步任务生命周期。如需产品摄影之外的更多提示词模式，请参阅 GPT Image 2.5 Flare 提示词：附带真实输出的复制粘贴配方。完整参数和 schema 见模型页面，通用 API 约定（认证、任务轮询、回调）见 hiapi 文档。

准备在自己的商品目录上尝试了吗？从 hiapi 仪表盘获取 API 密钥，然后对第一张产品照片运行上面的棚拍图示例。