博客

使用指南

Ideogram V3 Character Edit 接入指南:源图、蒙版与角色参考图怎么准备

三类图片输入各司其职:按契约字段提交局部编辑,并逐项自检角色一致性与边界

2026年11月18日 5 分钟阅读
博客封面图:深墨绿底上两组宽扁条带交织成技术编织格纹,黄铜色纵向穿插,几何克制。
本页内容

三类图片输入各管什么

接入 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。

选图建议

角色参考图的作用是提供稳定的人物特征,因此:

  1. 选清晰、正面或接近正面、面部无遮挡的图;
  2. 避免强逆光、重滤镜、多人合影(模型无法判断该对齐谁);
  3. 全身与半身各有取舍:需要服装细节时用半身以上,需要整体造型时用全身;
  4. 不要用已经带有复杂背景的图去「暗示」场景——场景交给 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 模型页。素材准备对了,后续的调优才有意义。

立即开始构建持久 AI 产物

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

阅读 API 文档