调用万相 3.0 时，报错往往只给一个状态码，真正的原因却藏在密钥、接口地址、参数结构或返回体解析里。按层定位，比反复改参数快得多。

这篇排查清单把常见的万相 3.0 API调用报错拆成五层：鉴权层、地址层、参数层、额度与模型层、输出解析层。每一层给出可以立刻执行的核对动作，最后附一份能直接照着跑的检查表。需要提前说明的是，具体字段名、取值区间、任务模式与计费规则，请以官方文档和控制台当前展示的信息为准，本文讲的是排查思路，不能替代接口规范本身。

一、先判断报错发生在哪一层

很多人一看到请求失败，第一反应是去调参数：换尺寸、换提示词、换重试次数。但真实情况是，参数错误引起的失败只占其中一部分，更多的报错来自请求根本没被正确识别。先分层，再动手，能省掉大量试错。

判断顺序建议从下往上倒着来：先看请求是否真的发出去了，再看服务端是否认可这次身份，接着看参数是否符合接口要求，最后才怀疑模型可用性和返回体解析。绝大多数“调了半天没用”的情况，卡在前两层。

二、密钥与接口地址：多数 401 和 404 出在这里

1. API Key 的三种典型错误传法

第一种是漏掉前缀。多数兼容接口要求请求头形如 Authorization: Bearer sk-xxxx，只写 Key 本身会被判为身份无效。第二种是 Key 值被污染：从文档或控制台复制时带上了首尾空格、换行，或者被引号包住写进了配置文件。第三种是环境变量串号，本地测试正常、部署到服务器后读到了另一套环境变量。

排查方法很朴素：在代码里临时打印 len(api_key) 和 Key 的前六位，确认长度与来源符合预期，同时确认请求头字段名是大写 Authorization 还是接口文档要求的其他写法。如果项目里同时配置了多个平台的 Key，建议用独立变量名区分，不要复用同一个 API_KEY。

2. Base URL 拼接：404 的高发区

SDK 或封装库通常会自动补全路径，如果 Base URL 里已经带了版本段，而调用时又拼了一次，就会出现重复路径；反过来，Base URL 只写到域名，缺少版本段，就会返回 404 或 405。正确做法是：先查控制台或文档给出的 Base URL 原文，再把客户端里所有相关配置项统一改成同一个值，然后只保留一处路径拼接逻辑。

如果你是通过统一的聚合入口调用多家模型，比如在通联AI中转站这类平台管理多个模型，同样建议先确认控制台展示的 Base URL、模型名称与兼容协议，再逐项替换配置，而不是直接把旧项目的地址整段搬过来。

固定一套排查顺序会省很多时间：先确认请求发出去了，再确认服务端认不认这个身份，接着核对参数是否合法，最后才怀疑模型与额度。跳过前三步直接调参，多数时间都是白费。

三、参数与任务模式：图像生成类接口最容易踩的坑

万相 3.0 属于生成类能力，很多同类接口采用异步任务模式：提交请求后先返回一个任务标识，再通过查询接口轮询结果，而不是一次性把成品直接返回。如果客户端把它当成同步接口处理，就会拿到一个“字段不全”的响应，然后报各种取值为空的错误。

• 字段名与类型：同一含义的参数在不同接口里可能叫法不同，务必以当前文档为准，不要凭记忆写。
• 取值范围：尺寸、比例、时长、数量这类参数通常有明确区间和枚举值，超出范围会直接返回参数校验失败。
• 必填与选填：提示词、参考图、风格类参数哪些必填，各接口要求不一致，漏填会表现为“请求格式正确但任务被拒”。
• 任务轮询：轮询要有间隔上限和超时上限，无节制地高频查询容易被限流，报错反而更难定位。
• 内容合规：输入内容触发审核时返回的提示往往比较简短，需要结合文档中的错误码说明判断，而不是当成程序 Bug 反复重试。

流式输出报错：先分清接口到底返回什么

“流式输出报错”大致分两类。第一类是解析方式不匹配：接口返回的是普通 JSON，客户端却按 data: 逐行读取，于是拿到一堆前缀和空行，抛出 JSON 解析异常；反过来，接口按流式返回，客户端却用一次性 response.json() 解析，就会报 unexpected token 或者解析到空对象。判断方法很简单：把原始响应体完整打印一次，看清它是分块返回还是整体返回，再写解析代码。

第二类是传输中断：网关或反向代理对响应做了缓冲，导致流式内容迟迟不下发，最终触发读取超时；或者连接空闲时间超过服务端限制被断开，表现为“前面正常、中间突然断掉”。这类问题通常需要检查代理层的缓冲开关、读取超时和空闲超时设置，同时在客户端做好分块累积与断点重试，不要把半截响应直接丢给下游解析。

四、一份可复用的排查清单

1. 用一个最小可运行请求替代完整业务代码，排除业务逻辑干扰。
2. 打印请求方法、完整 URL、请求头字段名（不打印 Key 明文）、请求体结构。
3. 确认 Key 来源唯一，环境变量没有被其他配置覆盖。
4. 确认 Base URL 与端点路径只拼接一次，且均来自控制台或文档原文。
5. 确认模型名称与控制台显示完全一致，包括大小写与版本后缀。
6. 确认账户余额、并发额度与调用频率限制没有触顶。
7. 先打印原始返回体，再决定用流式还是非流式方式解析。
8. 确认异步任务的轮询间隔与超时设置合理，并处理好中间状态。
9. 把报错信息、请求时间、模型名称记录下来，便于对照文档中的错误码说明定位。

五、多模型场景下，如何降低排查成本

当一个项目需要同时调用对话、图像、视频、语音等不同能力时，报错来源会成倍增加：每个平台有各自的鉴权方式、参数命名和返回结构，排查时很难判断问题出在网络、密钥还是模型本身。这也是不少团队选择统一接入方式的原因——把多个模型收敛到一套接口规范和一份 Key 管理体系里，出问题时只需要检查一处配置。

通联的定位正是这类 AI 聚合平台：通过统一入口对接多家厂商的多种模型能力，提供模型查看、API Key 与余额管理、调用配置管理等功能，便于按任务选择不同能力、减少多平台切换。具体开放了哪些模型、支持哪些兼容协议、如何计费，建议直接到通联AI中转站的控制台和文档页面查看实时信息，再决定是否把现有调用迁移过来。迁移时依然建议保持“先验证最小请求、再逐项替换配置”的节奏，而不是一次性整体切换。

回到最初的问题：万相 3.0 API调用报错并不可怕，可怕的是没有顺序地乱试。把报错按层归类，把配置收敛到一处，把原始返回体看清楚，大部分问题都能在十几分钟内定位到具体环节。