使用指南
面向 HiAPI 上 grok-imagine/text-to-image 生成电商产品图的开发者指南
提示词模板、超宽画幅比例，以及可直接用于目录级视觉素材的 API 请求示例
为什么在电商图片流水线中使用文本生图模型
每个商品目录都有大量棚拍难以处理的图片位。一款有四十个配色在售的产品、一个每季度都会变化的组合装、一张午饭前就要做好五个地区版本的主题横幅——这些在成为创意问题之前，首先是排期问题。文本生图并不能替代摄影师拍摄旗舰级主视觉。它能承担的，是围绕这些主视觉的大量重复性工作。
把分工说清楚很有必要。grok-imagine/text-to-image 适合这样的任务：主体可以用文字描述，构图可以重复：
- 变体扩展。 一个基础构图，衍生出多种配色、材质或包装状态。
- 占位与草稿位。 输出足够像样的目录级图片，让排版和商品企划评审在最终素材到位前先推进起来。
- 概念探索。 在预约付费拍摄之前，快速尝试背景、氛围和取景。
- 地区与格式变体。 同一产品，重新构图为宽幅主视觉横幅或方形网格图块。
它不适合对还原度有合同性要求的场景。受监管的宣传表述、精确的标签字体排版、精准的材质表面效果，以及任何需要对实物进行法律上可验证描绘的内容，都应交给摄影或受控的渲染流水线。文本生图模型是生成式的——它们会近似地画出一个标志，而不会精确复现它。
务实的划分方式是把工作当成队列。昂贵、高保真的工作交给人工。可重复、可描述、大批量的工作交给模型，并在生成与发布之间安排人工审核环节。一旦接受这种分工，工程上的问题就变得很常规：如何保持输出一致，如何为店铺实际使用的画幅比例做规划，以及如何在不盯守的情况下批量跑任务？
本指南的余下部分将结合 HiAPI 平台逐一解答这些问题，最后给出一个可以调整后用于你自己商品目录的请求结构。
grok-imagine/text-to-image 在 HiAPI 上提供什么
在 HiAPI 上，grok-imagine/text-to-image 是一个通过单一统一 API 接口访问的模型标识符。你发送一段描述所需图像的文本提示词，返回一个生成的图像资源。在概念层面，这就是全部约定——值得直白说明，因为很多集成痛点都源于假设过多。
对规划而言，有几个范围说明很重要：
它由提示词驱动，而非参考图驱动。 你得到的构图来自提供的文本。如果某个图位要求精确复现实物，这个模型就不是合适的工具；应把它用在可以接受按描述忠实描绘的场景。
一切都通过同一个接口流转。 身份验证、请求结构和响应处理都遵循 HiAPI 平台惯例，而不是模型专属的方言。这意味着你为这个模型写的代码，与平台上任何其他图像模型的代码骨架相同，从而让你的客户端层保持精简。
提示词是你最主要的控制面。 由于你不用结构化字段或参考图来引导模型，提示词规范承担了大部分责任。下一节会把它转化为模板。
计费遵循平台的计量方式，当前费率见定价面板。 按每次目录运行生成的图片数量来规划容量，然后到面板查看实时数字，不要把任何数值硬编码进规划文档。
不要假设存在未文档化的可调参数。 如果某个参数不在你所依据的请求 schema 中，就不要构建依赖它的流水线。把已文档化的请求面视为约定，并将模型特定行为挡在业务逻辑之外。
一个有用的心智模型：HiAPI 提供稳定、统一的入口，grok-imagine/text-to-image 则是门后的东西。让你的集成始终指向这个入口。
为一致的产品视觉设计提示词模板
整个目录的一致性不是模型本身的属性，而是提示词架构的属性。如果每条提示词都是随手写的，每张图都像不同一次拍摄。解决办法是把提示词分解为固定模块，只变化描述产品的那个模块。
四模块模板
[SUBJECT] 产品是什么，及其关键材质/颜色属性
[STAGING] 它在画面中如何摆放：角度、裁切、支撑面、比例
[LIGHTING] 光位、柔和度、色温、阴影表现
[BACKGROUND] 表面、景深、环境、留白
[CONSTRAINTS] 不得出现的内容：文字、水印、多余道具、人物
在同一个目录批次中，保持 STAGING、LIGHTING、BACKGROUND 和 CONSTRAINTS 逐字节一致。只有 SUBJECT 应按产品变化。仅靠这一条纪律，就能让网格看起来基本协调一致。
一个电商实战模板
Studio product photograph of {product_name}, {material}, {color}, {finish}.
Centered three-quarter view, product fills roughly 60% of frame height,
resting on a matte neutral surface. Soft large-source key light from
upper left, gentle fill from right, subtle contact shadow directly
beneath. Seamless light-grey background with clean negative space
above the product. No text, no logos, no watermarks, no props, no people.
从你的产品数据库中填入 {product_name}、{material}、{color} 和 {finish}。其余内容都是代码库中的常量，最好放在带版本的模板文件里，并把 template_version 字符串写入生成日志——这样当视觉风格漂移时，你能判断是模板变了还是模型变了。
实用规则
- 顺序的重要性不如稳定性。 选定一种模块顺序后，在同一个目录中永不改变。
- 描述材质，而非品牌。 “拉丝铝”是可引导的；商标则不是。
- 把主体前置。 将具体名词短语放在前面，让它锚定构图。
- 明确写出否定项。 对产品工作而言，
CONSTRAINTS模块不是可选项——杂散文字和道具是图片不可用的最常见原因。 - 先生成三个产品测试，再生成三百个。 模板缺陷会随目录规模线性放大。
把提示词当作代码：为其进行版本管理、审查变更，并让生成的资源始终关联到产生它的模板版本。
为店面规划超宽画幅比例
画幅比例是一个常常被拖到最后才做的设计决策。常见顺序是：生成一张漂亮的方形图片，然后发现首页主视觉想要的画面宽得多，再裁切并丢掉产品顶部三分之一。先规划比例。
生成前先盘点你的图位
走查你的店面，列出每个将承载产品图的不同画框形状：网格图块、详情页图库、分类横幅、首页主视觉、邮件页头，以及任何付费媒体投放位。每个图位都有形状，并且形状会聚类。将它们分组，按组生成，而不是按单张图片生成。
超宽画幅带来的变化
宽画布并不是拉宽的方形。当宽度相对高度增加时：
- 水平安全区变大，垂直安全区变小。 靠近顶部或底部边缘的任何内容，都可能在小视口的响应式裁切中被切掉。
- 主体比例需要决策。 在方形画面上大小合理的居中产品，在超宽画面上会变成一座小岛。要么有意放大它，要么接受产品占据一侧的构图。
- 留白成为关键。 宽幅画框通常会承载叠加文字、价格徽章或 CTA。在提示词中显式预留该区域——例如“右侧三分之一保留干净无干扰的背景用于标题文字”。
- 光照渐变会被拉伸。 在方形画面上效果良好的柔和暗角，在宽画面上可能看起来像一片污迹。让光照描述保持简单且有方向性。
能经受宽幅裁切的构图模式
- 产品居左，留白居右。 主视觉横幅最稳妥的模式。
- 产品居中，两侧留足边距。 当同一素材还需要裁切成方形时适用。
- 产品居右，环境居左。 适合左侧由表面或纹理承载的生活方式横幅。
按你所需的最宽目标生成
如果一份素材必须同时服务宽幅主视觉和方形图块，请按宽幅画框构图生成一个版本，并在布局中规划方形裁切——或者从同一模板用不同的 staging 模块生成两个版本。你应当避免的是按窄画幅构图，然后指望宽幅版本也能用。
把预期比例与产品 ID 一起写入同一份模板元数据，这样存储中的每份素材都知道自己是为哪个图位构建的。
构建一个可运行的 HiAPI 请求
集成骨架刻意保持无聊，而这正是你想要的。组装提示词，带上你的凭证和模型标识符发送到 HiAPI 端点，处理返回的素材。
流程梗概
import os, requests
HIAPI_BASE = "https://api.hiapi.ai" # confirm exact base in platform docs
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
def build_prompt(product, template):
return template.format(
product_name=product["name"],
material=product["material"],
color=product["color"],
finish=product["finish"],
)
def generate_image(prompt, aspect_ratio="1:1"):
payload = {
"model": "grok-imagine/text-to-image",
"prompt": prompt,
"aspect_ratio": aspect_ratio,
}
resp = requests.post(
f"{HIAPI_BASE}/v1/images/generations",
headers=HEADERS, json=payload, timeout=120,
)
resp.raise_for_status()
return resp.json()
在发布前，请把端点路径和确切参数名视为需对照平台当前文档核实的内容——这段代码展示的是结构，不是冻结的 schema。重要的属性有：
- 模型标识符是数据，不是代码。 将
"grok-imagine/text-to-image"存放在配置中，这样换模型只是改配置。 - 提示词是组装出来的，绝不手工输入。 一个
build_prompt函数，一个模板来源。 - 比例是调用的参数。 它属于请求的一部分，应依据图位盘点来选择，而不是作为后处理裁切来应用。
- 密钥来自环境变量。 仓库中不放任何凭证。
记录你以后需要的信息
对每个请求，持久化保存：请求 ID、产品 ID、模板版本、画幅比例、完整提示词字符串、模型标识符、时间戳，以及返回的素材引用。当商品运营人员问为什么某一图块看起来不对时，这份日志能在几秒内而不是一下午给出答案。
保持客户端精简
把调用包装在一个小函数中，返回素材引用或类型化失败。你的目录任务不应了解 HTTP，你的 HTTP 层也不应了解产品。正是这种分离让下一节的重试逻辑保持简短。
处理输出、重试与批处理任务
生成是容易的部分。真正让图片流水线可信的所有事情，都发生在响应返回之后。
发布前先验证
每个返回的素材都应在进入目录图位前通过自动门禁：
- 它是否存在且可解码？ 一个能下载但解析失败的文件，是等待上线日爆发的静默失败。
- 形状是否匹配图位？ 对照你请求的比例检查尺寸，而不是对照你期望的比例。
- 约束是否成立？ 如果你的模板禁止图中出现文字，请标记检测到文字的素材——轻量分类器，甚至小批量时对样本做人工抽查，都足够。
- 它是否通过人工审核？ 对任何面向客户的内容，安排审核步骤。审批状态是素材记录上的一个字段，而不是一条 Slack 消息。
有区分地重试
并非所有失败都一样，同等对待会浪费容量。
- 传输和限流错误： 使用带抖动的指数退避重试，并限制在少量尝试次数内。
- 服务端故障： 带退避重试几次，然后将该项标记为失败并继续。
- Schema 或验证错误： 绝不重试——它们会以同样方式失败。记录并告警。
- 质量拒绝： 不要盲目重试。重跑完全相同的提示词往往会得到相似结果。调整单一变量——通常是主体描述——并记录该次重试使用了修改后的提示词。
以 (product_id, template_version, aspect_ratio) 为任务键，使每次尝试都具备幂等性。崩溃的工作进程应能恢复，而不重复花费。
以队列而非循环运行批次
对超过少量图片的任何任务，都应将工作组织为队列：
- 枚举 从产品数据库和图位盘点中得到的目标输出，生成状态为
pending的任务记录。 - 处理 任务时限制并发——保守起步，只有在观察到延迟稳定后才提高。
- 持久化 每个结果到对象存储的确定性键下，并写入带有生成元数据的素材记录。
- 报告 批次情况：尝试数、成功数、失败数、审核拒绝数和总重试数。发布这份摘要，而不只是成功计数。
增加 dry-run 模式，组装并记录每条提示词而不调用 API。这是在上千个 SKU 上捕获模板缺陷最便宜的方式。
将产品图发布到生产前的检查清单
在第一个目录批次上线前运行此清单。
提示词质量
- 模板已拆分为主体、摆放、光照、背景和约束模块。
- 在一次目录运行中，只有主体模块变化。
- 否定约束明确，并包含文字、水印和杂散道具。
- 模板已纳入版本控制，且版本字符串已写入每条素材记录。
- 已用至少三个代表材质和颜色极端情况的产品做抽查。
比例覆盖
- 每个店面图位都有记录在案的比例和对应的摆放模式。
- 超宽素材按宽幅画框构图，并有为叠加文字预留的留白。
- 响应式裁切已在你支持的最小视口上审查。
流水线可靠性
- API 密钥从环境加载，绝不提交到仓库。
- 模型标识符和端点位于配置中，并已对照平台当前文档核实。
- 重试策略区分传输、服务端、验证和质量失败。
- 任务在产品、模板版本和比例上具备幂等性。
- 每个请求都记录提示词、比例、模型、时间戳和返回的素材引用。
审核与运营
- 对面向客户的素材设置了人工审批门禁。
- 批次摘要报告失败和审核拒绝，而不仅是成功。
- dry-run 模式可用，并在大批量运行前实际使用过。
- 已在平台定价面板确认当前计费费率，并按图片数量规划容量。
当每一项都打勾，且样本批次看起来像同一次协调的拍摄，而不是一群陌生人的集合时，就可以发布了。
