博客

使用指南

muse-image-1.0/text-to-image 用于电商产品图片:开发者工作流指南

通过 HiAPI API 实现角度与光照的提示词模板、尺寸选择和批量请求

2026年11月9日
交错排列的扁平黄铜色与深绿色丝带,在近乎黑色的深绿背景上构成开放式格纹——本指南的封面图。
本页内容

为什么 text-to-image 适合电商产品工作负载

目录工作本质上是重复性的:同一产品,从几个角度拍摄,用同样的布光,放在同样的背景上,做成几种尺寸。这种重复性正是 text-to-image 模型擅长处理的事情——不是用来替代主推产品的影棚拍摄,而是以低成本、一致的方式填补目录的长尾部分。

生成技术真正有价值的场景:

  • 大批量变体。 配色方案、细微的 SKU 差异以及包装改版,这些情况下重新拍摄的成本高于图片本身的价值。
  • 占位和上市前素材。 列表页面、内部评审材料以及 A/B 测试,在最终摄影素材到位之前需要看起来真实的内容。
  • 构图探索。 在投入摄影师和影棚档期之前,先尝试俯拍平铺与 45 度主图效果。

不适合的场景:受监管的宣传声明、必须清晰准确的包装文字,以及客户会比较精细材质质感的主图。这些仍然需要相机和人来完成。

对开发者而言,心智模型就是一条流水线。输入结构化的产品描述,渲染提示词模板,模型返回一张或多张图片,然后由 QA 检查决定哪些内容可以上架到店铺。下面每一节讲的都是如何让这条流水线变得平淡可重复,而不是追求聪明。

目录流水线就像平纹编织:一条提示词进入格纹结构,同样的结构产出多张独立的产品图。

通过 HiAPI 调用 muse-image-1.0/text-to-image

所有请求都通过同一个 HiAPI 接口,因此你只需认证一次,就可以为所有调用的模型保留一个客户端。模型标识符是 muse-image-1.0/text-to-image;你的请求携带提示词、输出尺寸选择,以及任何你想固定的单次生成选项。

从结构层面看,单次生成是:构建请求负载,通过 HiAPI 客户端 POST 发送,读取返回的结果对象,并将图片引用与其所属的产品 ID 一起持久化。从第一次调用起就值得养成的两个习惯:

  1. 把提示词保存在变量中,而不是内联在请求里。 你会重复使用和比对它数百次。
  2. 每次输出都记录精确渲染后的提示词。 三周后当图片看起来有问题时,提示词是你唯一的调试依据。
import os
from hiapi import HiAPI

client = HiAPI(api_key=os.environ["HIAPI_API_KEY"])

prompt = render_product_prompt(product, angle="three-quarter", light="softbox-left")

result = client.images.generate(
    model="muse-image-1.0/text-to-image",
    prompt=prompt,
    size="1024x1024",
)

save_asset(product_id=product.id, angle="three-quarter", result=result)

把 size 当作模板的一部分,而不是事后才考虑的事情——同一提示词在不同宽高比下可能会重新构图主体。接下来的章节同时涵盖提示词结构和尺寸决策。

请求从客户端经由端点到达模型,编织的丝带返回一张图片结果。

用于一致拍摄角度的提示词模板

目录中的一致性来自固定的提示词骨架,只替换少量槽位。如果每条提示词都是从头写的,每张图片都会产生偏移。为每种拍摄类型构建一个模板,并让相机描述语言在所有产品之间保持逐字节相同。

一个可用的骨架:

{subject_block}. {camera_block}. {light_block}. {background_block}. {style_block}

只有 subject_block 随产品变化。camera_block 是每个角度的常量:

  • 主图 / 四分之三视角: product photographed at a 45-degree three-quarter view, slightly above eye level, full product in frame with even margins
  • 正面立面: straight-on front view, camera at product mid-height, centered, no perspective tilt
  • 俯拍平铺: directly overhead top-down view, product centered, flat lay composition
  • 细节特写: close-up macro view of the product surface, shallow depth of field

两条规则让这些在实践中奏效:

  • 两次说明视角。 明确的角度加上构图条款(如 "full product in frame with even margins")比单独使用任一项更可靠。
  • 避免相对引用。 "Same angle as the last image" 对 text-to-image 模型没有任何意义;每条提示词都必须独立成立。

将模板与渲染代码一起存放在版本控制中。当你修改 camera_block 时,提升版本号并在提交前重新生成一个小样本——措辞的变更就是整个目录的变更。

用于光照和背景的提示词模板

光照和背景是让生成的一组图片看起来像同一次拍摄、而不是一堆不相关图片的关键。两者都属于模板的常量部分,需要明确方向和柔度。

可可靠迁移的光照语言:

  • 方向: key light from camera left、light from upper right、soft overhead light。方向是最直观的一致性杠杆——为每种拍摄类型锁定它。
  • 质量: soft diffused light、large softbox, gentle shadows、hard directional light with defined shadow edge。
  • 补光和溢光: subtle fill from the right, low-contrast shadows、clean highlight on the top surface。

背景语言:

  • 无缝影棚: on a seamless light grey studio backdrop, no horizon line, soft contact shadow beneath the product。
  • 生活方式台面: resting on a matte stone surface, softly out-of-focus neutral background。
  • 便于抠图: isolated on a plain white background, product fully in frame, generous margins for cropping。

两个实用提醒。首先,产品的表面和反射越多,你就必须越精确地描述光照,因为高光的位置就是产品的外观。其次,不要在同一拍摄类型中混用背景——一个网格图块组应共享背景,否则网格看起来会像是从三个不同供应商拼凑的。将这些块固定为常量,只在有意为之的时候才更改。

选择输出尺寸和宽高比

在批量处理之前,按投放位置决定尺寸,因为用不同尺寸重新运行是完整的重新生成,而不是调整大小。先将投放位置映射到宽高比,再映射到前端实际渲染的像素尺寸。

  • 网格和分类图块: 正方形。产品网格裁剪不可预测,所以带有充足边距的正方形构图能适应大多数图块布局。
  • 产品详情页: 正方形或 4:3,按缩放查看器而不是缩略图的尺寸来定。如果产品详情页裁剪为固定比例,就精确匹配它,不要在 CSS 里与之对抗。
  • 横幅和主图条: 宽幅,并明确规划安全区域。要求产品居中、两侧留有负空间,好让营销文案有地方放置。
  • 邮件和社交媒体: 匹配平台原生比例;重新生成比加边填充更便宜。

几条经验法则:

  1. 每个投放位置选择一个规范尺寸并重复使用。 一个图块网格中混用多种尺寸会导致可见的质量差异。
  2. 不要放大生成图片来填充更大的位置。 生成更大的尺寸再缩小。
  3. 比例改变后重新检查构图。 为正方形构图的 45 度主图在宽幅裁剪中可能丢失产品底座;相应调整 camera_block 中的构图条款。
  4. 将尺寸保留在任务记录中。 之后审核输出时,尺寸是上下文的一部分,不是元数据噪音。

批量请求与逐项结果处理

在目录规模下,工作单元是任务,而不是请求:一个产品、一种拍摄类型、一个尺寸、一条渲染后的提示词。先将任务建模为数据,并通过有界队列发送,这样失败就是一个可重新运行的行,而不是一个下午的损失。

一个健壮的循环做四件事:

  • 确定性地渲染提示词:从模板加产品字段渲染,并将渲染后的字符串存储在任务上。
  • 限制并发:以你的账户和下游存储能承受的量为限;不要一次性发起整个目录的请求。
  • 逐项处理结果。 批量操作是逐项成功或失败的,因此将每个结果写入其 job_id 下,永远不要假设整批是原子的。
  • 仅对瞬时错误进行退避重试。 验证错误——格式错误的提示词、不支持的尺寸——重试时会以相同方式失败,所以先分类再重试。
for job in queue.fetch_pending(limit=50):
    try:
        result = client.images.generate(
            model="muse-image-1.0/text-to-image",
            prompt=job.prompt,
            size=job.size,
        )
        db.record_success(job.id, result)
    except TransientError as e:
        queue.requeue(job.id, backoff=e.retry_after)
    except ValidationError as e:
        db.record_failure(job.id, reason=str(e))

为每个任务保留状态列(pending、done、failed),并为失败提供死信视图。当一批任务完成时,按拍摄类型和尺寸报告计数,而不是只报一个总数——回归问题就藏在那里。

发布生成图片前的 QA 检查清单

生成的图片需要一道关卡,而关卡应该是一份有人在背后把关的检查清单。自动化检查能抓住廉价的问题;审核者能抓住昂贵的问题。

审核前的自动化检查:

  • 目标投放位置的宽高比和像素尺寸正确。
  • 没有明显损坏的输出;文件能正常打开和解码。
  • 提示词指定了产品配色时,颜色符合预期。
  • 网格图块中留有供裁剪容差使用的边距。

发布前的人工审核:

  • 产品看起来像这个产品吗——形状、比例、五金件和表面处理?
  • 是否有虚构的文字、标志或包装文案?生成的文字是常见失败点,在店铺中也是法律风险。
  • 光照和背景在缩略图尺寸下与组内其他图片一致,而不仅仅是在全尺寸下。
  • 画面中没有多余物体、额外组件或不合逻辑的反射。
  • 宣传声明和受监管的标签未被生成技术改动;这些图片应走摄影流程。

为每个批准的素材记录审核者和提示词版本。当客户投诉或下架请求到来时,这条轨迹能让你一次性找到所有受影响的图片——并重新生成或撤下整套图片。

从一种拍摄类型、一个尺寸和一个小产品样本开始,通过 HiAPI 接口运行,只有在输出通过审核后才扩展模板。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档