2026 年万相 2.7 参考生 API 调用实操步骤：参考图上传与参数配置说明
2026 年万相 2.7 参考生 API 调用实操步骤：参考图上传与参数配置说明
做参考图生成时，最卡人的往往不是模型能力，而是参考图传不进去、参数对不上、返回结果和预期不一致。下面按可复核的顺序，把万相 2.7 参考生 API调用从准备到验证完整走一遍。
本文面向已经拿到 Key、准备接入图片生成能力的开发者与产品团队。文中出现的字段名、取值范围与限制条件，请以你所接入服务商的接口文档为准，因为不同网关对同一能力的参数命名可能并不一致，直接照搬别人的示例，往往就是报错的起点。
如果你手上还没有可用的调用入口，也可以先注册 通联AI中转站，在控制台里确认 Base URL、可用模型名称与调用格式，再回来对照本文完成第一次请求。
一、调用前先确认这四件事
万相 2.7 参考生 API调用本质上是“文本指令 + 参考图 + 一组约束参数”的组合请求。在写代码之前，先把下面四项确认清楚，能省掉大部分返工。
- 调用凭证：API Key 是否可用、余额是否充足、是否需要单独开通图片生成权限。
- 接口地址：Base URL 是根域名还是带路径前缀，是否按 OpenAI 兼容格式组织请求与响应。
- 模型名称：控制台里展示的可调用名称，通常与宣传页上的版本名并不完全相同。
- 参考图来源：图片通过公网 URL 引用、Base64 内联，还是先上传到对象存储再传链接。
这四项里最容易出错的是模型名称。宣传口径、控制台列表、网关映射后的名称，可能是三个不同的字符串。建议直接从模型列表复制，并在测试环境先跑通一次最小请求，再接入业务代码。
二、参考图上传的三种方式与选择建议
参考图是这类接口与普通文生图最大的区别。图片怎么给、给多大、给什么内容，直接决定调用是否能成功。
方式一：公网可访问的图片 URL
这是最省事的一种。服务器需要能直接拉取到这张图，因此链接不能带登录态，也不能使用已过期或即将过期的签名地址。测试阶段建议把图片放在自己的 CDN 或对象存储上，并把有效期设置得足够长。如果接口返回“图片下载失败”“无法读取参考图”，先检查这条链接能否在无痕窗口里直接打开。
方式二：Base64 内联进请求体
适合图片体积小、调用频次低的场景。好处是不依赖外部存储，缺点是编码后体积明显膨胀，请求体容易超过限制，日志里也不好看。拿它做联调可以，做批量生产要慎重。
方式三：先上传、再引用
生产环境更推荐的做法：先通过平台的上传接口或自己的对象存储拿到一个稳定地址，再把这个地址作为参考图字段传给生成接口。这样链路清晰，出问题也能分段排查——先确认图能拿到，再确认生成能跑通。
| 配置项 | 作用 | 检查方法 | 常见问题 |
|---|---|---|---|
| 参考图字段 | 告诉模型以哪张图作为主体参考 | 严格使用文档给出的字段名 | 写成 image_url 或 image 导致参数校验失败 |
| 图片格式与体积 | 决定图片能否被正常解析 | 用文档列出的格式与上限逐项核对 | 透明通道、超大分辨率被拒绝 |
| 尺寸与比例 | 决定成图构图与裁切方式 | 先固定一组取值做基线测试 | 比例与尺寸同时给出且互相矛盾 |
| 同步或异步 | 决定代码如何处理等待与轮询 | 看响应里是直接给图还是给任务 ID | 同步模式超时，异步模式未做重试 |
参考图不是“能给就行”。主体在画面中的占比、背景复杂度、清晰度都会影响结果。建议固定两到三张测试图建立基线，再逐个调整参数，否则很难判断变化来自图片还是来自参数。
三、参数配置：哪些必须写，哪些决定效果
必填与半必填项
模型名称、提示词、参考图通常属于必填；尺寸、比例、生成数量、随机种子等属于按需项。不要把“可选”理解成“随便”，很多可选参数在特定组合下会互相约束，例如比例和尺寸同时给出且相互矛盾时，接口可能只取其中之一，也可能直接返回参数错误。
影响画面结果的参数
提示词结构、尺寸与比例、生成数量、随机种子、是否添加水印，这几项对结果影响最直观。做批量生产时，建议把随机种子写入日志，配合固定提示词复现问题；做风格探索时则相反，固定种子、改变提示词，观察模型对指令的响应程度。无论哪种方式，都要保留一份当次请求的完整参数快照。
容易互相冲突的组合
常见冲突包括：同时传入多张参考图但未在提示词中说明主次关系；提示词要求横构图而尺寸参数给出竖版；生成数量设置在并发受限的账号上被限制。遇到这类问题，先做减法——只保留必填项跑通一次，再逐项加回参数，比一次性堆满参数更容易定位。
四、最小可用请求与返回处理
POST {BASE_URL}/v1/images/generations
Content-Type: application/json
Authorization: Bearer {API_KEY}
{
"model": "控制台显示的模型名称",
"prompt": "以参考图中的人物为主体，雨夜街道，冷色调，电影感光线",
"image": "https://your-cdn.example.com/reference.jpg",
"size": "1024x1024"
}上面只是结构示意，路径、字段名和取值都要以你所用服务商的文档为准。返回结果里通常会给出图片地址或 Base64 数据；如果任务耗时较长，也可能先返回一个任务 ID，需要再轮询查询。这两种模式的处理逻辑差别很大：同步模式要控制超时时间，异步模式要设计轮询间隔与失败重试上限，并且避免同一任务重复提交。
五、报错排查顺序
- 先看鉴权：Key 是否正确、是否带上了正确的请求头、余额是否充足。
- 再看模型名：是否与控制台展示的名称完全一致，包括大小写与版本后缀。
- 然后看参考图：链接能否直接访问、格式是否被支持、体积是否超限。
- 接着看参数：必填项是否齐全，互斥项是否被同时传入。
- 最后看网络与超时：是否需要加大超时时间，或改用异步任务模式。
按这个顺序排查，大部分问题都能在一两轮内定位。反过来，一上来就改提示词，通常只是在浪费时间。
六、把一次成功调用沉淀成可复用流程
当万相 2.7 参考生 API调用在本地跑通之后，下一步是把它变成团队可复用的能力：把 Key 放进环境变量或密钥管理服务，把参考图上传与生成拆成两个独立步骤，为请求加上日志与错误码记录，并为模型名、尺寸、比例维护一份配置清单。这样后续换模型或换版本时，改动范围是可控的。
如果团队同时要接多个图像或视频模型，逐个平台维护地址与 Key 会比较繁琐。这时可以考虑使用 通联AI中转站 这类 AI 聚合平台：用一个 Base URL 对接多家模型，在控制台统一管理 API Key、余额与可用模型。接入时先核对控制台给出的接口地址、模型名称与兼容协议，再逐步替换原有配置，不要一次性全量切换。
参考图上传和参数配置都调通之后，建议把测试环境固定下来：注册一个账号，拿到 API Key，确认 Base URL 与模型名称，再用同一张参考图跑一次完整请求，把成功参数记录下来。