使用指南
Ideogram V3 Character Edit 接入指南:源图、蒙版与角色参考图怎么准备
三类图片输入各司其职:按契约字段提交局部编辑,并逐项自检角色一致性与边界
本页内容
三类图片输入各管什么
接入 ideogram-v3-character/edit 之前,先把三个图片字段的职责分开,后面所有准备动作都会变得清晰。
- 源图
image_url:决定「改什么画面」。它提供原始构图、背景和主体位置,是整个编辑操作的底座。 - 蒙版
mask_url:决定「改哪里」。它只圈定需要重绘的区域,区域之外的内容应当保留。 - 角色参考图
reference_image_urls:决定「角色长什么样」。它提供角色的外貌特征,让重绘结果与参考角色对齐。
三者的边界不要混:源图不是角色参考图,角色参考图也不能代替源图;蒙版是空间约束,不是内容描述。把角色特征交给参考图、把画面内容写进 prompt、把修改范围交给蒙版,是最省错误的切分方式。一旦混用(比如只上传角色图不开蒙版、或用蒙版去「暗示」角色长相),排查问题时就会失去判断依据。
在契约层面,源图与蒙版是字符串 URL 字段,角色参考图是数组字段,三者的类型不同也提示了用途不同:前两者是一对一的空间配对,后者是一个独立的人物描述来源。

源图与蒙版的准备要点
image_url 与 mask_url 都是必填字段,格式为 URI,需以 http:// 或 https:// 开头(契约 pattern ^https?://),最短长度为 1。
宽高比必须一致
契约对两者的唯一硬性几何约束是:蒙版必须与源图保持相同宽高比。这不是建议而是前提,准备素材时最稳妥的做法是先在本地把蒙版按源图尺寸输出,再一起上传,不要指望服务端帮你对齐。
蒙版的语义:只圈定重绘区域
蒙版标记的是「允许重绘」的位置。因此:
- 需要保留的部分不要落进蒙版区域;
- 需要改动的主体(如换装、换姿势)应完整落在蒙版内,避免边缘被切开;
- 蒙版不要做得过碎,零散的小块会让模型难以理解编辑意图。
URL 可用性
两个字段都是远程 URL,提交前务必确认链接可以匿名访问、没有跳转失效、没有需要登录的鉴权。蒙版建议使用带透明通道或黑白对比明确的图,避免半透明渐变导致的边界歧义。
角色参考图的规格与限制
reference_image_urls 是必填的数组字段,契约给出明确约束:minItems: 1、maxItems: 1,即需且仅需一张。传两张或传零张都会被判定为不合法输入,这一点与很多「多图参考」的直觉相反,接入时容易踩坑。
格式与体积
- 支持格式:JPEG、PNG、WebP;
- 单张最大 10 MB。
选图建议
角色参考图的作用是提供稳定的人物特征,因此:
- 选清晰、正面或接近正面、面部无遮挡的图;
- 避免强逆光、重滤镜、多人合影(模型无法判断该对齐谁);
- 全身与半身各有取舍:需要服装细节时用半身以上,需要整体造型时用全身;
- 不要用已经带有复杂背景的图去「暗示」场景——场景交给
prompt描述。
数组形式虽然只容纳一个元素,但写法上仍需按数组提交,例如把单个 URL 包成一项,而不是直接放字符串。
必填与可选字段怎么配
必填项共四个:prompt、image_url、mask_url、reference_image_urls。可选调节项包括 expand_prompt、style、seed、rendering_speed。
prompt 写的是新场景,不是编辑指令
契约对 prompt 的定义很关键:「描述参考角色所处的场景,即本次编辑要生成的画面内容」,长度 1–5000 字符。也就是说,不要写「把她的衣服换成红色外套」这类操作指令,而要写「她站在雨后的街道上,穿红色外套,霓虹灯反射在湿地面」这类画面描述。编辑范围由蒙版负责,prompt 负责画面内容本身。
expand_prompt 默认开启
expand_prompt 是布尔开关,默认 true,开启时会用 MagicPrompt 对提示词自动扩写。这意味着你提交的简短描述会被模型再加工一次。排查阶段建议先保持默认,明确长描述与扩写结果的差异后再决定是否关闭。
style 与 seed
style枚举为AUTO、REALISTIC、FICTION,默认AUTO。需要写实人物时用REALISTIC,风格化插画用FICTION,不确定就留在AUTO。seed为整数,范围 0 到 2147483647,用于复现同一提示词的生成结果。想对比「同一输入不同参数」时,固定 seed 能排除随机性干扰。
rendering_speed 档位选择
rendering_speed 是字符串枚举,默认 BALANCED,共三档:
- TURBO:最快出图,适合草稿阶段快速验证蒙版范围、角色是否对得上;
- BALANCED:默认档,速度与细节的折中,日常接入的起点;
- QUALITY:细节最丰富,适合最终出图前的定稿轮次。
选择思路是按阶段切换,而不是一次性定死:先用 TURBO 确认几何与角色方向没问题,再用 BALANCED 或 QUALITY 收敛细节。这样在反复调试时不会把时间消耗在高质量渲染上。
需要强调:三档在计费口径上存在差异(按出图档位计费),具体价格请以站点价格面板为准,本文不展开数字。排查图片输入问题时,先固定为默认档可以减少一个变量。

提交前的自检清单
按契约逐项核对,可以把大部分失败挡在提交之前:
-
prompt非空且不超过 5000 字符,内容是场景描述而非编辑指令; -
image_url为http://或https://开头的可匿名访问链接; -
mask_url同样可访问,且与源图宽高比一致; -
reference_image_urls是数组,长度恰好为 1; - 该参考图格式为 JPEG/PNG/WebP,大小不超过 10 MB;
- 可选字段拼写与枚举值正确(
style、rendering_speed使用契约中列出的大写值); - 如设置了
seed,确认其为 0–2147483647 的整数; - 若关闭了
expand_prompt,确认prompt本身已足够完整。
这份清单同样是排错时的第一站:任何一条不满足,优先修正输入而不是反复调整描述。
角色偏差与边界问题的排查思路
生成结果不如预期时,先把问题归类,再针对性调整,比整张图重提更有效。
类型一:角色不像
表现为面部特征、发型、体型与参考图偏离。调整方向:
- 更换参考图:更清晰的正面图、更好的光照、单人主体;
- 检查参考图是否被截断或压缩过度;
- 在
prompt中补充角色描述(服装、体态、年龄气质),让文字与图像互相印证; - 降低场景复杂度,避免背景元素抢占角色细节。
类型二:边界糊了
表现为蒙版外的内容被意外改动,或蒙版边缘出现接缝、重影。调整方向:
- 先确认源图与蒙版宽高比严格一致;
- 检查蒙版是否把需要保留的部分也圈了进去;
- 让主体完整落入蒙版,避免切边;
- 换成更干脆的蒙版边缘,减少半透明过渡。
两类问题不要混在一起调:角色问题改参考图与描述,边界问题改蒙版与几何。一次只动一个变量,才能判断是哪一项生效。
从示例到接入
把上面的契约要求落成流程,就是四步:准备好同宽高比的源图与蒙版、选一张合规的角色参考图、用场景化 prompt 描述新画面、按清单核对字段后再提交。
接入入口在模型页,字段定义与枚举值以页面为准,可以对照本文清单逐项比对:Ideogram V3 Character Edit 模型页。素材准备对了,后续的调优才有意义。