使用指南
通过 hiAPI API 使用 Ideogram V3 Character Edit 编辑电商产品图片
一份开发者指南：一致的主体、干净的背景替换，以及可用的 hiAPI 请求
本页内容
ideogram-v3-character/edit 的用途
文本生图模型围绕提示词构建：你描述想要的内容，模型凭空创造场景，每次调用都会产生新结果。当你需要全新概念时这很有效，但一旦你有必须保留到编辑结果中的特定主体，这种方式就不够用了。ideogram-v3-character/edit 是这套工作流的另一半。它把现有主体作为输入锚点，并对该主体应用指令，因此主体的身份保持可识别，而周围上下文可以改变。
编辑与生成
判断该用哪种调用，最清楚的方法是问：什么不能变。如果产品、角色或吉祥物是固定点，只有场景、构图或风格需要变化，那你要用编辑模型。如果你在探索概念、没有需要保护的主体，标准文本生图调用更便宜、更灵活。脑中的示意图应有两列：一边是提示词输入、生成全新图像输出；另一边是主体加指令输入、保留主体的图像输出。
编辑调用在实践中为何不同
编辑调用的输出质量，与其说取决于描述已有内容，不如说取决于描述应当改变什么。因为主体已经确立，指令中有用的部分是差异：用不同方式打光、把它放到新背景前、改变相机角度。这也是为什么编辑调用值得比生成调用更严格的审阅循环——你不只在问图像好不好看，还在问它是否仍是同一个主体。
当你有反复出现的视觉主体，并要基于它生成一组受控变体时，在 hiAPI 上使用 ideogram-v3-character/edit。当主体本身仍是开放问题时，使用生成。
角色一致性在电商中的重要性
并非每张电商图片都需要一致性模型。在写第一条提示词之前，先把图片需求分成两堆会有帮助。
受益场景
- 目录变体集。同一产品分别置于影棚白色背景、生活方式室内场景和户外场景中，产品本身不变。
- 季节性活动换肤。同一主推产品贯穿多个活动背景，商品保持一致。
- 品牌角色与吉祥物。反复出现的插画或人偶主体被放入新语境，而无需每次重新设计。
- 多角度或多语境列表。额外拍摄角度必须读起来是同一件实物，而不是相似的东西。
在所有这些场景中，价值在于浏览产品页的审阅者能把主体识别为同一件商品。如果模型每次调用都重新发明主体，你得到的一组图会像是用不同产品拼凑出来的。
不需要该模型的场景
概念探索、情绪板和一次性插图不需要保留主体，强行使用编辑调用会增加你并不想要的约束。同样，如果你的变化纯粹在版式上——裁切、文字叠加、拼贴构图——那属于后处理问题，不是编辑模型问题。
一致性契约
对开发者而言，实用的框架是一份契约：主体稳定，上下文可替换。你为电商套图写的每条提示词都应清楚表明哪些部分属于契约、哪些部分可自由变化。这一纪律会贯穿本指南其余部分。
构造 hiAPI 请求
本节刻意保持概念性。目标是调用的形态，而不是让你盲目复制的参数列表，因为权威字段列表在 hiAPI 模型文档中。
结构
通过 hiAPI API 向 ideogram-v3-character/edit 发起的请求通常包含四个概念部分：
- 主体输入。锚定身份的现有图像。其他一切都相对于它来解释。
- 指令。描述要应用何种变化的文本提示词。
- 模型选择。显式指定
ideogram-v3-character/edit，让路由落到编辑模型上。 - 输出处理。返回图像进入管线的位置——签名 URL、存储写入、队列消息。
客户端代码将其发送到 hiAPI 端点；平台将其路由到模型；模型返回编辑后的图像；你的代码在让任何下游消费之前验证它。
先确定形态，再处理细节
两个结构性决策比任何单个字段都重要。第一，在代码中把主体输入视为不可变——从固定引用加载它，绝不从上一轮输出加载，这样错误无法在链条中累积。第二，把指令保持为单一显式字符串，而不是拼接来自多个来源的片段，因为被打乱的指令是导致结果令人困惑的最常见原因。
边界处验证
在基于响应构建之前，确认你收到了图像，并且请求确实被编辑模型接受，而不是被静默降级。这里薄薄一层验证——检查响应类型、检查图像可获取、记录请求标识符——能让你从一次测试调用转向批量时节省数小时。
以主体为先的编辑提示词
最适合该模型的提示词模式会把初学者通常混成一段的三件事分开：主体、指令和期望场景。把它们写成不同区块，能让编辑更容易推理，也更容易一次只修改一个。
区块一：主体描述
这是关于主体是什么及其决定性视觉特征的简短稳定陈述。对于产品，可能是材质、颜色和轮廓；对于角色，是面部结构、发型和服装。让这个区块在一组中的每条提示词里都保持相同。如果你发现自己在编辑它，别的地方可能出了问题。
区块二：指令
一句命令式句子，描述变化。"将主体置于柔和中性影棚背景前，使用均匀照明"比一段同时重新描述主体的文字更好。指令应假定主体已经存在，只说明要对其做什么。
区块三：场景或约束
任何剩余上下文，以及要保留的内容。有用的结尾句是明确的保留线索：保持主体的比例、颜色和细节不变。说明什么必须保留，往往和说明什么必须改变同样有效。
常见提示词错误
- 在指令中重复主体描述。这会与锚点竞争，而不是补充它。
- 堆叠多个无关变化。每次调用只做一次编辑，失败才能归因。
- 描述性废话。不映射到视觉决策的词只会增加噪声；提示词是规格说明，不是营销文案。
写好三个区块，冻结区块一，只改变调用本应改变的内容。
规划背景替换与变体
一旦一个基础主体获得批准，高效路径就是分支树：一张批准的源图，并行派生出多个背景或场景变体。在运行任何东西之前规划好这棵树，才能让一批结果可审阅。
从一个已批准的基础开始
不要从未批准的主体分支。先获得一张通过质量标准的编辑图像，然后把它当作所有变体的规范输入。这能防止你产出十几张都继承同一缺陷的图像。
定义变体轴
列出你真正需要的维度：背景类型、光照情绪、相机构图、季节语境。每个变体集只改变一个轴，而不是同时改变几个。目录可能先需要固定构图下的三种背景，才需要新光照。按这种方式安排工作，意味着第一批变体验证构图，后续变体复用这份信心。
保持集合可比较
给每个变体一个可预测的标识符，并把指令与输出一起存储。当审阅者标记某张图像时，你可以追溯回产生它的确切指令。实践中，一份小清单——主体引用、指令、输出引用——就够了。
何时停止分支
如果背景替换反复拖拽主体的颜色或边缘，问题在指令或基础图像，不在模型。停止该分支，修复根因，再重新开始。在不稳固的基础上生产更多变体只会成倍增加审阅工作。
扩大规模前审阅输出
有前景的演示与可交付图像集之间的差距是审阅纪律。批量之前，让每张编辑图像通过同一份简短清单。这是发现问题成本最低的地方。
主体保真度
把编辑图像与源主体比较。先检查轮廓和比例，再检查独特细节：标志、五金、产品颜色、角色特征。问一个直白问题——顾客会相信这是同一件商品吗？色相或形状的细微漂移在缩略图中容易漏掉，在产品页上却很明显。
边缘伪影
仔细观察主体与新背景的边界。常见问题有光晕、色边、轮廓沿线细节涂抹，以及阴影与新光照方向不匹配。边缘是背景替换最容易暴露自己的地方。
背景接缝与光照一致性
替换后的背景应感觉像同一张照片。检查地平线或表面平面是否连贯、主体阴影落点是否合理、新环境的色温是否匹配主体自身光照。
联系表审阅
把变体作为一组来审阅，而不是逐张。并排摆放，找出异类——那通常是漂移或接缝问题。批准整组，拒绝个别图像并注明未通过的检查项，只有之后才扩大到批量。
成本与迭代纪律
图像模型按每次生成计费，反复重写提示词并重新生成，是在什么都没学到的情况下烧掉预算的最快方式。防止这一点的纪律是每次运行只改变一个变量。
每次迭代只改一个变量
锁定主体区块，锁定指令，只改变场景行。运行。只改变光照短语。运行。这让每个结果都能归因于单一决策，也意味着在向正确提示词收窄时你保留了可用的提示词。每次尝试都重写整个提示词，每次都会重置你的知识。
缓存并复用已批准结果
一旦某条指令产生你批准的图像，就把该指令及其输出一起存储为可复用单元。未来变体从它分支，而不是重新推导。在一个目录项目中，这会变成一座可快速组装的已知良好指令库。
批量前先测试
在你计划扩大的确切指令集上先跑一个小型试点。少量代表性调用会在大批量放大问题之前揭示漂移或接缝问题。用你在完整运行中会使用的同一份清单验证并审阅试点。
跟踪花费与价值
因为 hiAPI 按每次生成计费，实时价格在网站的价格面板中，正确的规划动作是估算一组需要多少次调用，以及每次是否可能通过审阅。如果某个变体轴持续失败，就修复提示词或基础图像，而不是用同一指令重试——对已知糟糕的提示词重试是这套工作流中最昂贵的习惯。
保持紧密的迭代循环，尽早批准基础主体，hiAPI 上的 ideogram-v3-character/edit 就会成为你产品图像管线中可预测的一部分，而不是实验。
