拿到的 Key 不知道该往哪个字段放，Base URL 写成官网地址，模型名抄了文档里的展示名——这几个动作能让第一次调用直接失败。这篇不讲怎么调优，只把从密钥到首个成功响应这段路拆开：每一步填什么、在哪核数字、报错先看哪一行。跑通之后再谈别的。
拿到 Key 却不知道往哪个字段放，把官网首页当成接口地址填进 Base URL，模型名照着产品页的中文名直接抄——这三件事干下来，第一次调用基本必挂。这篇不讲怎么调优、怎么省钱，只负责把从密钥到第一个成功响应这条路铺平：每一步填什么、去哪儿核数字、报错了先看哪一行。跑通之后想折腾别的再说。
整个过程其实就四段路：密钥和端点配对、发一个最短请求、模型名和参数别抖机灵、报错时按顺序排查。中间任何一步图省事，后面都会用更绕的方式还回来。下面按这个顺序拆。
密钥和端点，两个格子别填反
很多人第一反应是把 Key 拼进 URL 或者复制粘贴到请求体的 prompt 里，这属于经典误操作。鉴权用的 Key 一般放在请求头的鉴权字段，字段名和前缀写法得严格按文档来，少个空格、少个前缀都可能直接被判成鉴权失败，而且报错信息往往不会告诉你「你放错位置了」，只说没权限，很容易让人怀疑 Key 本身是坏的。
Base URL 也是同理。控制台网页地址和接口调用基址长得像，但完全是两码事，填网页地址过去通常连 404 都算客气，有时直接超时。协议前缀和版本段都得留着，抄的时候整段复制，别手敲——敲错一个字母排查起来能耗掉半天。
- Key 放请求头鉴权字段，不要塞进 URL 参数或请求体
- Base URL 用调用基址，不是控制台页面地址，整段复制别手打
- 端点路径、模型 ID 和当前可用档位，到 /official-api/providers/sensenova 核一遍再填，别凭记忆试
- Key 别写死在代码里，先放进环境变量，后面换环境少改一处
第一个请求别写业务逻辑，先要一句回话
第一次调用最忌讳上来就把业务逻辑、提示词模板、多轮拼接全堆进去。目标只有一个：让接口回一句话，确认链路通了。所以输入能多短就多短，非流式，只看三件事——状态码是不是 200、响应体里有没有能读的 content、这次请求大概花了多久。三样都正常，链路就算通了。
第一次别开流式。流式把连接层的问题和解析层的问题搅在一起，一旦没输出，你分不清是请求没发出去、服务端没回、还是你解析 SSE 的代码写错了。非流式一次请求一个完整响应，错了就是错了，好定位。
- 搭最小请求用 curl 或十几行的脚本，一个固定输入、一个模型字段，别的参数先不传或给默认值
- 发出去看状态码200 就往下；401、403 回头查 Key 和请求头字段名；400 查请求体 JSON 结构；5xx 先重试一次
- 读响应体找 content 字段有没有实际文本，没有的话看响应里的错误信息指向哪个字段
- 存档做基线把这次能跑通的 curl 或脚本存成文件，后面改参数都拿它做对照，不要每次重写
这份能跑通的脚本别删。后面调温度、换模型、加多轮，出问题时把它拿出来跑一遍，能立刻判断是参数改坏了还是环境变了。这事儿麻烦在很多人跑通就丢，第二次出问题又从头来。
模型名和参数是最常见的翻车点
模型字段要填接口认的标识，不是产品页上的中文名，也不是带斜杠的完整路径。填错一般报模型不存在或参数不合法，两种报错指向的其实是同一件事：你填的东西接口不认识。碰上这种，别急着怀疑 Key，先去核模型 ID。
温度、最大输出长度这类参数，第一次先用保守值。上来就拉极端值，校验错误会盖掉真正的问题——你以为是参数调崩了，其实是模型名就填错了。另外同一个 Key 在不同端点上的权限可能不一样，鉴权通过但调用被拒，先确认这个 Key 有没有开对应模型的权限，而不是反复改代码。
| 现象 | 大概率原因 | 先查哪里 |
|---|---|---|
| 鉴权失败 | Key 放错位置或请求头字段名不对 | 请求头鉴权字段和前缀写法 |
| 模型不存在 / 参数不合法 | 模型 ID 填了展示名或完整路径 | 到 /official-api/providers/sensenova 核模型标识 |
| 鉴权通过但调用被拒 | Key 没开对应模型权限 | 控制台里这个 Key 的权限范围 |
| 400 类错误 | 请求体 JSON 结构或字段类型不对 | 对照文档的请求体示例逐字段看 |
报错按这个顺序看，别一上来就改代码
报错第一反应改代码，往往越改越乱。按状态码、响应体、网络这个顺序看，能少走很多冤枉路。状态码先把大类分出来：鉴权类回头查 Key 和请求头字段名，参数类查 JSON 结构和字段类型，服务端错误先重试一次再说，别立刻怀疑自己写错了。
状态码之后看响应体里的错误信息，它通常比状态码具体，能指出是哪个字段不合法、哪个值不认识。最后才怀疑网络和代理。本机直连能通就说明不是链路问题，别在代码里加一堆重试和超时把真正的原因盖住。
- 先看状态码定大类，别跳过直接读代码
- 再看响应体错误信息，定位到具体字段
- 本机直连能通就排除链路问题
- 需要延迟基线做对比时，到 /tools/speed-test 量一下
- 改完只改一处，改完立刻用存档脚本复跑验证
判断标准就一条：每次只改一个变量，改完立刻用那份存档脚本复跑。一次改三处，跑通了也不知道是哪处起了作用，跑不通更不知道哪处坏了。这套顺序不适用于你已经在跑生产环境的场景——线上出问题优先止损和回滚，排查顺序是事后的活。
下一步链路跑通后，模型当前可用档位和端点细节会变，别拿记忆里的名字长期用，到 /official-api/providers/sensenova 核当时的模型标识和端点；想对比链路延迟基线，用 /tools/speed-test 量一次存档。→常见问题
商汤日日新 API 的 Key 申请下来后多久能用？
一般拿到就能用，但如果刚开通就去调，可能碰上权限还没同步。先拿最小请求试一次，返回鉴权失败先别改代码，等一会儿再试；持续失败就去控制台确认这个 Key 的模型权限有没有勾上。
为什么我填了正确的 Key 还是报鉴权错误？
多数是位置放错：Key 要放在请求头的鉴权字段，不是 URL 参数也不是请求体。还有一种情况是复制时带了空格或换行。把请求头原样打印出来看一眼，比反复换 Key 快。
第一次调用返回模型不存在，是模型下线了吗？
先别下这个结论。多数时候是模型字段填了展示名或者拼错了。到 /official-api/providers/sensenova 对照接口认的标识，再检查是不是在请求里多加了前缀。
