搜「商汤日日新API接入注意事项」的人,多半是拿到密钥、文档翻了两页就动手,结果第一个请求就返回看不懂的报错。这篇不铺概念,按实际动手顺序拆:接入前要跟谁确认什么、请求体里哪几格最容易填错、报错先看哪一层。每一步都给出判断标准,什么情况下这套做法不适用也一并说清。
搜这个问题的人,状态多半差不多:密钥拿到了,文档翻了两页,觉得不就是发个请求吗,结果第一个 POST 出去就回来一串看不懂的报错。然后开始在代码里到处试,改请求头、换模型名、加参数,越改越乱。这事儿麻烦在你不知道是哪一层出的问题——是账号没开权限,是协议抄错了版本,还是网络根本没通到对方。
这篇按实际动手的顺序来拆:动手前要跟谁确认什么、请求体里哪几格最容易填错、报错之后先看哪一层。每个环节给一个判断标准,也写清什么情况下这套做法不适用。不铺概念,都是能直接照着做的动作。
动手前先确认三件事,别急着写代码
很多人把「拿到密钥」当成「可以调用了」,这两件事中间还隔着一层。密钥只是身份,能用哪些模型是账号权限的事,两者对不上,请求会以权限类错误回来,而不是告诉你「模型不可用」。先到 /official-api/providers/sensenova 把接口路径和可选模型对一遍,比在代码里盲试省时间。
第二件事是确认你抄的是哪套协议口径。原生接口和 OpenAI 兼容层在路径、字段命名、多模态入参形态上并不一致,网上搜到的示例经常是混着来的。判断方法很简单:看你手头示例的请求路径和鉴权写法,跟当前文档能不能逐字对上,对不上就说明抄串了,别硬改。
第三件事是网络。公司内网经常卡在代理和证书这两步,表现出来却像代码错误。建议先在 /tools/speed-test 量一次延迟基线,把网络问题从代码问题里摘出去。如果 ping 都不通,后面所有排查都是白费。
请求体里最容易填错的几格
鉴权是第一个坑。头的位置和前缀要按当前文档写,Bearer 后面少个空格、或者把 Key 塞进 body 里,返回的都是鉴权失败,而不是参数错误——这两种错误的改法完全不同,一开始就分错方向很常见。
模型名建议原样复制,别自己简写、别随手加版本后缀。名字对不上时,回来的信息未必是「模型不存在」这么直白,可能是更笼统的参数错误,于是你又跑去查别的地方了。
多模态请求的坑更集中。图片和文本的拼装结构和纯文本差得远,正确顺序是先跑通纯文本,再单独加多模态,别一次性把两类参数混在一个请求里。实际用下来,混着调的时候报错信息几乎指不出是哪部分出的问题。
- 鉴权头
- 位置和前缀按文档写,别把 Key 放进 body
- 模型名
- 原样复制,不简写不加后缀
- 多模态结构
- 和纯文本不同,先单跑再合并
- 可选参数
- 流式、最大输出长度等不确定就先不带,跑通后逐项加
报错了按这个顺序查,别乱改代码
报错先分清是哪一层拒的,这一步不做,后面全是碰运气。鉴权类错误看 Key、账号权限和请求头;参数类错误看字段名、类型和嵌套层级;限流类错误看并发和调用节奏。三层对应三种改法,改错层等于没改。
- 缩小到最小请求拿一个模型名加一句短提示复跑,把业务代码里的变量全去掉。能通说明问题在参数拼装,不在接入本身。
- 日志记原样把出错时的请求体原样记进日志再动手改,否则改完分不清是修好了还是碰巧了。
- 限流看节奏别靠重试硬顶,按并发分档排队加退避更稳。具体档位去 /official-api 和站内价格页核对当时的数字。
| 报错类型 | 先看哪里 | 常见误判 |
|---|---|---|
| 鉴权失败 | Key、账号权限、请求头前缀 | 以为是模型名写错 |
| 参数错误 | 字段名、类型、嵌套层级 | 跑去换 Key 或换模型 |
| 限流 | 并发数与调用节奏 | 加大重试次数硬顶 |
| 网络超时 | 代理、证书、出网策略 | 在代码里反复改参数 |
这些做法在什么情况下不适用
如果团队已经把调用收口到自建网关或中转层,上面这些接入注意事项要前移到网关配置那一层,客户端侧只管 Base URL 和 Key,再在客户端抠请求头是抓错了地方。判断标准是看你的请求实际从哪台机器发出。
- 只做一次性验证:不必上完整的重试与日志体系,最小请求确认连通就够
- 延迟敏感的业务:参数调优要放到真实流量下做,本地空跑的结论不可靠
- 多人共用一个 Key 的团队:先定好谁负责轮换和权限变更,否则出问题查不到人
还有一个常被忽略的点:如果你还在选服务商阶段,别只盯着接入细节。中转站的可信度、计费口径这些要到 /price-watch 和站内检测页面看当时的数据,具体数字会变,判断标准比数字更耐放。
下一步把接口清单和模型权限先对一遍,再去量一次网络,能省掉大部分无效排查。→常见问题
密钥能调通一个模型,换另一个就报错,是 Key 的问题吗?
多数不是。密钥管的是身份,模型管的是权限和参数。先去 /official-api/providers/sensenova 核对你账号下开通了哪些模型,再看新模型的请求字段是否和老模型一致。同一个 Key 在不同模型上表现不同,基本是权限或参数形态的差异。
接入时要不要一上来就配重试和流式?
建议反着来。先用一条最小请求跑通非流式,确认鉴权、模型名、返回结构都对,再加流式,最后才加失败重试。顺序颠倒的话,出错时你分不清是流式解析写错了还是接入本身没通。
报错信息看不懂,最快怎么定位?
把请求砍到最小:一个模型名、一句提示、必要的鉴权头。能通就往回加参数,不通就查账号权限和网络。同时把状态码和响应体原样存下来,状态码能直接告诉你是鉴权、参数还是限流,比读报错文案快得多。