使用指南
Seedream 5.0 Lite 图生图上手指南：能力边界、定价与接入要点
从能力判断到调用参数与成本核算，开发者的实操路线
图生图能解决什么问题
文生图（text-to-image）要求你把意图压缩成一段描述，模型再从零开始「想」出一张图。图生图（image-to-image）换了一条路径：你交给模型一张已有的图，再附加修改意图，模型在保留原图结构、构图、主体关系的基础上做变换。
seedream-5.0-lite/image-to-image 就是这一类能力：由 ByteDance 提供，输出类型为图像，输入是图像而非纯文本提示。判断它是否适合你的业务，先看三个信号：
- 原始视觉信息必须保留。例如商品图换背景、人像换风格、线稿上色、海报改配色——这些场景里，纯文本描述很难稳定还原原图细节。
- 提示词表达成本过高。当用户不会写 prompt，但会用手机拍一张图时，图生图把「表达」这一步交还给图像本身。
- 需要批量、可控的视觉一致性。同一套模板反复作用于不同输入图，比每次重新生成更可控。
反过来，如果需求是「从零生成一个此前不存在的画面」，文生图更直接；如果需求是「精准抠图、局部像素级编辑」，那属于更专门的编辑能力，不要指望通用图生图模型做到位。
一个常见的误区是把图生图当成「万能的 Photoshop」。它的强项是在保留整体语义的前提下做风格、氛围、细节层面的变换，而不是逐像素听指令。先把这条边界写进产品预期，后面的调试会顺很多。
图生图与文生图的输入差异
文生图的输入是提示词，输出是图像；图生图的输入至少包含一张参考图，输出同样是图像。这意味着你的工程链路会多出几件事：图像上传与存储、格式与尺寸校验、输入图的预处理。这些在文生图里是不存在的，规划时要把它们算进工作量。
接入前需要确认的接口契约
在写第一行调用代码之前，先把接口契约核实清楚。不要凭对「图生图」这三个字的想象去猜参数名和字段结构。以下是必须逐项确认的清单。
输入格式
- 参考图以什么形式传入：URL、二进制上传，还是 base64？不同方式对文件大小、网络超时、临时存储的要求不同。
- 支持哪些图片格式与尺寸范围？是否需要你自行做等比缩放或裁剪？
- 提示词是必填还是可选？如果可选，纯图输入时模型的行为是什么？
输出格式
- 返回的是图像 URL 还是二进制内容？如果是 URL，有效期多久，需要你多快转存到自己的对象存储？
- 输出图像的尺寸由谁决定：跟随输入图、由参数指定，还是模型自行决定？
- 是否返回可用的元信息（如实际输出尺寸），以便你做后续排版与计费核对。
请求与响应处理
- 同步返回还是异步任务？如果是异步，如何轮询、超时多久、失败时如何取回错误信息？
- 错误码的语义：参数错误、内容审核拒绝、上游超时，是否可区分？这直接决定你的重试策略。
- 限流口径：按请求数还是按并发？需要提前为峰值流量做排队设计。
接入路径
在 HiAPI.ai 的统一接口语境下接入，好处是你面对的是同一套鉴权、同一套请求结构和同一套计费口径，模型切换时业务代码改动最小。具体字段名与调用示例以控制台与接口文档为准，本文不替代文档。先把上面三组问题在文档里逐一找到答案，再开始写代码。
按张计价：把单价换算成业务成本
seedream-5.0-lite/image-to-image 按张计费。定价口径是每张若干金额，具体单价与实时价格以站点价格面板为准，本文不写死数字。你需要做的是把这个「按张」的口径，翻译成自己业务能看懂的账。
成本估算的三步法
- 确定一张的定义。一次成功请求产生一张输出图，就是一次计费单元。多图输出、批量任务要分别确认是否按输出张数累计。
- 叠加失败与重试。真实调用中会有参数错误、超时、内容审核拒绝。如果这些失败请求也计入用量，你的实际成本会高于「成功张数 × 单价」，规划时预留冗余。
- 乘上业务用量。单用户日均生成张数 × 日活 × 计费单价，得到日成本；再乘 30 得到月度量级，用于和预算对齐。
哪些用量口径要额外确认
- 失败请求是否计费、如何计费。
- 同一张输入图做多轮迭代（用户反复微调）时，每一轮是否都算一张。
- 是否区分分辨率或尺寸档位，不同档位是否同一单价。
- 是否有并发或批量相关的口径差异。
把这四项在文档和价格面板里对清楚，再填进你的成本模型。养成一个习惯：任何「按张」「按秒」「按 token」的计价，都先问一句「计费单元到底怎么数」，这比记住某次报价更有用。
典型用法与请求组织方式
图生图在产品中的常见形态比较集中，理解这些形态有助于你设计请求结构。
常见产品功能
- 风格化：用户上传照片，选择预设风格（插画、胶片、水彩等），输出同构图的风格化结果。
- 商品图处理：电商场景下统一背景、统一光效，让不同来源的商品图在列表页看起来一致。
- 素材延展：以一张主视觉为参考，生成同一视觉语言的多个变体，用于投放素材测试。
- 草稿细化：设计或游戏场景里，把线稿、灰模作为输入，输出更完整的效果预览。
请求链路的组织建议
一条稳妥的调用链是：接收上传 → 校验与预处理 → 调用模型 → 后处理 → 落地存储。
- 预处理：统一尺寸、修正方向（EXIF）、压缩到接口允许的范围。把不合规的输入挡在调用之前，比让请求失败更省钱。
- 调用层：把提示词模板与风格参数收敛到服务端配置，不要让前端直接拼装，便于灰度与回滚。
- 后处理：统一裁剪、加水印、生成缩略图，这些都在调用返回之后做，不要塞进模型请求。
- 存储：输出若为临时 URL，立刻转存到你自己的对象存储，避免链接过期导致用户看到裂图。
upload -> validate -> preprocess -> call model -> postprocess -> store -> respond
\-> reject early (bad format/size)
重试只针对可判定的瞬时错误（超时、限流），参数错误与内容拒绝不要重试，直接反馈给用户并提示修改输入。这条规则能同时压住成本和体验问题。
效果验证与常见问题排查
「效果不稳定」是接入图生图后最常见的抱怨，但它通常不是模型的问题，而是缺少一套可定位的验证流程。
建立固定验证集
准备一组覆盖典型场景的输入图：正脸人像、复杂背景、低分辨率、极端长宽比、含文字的海报。每次调参或换版本，都用同一组图跑一遍，人工或半自动打分。没有固定验证集，你的「感觉变好了」无法复现。
出现不符预期时的排查顺序
- 先看输出是否真的被生成。是请求失败、内容拒绝，还是成功返回但结果不对——三类问题处理路径完全不同。
- 查输入图本身。尺寸是否被过度压缩、方向是否正确、主体是否太小。输入质量差，输出不可能好。
- 查提示词与参数。指令是否与「保留原图」的目标冲突（比如要求大改构图），风格强度是否设得过满。
- 对照验证集。换回之前可用的配置，确认是本次改动引入的回归。
- 最后才怀疑能力边界。如果场景本身要求逐像素精确编辑，那是把工具用错了地方。
记录与可观测性
为每次调用记录：输入图特征（尺寸、来源类型）、关键参数、耗时、是否成功、失败原因分类。这些数据在后期做成本优化和效果迭代时价值很高，别等出了问题才回头补日志。
成本与体验的平衡实践
输出分辨率、调用频次、失败重试，是三个彼此牵动的旋钮。
- 分辨率不要一味求高。预览阶段用较低档位快速出结果，用户确认后再出高清版本。这既能降低单次成本，又能让交互更跟手。
- 区分预览与成片。绝大多数点击发生在预览，只有少数用户会走到导出。把高成本操作限制在明确意图之后。
- 控制重试预算。给每个用户请求设最大重试次数，超时类错误指数退避，非瞬时错误不重试。没有上限的重试会让一次故障放大成账单事故。
- 回收无效调用。用户连续快速切换风格时，取消或合并尚未返回的请求，只保留最后一次的结果。
- 把用量可视化。按功能、按用户分层统计张数与失败率，及时发现异常调用模式。
平衡的判断标准不是「每张最便宜」，而是「一次成功交付的总成本最低」。为省一张图的钱让用户反复失败，最终成本反而更高。
上线前的检查清单
把以下条目当成上线前的逐项核对表，团队可以直接对照执行。
接口与工程
- 输入图的传递方式、格式与尺寸限制已确认，预处理逻辑已实现。
- 输出形态（URL 或二进制）已确认，转存与过期处理已就绪。
- 同步/异步模式、超时时间、轮询间隔已明确。
- 错误码分类完成，重试策略与最大重试次数已配置。
- 限流与排队策略已覆盖预期峰值的数倍。
- 鉴权凭据走服务端配置，未出现在客户端代码中。
成本
- 计费单元的定义已从价格面板核实，未凭猜测估算。
- 失败请求、多轮迭代、分辨率档位的计费口径已确认。
- 日成本与月度成本模型已建立，并预留了失败重试冗余。
- 预览/成片等不同档位的用量已分开统计。
效果与运营
- 固定验证集已建立，回归流程已写入发布规范。
- 内容审核与拒绝提示对用户友好，不暴露内部错误细节。
- 调用日志覆盖输入特征、参数、耗时与失败分类。
- 已向产品侧书面说明能力边界，避免不切实际的预期。
清单不追求一次全勾，但每一项都应有明确的责任人和确认结论。接入 seedream-5.0-lite/image-to-image 的难点往往不在调用本身，而在把输入、计费与预期对齐；把这份清单跑完，你的图生图功能就有了可持续迭代的基础。
