把中转站做成开发者体验良好的服务
技术上正确和用起来舒服是两件事。开发者体验的核心指标很简单:用户从决定尝试到发出第一个成功请求,需要多久。
把接入路径压缩到最短
文档首页就是一��能跑的 curl,Base URL、Key、模型、验证命令四件事。中间的细节往后放。
任何客户端接入,先把这三样固定下来:Base URL、模型 ID、Key。
最小请求的价值在于排除干扰:先用最短的 prompt、关闭流式、不带任何工具,把链路跑通。
错误提示要可执行
「请求失败」没有价值。「这个 Key 没有 gpt-6-sol 权限,你当前可用的模型是 A、B、C」才有价值。
模型 ID 不要从文档里抄,要用你的 Key 实际查一次 /v1/models 拿到真实可用的那个。
把它写成 https://aiminis.info/v1/chat/completions 是新手最常见的低级错误。
让用量和状态随时可查
用户最常问的两个问题是「我用了多少」和「现在能不能用」。这两个答案应该随时能自己拿到。
用户最常问的三个问题:我今天用了多少、我这个 Key 现在还剩多少、这笔是谁调的。
网关的用量查询页应该一次性回答这三个问题,而不是让用户提工单。
为常见客户端提供现成配置
把 Base URL、环境变量名、最小配置片段直接给出,让用户复制粘贴就能跑起来。
现在本地 Agent 客户端多起来了,手工在每个客户端里抄一遍 Base URL 和 Key 很快就会出错。
更省事的做法是做一个导入链接:浏览器点击后直接唤起客户端并预填配置。
实操:最小可用请求:一条普通的对话补全。
文档首页就应该放这一段,而不是先介绍公司的技术实力。
BASE="https://aiminis.info/v1"
KEY="sk-gw-你的密钥"
curl "$BASE/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-sol",
"messages": [{"role": "user", "content": "用一句话介绍你自己"}],
"stream": false
}'
几个容易踩的坑
- 把 API Key 硬编码在代码里然后提交到仓库。
- 每次失败都重试,包括参数错误、额度不足这类永远不会成功的错误。
- 没有对已经产生上游用量的请求做重放保护,账单翻倍。
- 模型 ID 从旧文档里抄,实际 Key 没有该模型权限。
小结
先跑通最小请求,再逐项加功能——这是接入任何网关都适用的节奏。
文中的配置和示例都能在 https://aiminis.info/ 直接跑一遍,接入文档在 https://aiminis.info/docs/api-integration。
- 点赞
- 收藏
- 关注作者
评论(0)