调通一个图像生成接口，卡住人的通常不是模型效果，而是请求体怎么写、返回结构怎么读、报错怎么定位。这篇就把万相 2.7 图像 API 接口的接入过程完整拆开。

万相 2.7 图像 API 接口属于典型的文生图类 HTTP 接口：客户端把提示词、尺寸、生成数量等参数放进请求体，服务端返回图片地址或二进制数据。结构看起来简单，但不同服务方在鉴权方式、参数命名、同步与异步模式上的差异并不小，直接照抄示例经常第一次就报错。下面按“准备—请求—返回—排错”的顺序展开，每一步都给出可核对的检查点，你可以对着自己的调用日志逐项比对。

一、接入前必须先确认的四项前提

在写第一行代码之前，把下面四件事确认清楚，能省掉后面大量无效调试。

• 鉴权方式：多数图像接口把 API Key 放在 Authorization 请求头里，格式通常是 Bearer YOUR_API_KEY；也有服务使用签名或 AccessKey 组合。以你所用服务方的文档说明为准。
• Base URL 与接口路径：要区分“控制台地址”“API 域名”和“具体接口路径”三件事，它们往往不同。少写一段路径、多写一个斜杠，都会直接返回 404。
• 模型标识：模型名称一般带版本号，必须与文档或控制台中列出的字符串完全一致。建议直接复制，不要凭印象手写。
• 调用模式：同步调用能直接拿到结果，适合交互式场景；异步任务需要先提交、再拿 task_id 轮询，适合批量生成。两者返回结构完全不同，不能混用解析逻辑。

如果你同时要调用多家厂商的图像模型，逐个维护域名、Key、参数风格和用量统计会很快变成负担。像 通联AI中转站 这类 AI 聚合平台提供的思路是：用一个 Base URL、一套 API Key 统一管理多家模型调用，在控制台里切换模型、查看调用记录。是否适合你的项目，可以先注册进去看模型广场里当前提供哪些图像能力，再决定要不要迁移。

二、请求参数怎么组织

请求头与基础配置

一个最小可用的图像生成请求，通常由三部分组成：请求地址、请求头、JSON 请求体。请求地址由服务方的 Base URL 加上接口路径拼成；请求头至少包含鉴权信息和内容类型；请求体承载全部业务参数。

POST {BASE_URL}/你所用服务方的图像接口路径 Authorization: Bearer YOUR_API_KEY Content-Type: application/json { "model": "控制台中显示的模型标识", "prompt": "一只坐在窗台的橘猫，清晨侧光，胶片质感", "size": "1024*1024", "n": 1 }

注意上面的字段只是结构示意：字段名、取值范围、是否必填，都要以你实际调用的服务方文档为准。特别是 size 这类参数，各家的写法可能是 1024*1024、1024x1024 或宽高分开传，写错了通常不会静默忽略，而是直接返回参数校验错误。

核心字段逐项对照

任何参数示例都只是结构示意。字段名、取值范围、是否必填，一律以你调用的服务方文档和实际返回的错误信息为准；跨服务方复制参数是最常见的踩坑来源。

三、返回结果解析：从 JSON 到可用图片

万相 2.7 图像 API 接口的返回体一般包含三块信息：状态、结果和用量。状态用来判断这次调用是否成功，结果里放着图片地址或图片数据，用量则和计费直接相关。解析代码要能同时处理成功与失败两种情况，而不是只写 happy path。

同步返回与异步任务的差别

同步返回通常长这样：顶层是请求标识，下面跟着输出对象，输出对象里包含状态字段和结果数组，结果数组中的每张图一般给一个可访问的 URL。异步任务则先返回一个任务 ID，你需要用这个 ID 去查询接口轮询，直到状态变为成功或失败。

{ "request_id": "……", "output": { "task_status": "SUCCEEDED", "results": [ { "url": "https://……/image.png" } ] }, "usage": { "image_count": 1 } }

实际写解析逻辑时要注意三点：第一，不同服务方可能用 output.results[0].url，也可能用 data[0].url，解析前先打印一次原始响应；第二，图片 URL 通常有有效期，正式业务应尽快转存到自己的对象存储；第三，务必记录 request_id，出现问题时它是排查的主要线索。

四、常见报错与排查顺序

按下面的顺序排查，比漫无目的地改代码效率高得多：

1. 401 / 403：先查 API Key 是否过期、是否被写进了请求头、是否存在多余空格。
2. 404：检查 Base URL 与接口路径的拼接是否正确，特别注意结尾斜杠。
3. 400 参数错误：逐项比对字段名与取值，重点看 size、n 和模型标识。
4. 429 / 限流：降低并发或在代码中加入退避重试，不要无间隔连续重试。
5. 任务一直处于处理中：确认轮询间隔是否过短、任务是否已超时，必要时查询任务详情接口。

当你在多个服务方之间切换时，报错格式也会跟着变，统一入口的价值就体现在这里：像 通联AI中转站 这类平台把多家模型的调用收敛到一套 OpenAI 兼容风格的接口上，Key、余额和调用记录集中在一个控制台里管理，切换模型主要改模型名称，不用重写整套请求逻辑。具体支持哪些协议与模型，仍以官网页面和控制台实时展示的信息为准。

五、上线前建议完成的三次测试

接口跑通一次不等于可以上线。建议至少完成三轮验证：用最短提示词验证连通性；用业务真实提示词验证出图质量和参数边界；用并发请求验证限流与超时处理。每一轮都记录耗时、返回状态和用量，方便后续估算成本。

另外提醒一句，图像生成类接口的计费方式通常与生成张数、分辨率相关，调试阶段把 n 固定为 1、尺寸降到较低档位，能有效避免调试成本失控。正式开始批量生成前，先去控制台核对一次计费规则和余额，比事后查账单要轻松得多。