很多人拿到商汤日日新的 Key 之后卡住：接口地址不确定、模型名怎么写不确定、SDK 和裸 HTTP 之间不知道挑哪个，第一次调用失败了也分不清是鉴权问题还是参数问题。这篇按「拿密钥 → 配环境 → 发首个请求 → 按场景选模型」的顺序走一遍，每一步给出可对照的检查点和失败时的排查方向。
很多人拿到商汤日日新的 API Key 之后会卡在同一步：接口地址记不清、模型名不知道怎么填、手上只有一份官方文档却不知道从哪下手。更麻烦的是第一次调用返回报错，分不清是密钥填错、模型名写错，还是额度或者并发被限住了，只能一份份文档来回翻。
这篇按「拿密钥 → 配环境 → 发首个请求 → 失败排查 → 选模型和接入路径」的顺序走一遍。每一步给出对照检查点和失败时的排查方向，写完你至少能跑通一次最小调用，并且知道后面扩容或者换接入方式时该看哪些指标。
第一步：密钥与环境准备
先把密钥这件事弄干净。确认你从控制台拿到的是项目级的 API Key，而不是登录账号和密码，这两者在很多平台里是两套东西，用账号去调接口必然鉴权失败。拿到之后不要直接写进代码仓库，本地放在 .env 文件里，线上交给平台的密钥管理服务，代码里只读环境变量。
- Key 放进环境变量，变量名带平台前缀（比如 SENSETIME_API_KEY），以后接入别的平台不会串号
- 顺手记下控制台里已经开通了哪些模型，以及账号当前的调用额度和并发口径
- 把控制台的模型列表页存个书签，模型名要从这里复制，不能凭记忆写简称
- 团队多人开发时约定同一个变量名，避免有人用 A 名字有人用 B 名字，联调时互相覆盖
额度和并发这两个数字后面选模型、做压测都要用到。具体是多少，以你账号控制台当页显示为准，也可以到 /price-watch 对照站内追踪的额度与价格变化记录，看当时的数字。别拿别家平台的经验值往这里套。
第二步：跑通第一个请求
第一次调用不要直接上 SDK，先用裸 HTTP 发一个最小请求：参数只留模型名和一条很短的消息，别的都删掉。变量越少，出错时越容易定位。跑通之后再换成 SDK，把这次成功返回的响应体存一份，后面所有对比都以它为准。
export SENSETIME_API_KEY="你的密钥"；curl -X POST "接口地址" -H "Authorization: Bearer $SENSETIME_API_KEY" -H "Content-Type: application/json" -d '{"model":"从控制台复制的模型名","messages":[{"role":"user","content":"你好"}]}'模型名一定从控制台复制，不要凭印象写简写或者猜命名规则。模型名写错时返回的通常是「模型不存在」或者「无效的模型」这一类报错，和「密钥无效」是完全不同的两种文案，先看清再动手。接口地址同样以官方文档当前给出的为准，不同接入方式（直连、SDK、转发）地址可能不一样。
第三步：首个调用失败怎么查
调用失败别急着改代码，按固定顺序排查一遍能省很多时间。顺序是：网络能不能通 → 密钥是否有效 → 模型名和参数是否合法 → 额度和并发是否超限。前一步通了再走下一步，不要四件事一起猜。
| 现象 | 先查什么 | 常见原因 |
|---|---|---|
| 连不上、超时 | 网络和接口地址 | 地址写错、代理没配、本地网络到不了 |
| 返回鉴权失败 | 密钥本身 | Key 复制时带了空格、用了账号密码、Key 已失效 |
| 返回参数或模型错误 | 模型名和请求体 | 模型名不是控制台里的全称、多传了不支持的字段 |
| 报限额、限流 | 额度与并发口径 | 账号额度用尽、短时间请求太密 |
| 能通但很慢 | 延迟基线 | 网络链路问题，不是代码问题 |
「接口慢」和「接口不通」是两码事，排查方式也不一样。先用站内的测速工具量一次端到端延迟，得到基线值，再决定是查网络还是查代码。工具入口在 /tools/speed-test，测的时候把官方直连和你当前用的路径分别跑一遍做对比。
如果排查下来发现不是自己代码的问题，而是接入路径本身不稳定，那就涉及换路径的判断了。换之前建议先看 /sites 里各条路径的可信度检测记录，别在故障当下临时找替代方案。
第四步：选模型和选接入路径
模型不要用一个硬扛全部场景。先定任务再挑模型：通用对话看响应稳定性和上下文长度，长文档理解看单次能吃进多少内容，多模态理解看图片和文本能不能一起传，代码生成看它对代码语法的处理。任务定下来之后，去控制台的模型说明页对一遍能力描述，再去 /rankings 看当时的对比数据，别记死数字，看当下的就行。
接入路径分三档，各有各的代价，选之前先想清楚你愿意自己扛哪一块。
- 官方直连
- 最稳，字段和文档一一对应，但结算、限流、网络都要自己处理
- SDK 封装
- 接起来快，但要确认 SDK 版本和当前接口是否对得上，出问题时多一层要查
- 经中转站转发
- 省掉结算和部分网络问题，但多一层中间环节，稳定性和可信度要单独验证
中转站不是不能用，而是要先验。判断标准有三条：能不能给出稳定的响应结构、故障时有没有明确的处理说明、计费和额度口径是否透明。具体到每一家，去 /sites 看检测记录和用户反馈汇总，别只看宣传页。
- 业务对数据流向有硬约束的，中转方案要先过合规评估，不能只看便利性
- 调用量大、对延迟敏感的场景，优先直连，把中间层减到最少
- 只做内部工具、调用频率低的，中转站省事，但也要留一条直连兜底
- 多模态或者长文档类任务，先确认所选路径对请求体大小有没有额外限制
什么情况下这套判断不适用：如果你的业务量小到一个月只调几百次，路径选择其实不重要，跑通就行，别在最开始花太多时间比价；如果业务正在快速增长，那第一版就别绑死在某一条路径上，把调用层做成可切换的，后面换起来才不疼。
下一步去价格追踪页对一遍各家当前的价格和额度口径，再回到站点列表页看你准备用的那条路径最近有没有异常记录，两件事都看完再定方案。→常见问题
商汤日日新的 Key 申请下来后，第一个请求老失败是怎么回事？
多数是模型名写错或密钥没开通对应模型，这两种报错文案不一样，先看错误码再判断。其次是环境变量没加载、请求头字段没带全。建议先用最小参数裸 HTTP 请求打通一次，再换成 SDK 和框架，中间少一层封装的干扰，定位会快很多。
官方直连和中转站接入，该选哪个？
看团队更怕哪类问题：怕网络抖动和结算麻烦就选中转，怕链路不透明和数据出口不合规就选官方直连。中转站不是不能用，但接入前先在站内做个在线检测，确认它确实在转发你要的模型，并且价格口径对得上，再写进生产配置。
首个调用跑通之后，正式上生产还要补什么？
至少补三样：密钥不落代码库、超时与重试有明确上限、日志里记下每次请求的模型名与耗时。另外把并发口径摸清楚，先在测试环境压一次，别等线上被限流了才回头查是否踩到并发上限。
