Max Router 入门
选择模型、创建 API 密钥,并通过 Max Router 发起第一条请求。

选择模型和接口
打开模型广场,比较可用模型、支持的接口和当前价格。选择适合应用输入与输出的模型,并记下准确的模型 ID 和接口;不同模型和协议的能力可能不同。
刚接入时,最容易遇到的问题不是不会写代码,而是不知道失败发生在哪一层。先选一个支持对话接口的模型,让它回答一句简单问题。暂时不要同时加入图片、工具调用、流式输出和复杂系统提示词。把目标缩小之后,接口地址、密钥、模型名称和请求格式都更容易逐项检查。等基础请求稳定,再把业务需要的能力一项项加回去。
在模型广场查看模型的准确 ID、支持的接口和当前价格。模型展示名便于阅读,但代码通常需要准确的模型 ID;不要自行猜测连字符、斜杠或版本号。不同模型可能走不同接口:能处理文本的接口不一定适合图片或视频任务。以模型详情和文档列出的能力为准,并在切换模型后重新验证关键参数。
创建 API 密钥
登录后打开 API 密钥页面,为应用创建密钥,并将其保存在环境变量或密钥管理服务中。不要把真实密钥放进浏览器代码、公开仓库或截图。
为开发和生产分别创建凭据,便于控制使用范围和排查问题。服务端从环境变量或密钥管理服务读取密钥,再由自己的后端调用 API。前端页面、浏览器插件和公开代码都不是保密位置,即使变量名里包含 SECRET,打包进浏览器后仍可能被看到。截图或日志泄露密钥时,应先轮换并检查使用记录。
应用通过网关连接文本、图像与视频模型。发送请求
下面的示例使用聊天补全接口。请将 YOUR_MODEL_ID 替换为支持该接口的模型,并在环境中设置 MAX_ROUTER_API_KEY。图像和视频生成请使用模型文档中列出的对应接口。
curl https://maxrouterai.com/v1/chat/completions \
-H "Authorization: Bearer $MAX_ROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"Hello!"}]}'
检查结果
检查响应和错误信息,然后在控制台查看用量。先用小请求验证所需模型与参数,再参考文档接入流式输出或工具调用。
第一次请求失败怎么办
先核对模型 ID 和接口地址是否与模型广场一致。身份验证错误应检查密钥与权限;参数不受支持则需要修改请求。不要在公开求助信息中粘贴密钥,提供请求标识和脱敏后的错误通常更有帮助。
成功的 HTTP 响应也需要检查正文:应用真正需要的字段是否存在,输出是否符合预期,是否有结束状态。失败时先保留请求标识和脱敏后的错误信息。认证错误通常要检查密钥和权限,参数错误需要修改请求;限流或暂时性故障则要按接口规则决定是否等待重试。不要把所有错误都变成无限循环。
把一次调用拆成三段
当用户在页面里输入问题后,浏览器应该先把请求发送给你自己的服务端。服务端确认用户身份,检查输入是否符合产品规则,再使用保存在服务器上的密钥调用模型接口。收到响应后,只把用户需要的结果返回页面。这样即使有人查看浏览器网络请求,也不会因此拿到平台密钥。
排查时可以沿着同一条路径倒着找:页面有没有成功联系自己的服务端?服务端是否发出了请求?模型接口返回了状态码还是连接错误?如果第一段已经失败,反复更换模型并不会解决问题。为每次调用生成内部请求标识,并在允许的范围内记录状态和耗时,会比保存整段对话更有帮助。
开发阶段还可以先用命令行直接发送最小请求,再让服务端程序发送同样的请求。两者的模型 ID、请求地址、请求头和必要字段应当一致。如果命令行成功而程序失败,优先检查环境变量读取、运行环境和请求序列化;如果两者都失败,再核对账户状态和接口文档。
从结果里读出真正的问题
第一次看到成功状态时,不妨多看一步:返回的内容在哪里?应用有没有正确处理空内容、结束原因或模型拒绝?不同接口的响应结构可能不同,读取字段时应以实际使用的协议为准。不要把一个示例里的字段路径当作所有模型都通用的约定。
遇到认证错误,检查密钥是否属于当前环境、是否被停用,以及请求头格式是否正确;遇到参数错误,先删去非必需字段,保留最小请求,再逐项加回。对暂时性限流,按照响应和文档提示等待;对明显的输入错误,修改请求比重复提交更有效。
在分享问题时,保留请求时间、请求标识、模型 ID 和脱敏后的错误类型即可。密钥、完整用户输入、私人图片链接以及内部服务地址都不应出现在公开帖子里。如果怀疑凭据已经泄露,先停用或轮换,再查看相关用量,不能只依赖删除消息。
上线前做一轮小范围验证
把测试分成几组:正常短问题、较长输入、缺少必填字段、无效密钥,以及客户端主动取消。观察页面是否有清楚的加载、完成和失败状态;服务端是否设置了合理的等待时间;用户重复点击时是否会产生多次请求。测试环境应使用专门的凭据和不含真实客户信息的样本。
接下来选少量真实使用场景,先让团队试用,记录回答质量、响应时间和实际用量。遇到偶发错误时,保留足够的脱敏上下文以便复现,而不是马上把所有失败都设置成自动重试。上线范围可以逐步扩大,每次调整后比较错误率和使用成本。
最后把模型名称、接口、依赖版本和测试日期写进项目自己的运行记录。模型或客户端升级以后,用相同样本重新验证。这个小习惯能帮助你区分代码改动、配置变化和上游能力变化,也让下一位接手的人知道该从哪里开始。
如果测试结果与文档不一致,先记录具体模型、接口和输入条件,再检查近期的配置变化。可以把问题缩小到一条不含密钥的请求,向支持团队提供请求标识和发生时间。这样既保护用户信息,也能减少双方来回确认的次数。
下一步稳一点
小请求成功后,再用接近真实业务的输入检查结果是否满足需求。一次接入一项能力,把凭据留在服务器端,并在增加流量前查看用量。模型当前的限制和支持选项应以对应文档为准。
用一组接近真实业务、但不含真实敏感信息的样本试运行,记录质量、耗时、用量和错误。再测试密钥失效、网络中断以及用户取消操作,确保页面能给出明确反馈。确认结果后逐步增加流量,并持续查看控制台中的实际用量。价格、模型能力和速率限制可能变化,上线前和后续调整时都应重新核对。
把第一次成功请求使用的模型 ID、接口、非敏感参数和验证日期记下来。以后更换依赖或模型时,可以用同一份小样本比较变化。记录中不要保存密钥、用户输入或完整客户数据;需要团队协作时,分享可以复现问题的最小请求结构和脱敏错误,比转发整个生产日志更安全也更容易讨论。