2026年 JSON 格式大模型 API 教程：字段格式报错排查与常见避坑清单
2026年 JSON 格式大模型 API 教程：字段格式报错排查与常见避坑清单
大模型 API 的报错里，JSON 字段问题占了相当大一部分，而且提示往往含糊，让人不知道该改哪里。
先给一个结论：绝大多数“字段格式报错”并不是模型不接受你的请求，而是请求体没有满足接口约定的结构——字段名写错、类型不对、嵌套层级不对，或者 JSON 本身就不合法。下面按排查顺序讲清楚。
一、先分清三类 JSON 相关报错
同样是 400，原因可能完全不同。把报错先归类，能省掉大量试错时间。
1. JSON 本身不合法
表现是解析阶段就失败，典型原因包括：末尾多了逗号、用了单引号、中文引号混入、字符串里出现未转义的换行或双引号、数值写成 NaN 或带单位。这类问题用代码里的序列化函数生成请求体通常可以规避，手写字符串最容易出错。
2. 结构合法但字段不符合约定
表现是服务端解析成功，但提示未知字段、缺少必需字段或字段类型错误。常见情况有：messages 写成了字符串而不是数组；role 用了非标准取值；把 max_tokens 写成字符串；把整段上下文塞进单个 content 却没有做任何分隔。
3. 语义冲突
表现是单个字段都合法，组合起来不成立。例如同时指定了两套互斥参数；开启流式输出后仍期待一次性返回完整结构；要求模型输出 JSON，但提示词里没有明确约束输出字段。这类问题通常不会报语法错误，而是返回不符合预期的结果，更容易被忽略。
二、请求体字段逐项对照
下面这张表把最常出问题的字段集中列出来，排查时可以一行一行对。
| 字段 | 作用 | 常见写法错误 | 检查方法 |
|---|---|---|---|
model | 指定调用的模型 | 使用了别名、大小写不一致或控制台里并不存在的名称 | 以控制台与文档给出的模型名称为准，逐个复制 |
messages | 承载对话上下文 | 写成字符串、缺少 role、最后一轮不是用户消息 | 检查是否为数组，每项都含 role 与 content |
role | 标识消息来源 | 使用了非标准取值或中文角色名 | 统一使用 system / user / assistant |
content | 消息正文 | 多模态场景仍直接传字符串而非结构化数组 | 纯文本用字符串，带图时按文档格式传数组 |
stream | 控制流式输出 | 传了字符串取值而非布尔值 | 用布尔值，并在客户端正确处理增量片段 |
max_tokens | 限制输出长度 | 传了字符串、超出上限、与上下文长度冲突 | 参考文档上限，先用小值验证再放大 |
| 结构化输出参数 | 要求返回 JSON | 只设参数，未在提示中约束字段 | 在提示里给出字段名、类型与示例 |
三、一个可用的最小请求体
排查字段问题时，先把请求体缩到最小。下面这个结构足够验证连通性和字段格式，其他参数等跑通后再逐项加回来。
{
"model": "以控制台显示的模型名称为准",
"messages": [
{"role": "system", "content": "你是一个严谨的技术助手"},
{"role": "user", "content": "请用一句话说明这个接口的用途"}
],
"stream": false
}如果这个请求体在本地用 curl 能通，但代码里报错，问题通常出在序列化环节：请求头没有声明 Content-Type: application/json，或者请求体被额外包了一层。可以先打印最终发出的原始字符串，与上面这段逐字符对比。
四、按顺序排查的六个步骤
- 打印实际发出的请求体原文，不要只看对象本身。
- 用 JSON 校验工具确认它是合法 JSON。
- 把请求体缩到最小结构，确认能返回 200。
- 每次只加回一个字段，加一个测一次。
- 对照文档检查字段名、类型和取值范围。
- 把每条报错信息与对应原因记录成对照表，方便团队复用。
字段类报错最忌讳“一次改三处”。同时改字段名、类型和嵌套结构，即使调通了，你也不知道是哪一处起了作用，下次还会踩同一个坑。
五、接入前的准备：Base URL、Key 与模型名称
字段写对之后，还要确认三个基础配置。它们和 JSON 本身无关，但报错信息经常混在一起，导致排查方向跑偏。
- Base URL：结尾是否带
/v1，拼接后路径是否与文档一致。少一个斜杠或多一个/v1都可能返回 404。 - API Key：是否放在正确位置，格式是否为
Authorization: Bearer xxx，前后有没有多余空格或换行。 - 模型名称：区分大小写，也要区分同一模型的不同版本后缀。名称以控制台当前展示的为准，不要照抄旧文档。
如果你希望在同一个入口里对比多个模型的字段支持差异，可以用通联AI中转站（通联AI中转站官网）提供的统一接口做测试：一套 Base URL 加统一格式的请求体，逐个替换 model 字段，就能比较不同模型对同一结构的响应差异。实际可用的模型名称、鉴权方式和参数支持范围，请以控制台和文档页面显示的信息为准。
对于需要长期维护的项目，建议把模型名称、Base URL 和 Key 都放进配置文件，而不是散落在业务代码里。这样换模型时只需要改一处，也能避免“本地能跑、线上报错”这类环境不一致问题。想直接看当前可用的模型和接入说明，可以访问 通联AI中转站 的控制台与文档页面。
字段报错排查完之后，下一步是拿真实模型跑一次完整链路。先确认 Base URL、API Key 与模型名称，再用最小请求体验证一次结构是否正确。