换模型平台之前，这份迁移检查清单先过一遍
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
换平台真正的风险不在于「改完跑不起来」，而在于「改完跑起来了，但有几件事悄悄变了」。 改 base_url 和 api_key 这一步各家文档都写得很清楚，智谱的迁移文档原话是把 api_key 和 base_url 换掉就能用，阶跃星辰的迁移页给的也是同样两步，Gemini 官方在 OpenAI 兼容页上写的是「只需改三行」——api_key、base_url、model。问题是这三行改完之后，缓存还命不命中、限流按什么维度算、思考 token 算不算钱、旧模型名会不会被重定向到另一个模型，全都没人提醒你。这份清单就是按这条真实的操作顺序排的：先确认接入形态，再确认 Key 的归属，然后是模型名、思考参数、缓存、限流、错误处理，最后才是切流量。每一项都在各家官方文档里能找到明确出处，不是经验之谈。
第一件事：确认你换的是端点，还是整套调用形态
「兼容 OpenAI」这句话在不同平台的兼容深度是不一样的，别把它当成一个布尔值。
阶跃星辰的迁移页把与 OpenAI 兼容的接口逐条列了出来：Chat Completion、上传文件、获取文件列表、获取文件信息、获取文件内容、删除文件、获取模型列表、查询单个模型信息、生成图片。列表之外的能力就不在这个兼容清单里，需要按平台自己的接口文档走。智谱的说法是后端兼容了 OpenAI 的所有 Endpoint，但同一页也挂了提示，说某些场景下仍存在差异；智谱还另外说明了一件事：部分功能需要通过官方 SDK 调用，装 zhipuai 包才能用。
再往上一层，是 Anthropic 形态的兼容。智谱提供了 Claude API 兼容，base_url 走的是 https://open.bigmodel.cn/api/anthropic，官方 cURL 示例里的鉴权头是 x-api-key，不是 OpenAI 那套 Authorization: Bearer。MiniMax 在接口概览页把 Anthropic SDK 标成推荐接入方式，OpenAI SDK 并列作为另一个选项。Gemini 的原生 REST 鉴权头是 x-goog-api-key，而它 OpenAI 兼容层的鉴权头才是 Authorization: Bearer。
所以第一项检查是：你的代码到底是通过哪一层进去的？如果只是把一个 OpenAI 客户端指向新域名，那你拿到的是这家的 OpenAI 兼容子集；如果你的应用本身是 Anthropic 形态（比如围绕 Claude Code 那类宿主搭的），要找的是这家的 Anthropic 兼容入口，两条路的鉴权头和 base_url 都不一样。Gemini 官方还给了一条反向建议：如果你本来就没在用 OpenAI 库，官方推荐直接调 Gemini 原生 API，而不是绕兼容层。
第二件事：确认 API Key 到底属于哪个「域」
这一项排第二，是因为它踩中的时候拿到的信息特别少——Kimi 文档里给的返回就是一个干巴巴的 401，除此之外没有更多线索告诉你 Key 错在哪。
Kimi 的错误码文档专门为此写了一段平台隔离说明：platform.kimi.com（中国站）与 platform.kimi.ai（国际站）的账户、余额和 API Key 完全独立，混用会返回 401，要确认调用端点与 Key 所属平台一致。MiniMax 的文档里也出现了两个域：国内用户用 https://api.minimaxi.com/v1，国际用户用 https://api.minimax.io/v1。
同一家平台内部也可能有多套 Key。MiniMax 接口概览页写得很明白：按量付费的 API Key 在接口密钥页创建，Token Plan 的订阅 Key 在订阅管理页查看，两者相互独立，订阅 Key 用于订阅套餐和已购积分。也就是说你手上有两把钥匙，插错锁不是余额不足的问题，是身份不对。
Gemini 这边的结构又不一样：API 密钥没有独立的结算设置，它继承所属项目的层级与结算状态，一个项目内所有密钥的用量合并计入。更值得记的是，官方说层级、限流、账号上限都在结算账号级别确定，而不是项目级别；项目从一个结算账号换到另一个，层级和限流会跟着新结算账号变。
Key 该怎么存、怎么轮换、怎么在多环境之间隔离是另一个话题，这里只强调一句：迁移期你手上会同时存在新旧两套 Key，最容易出的事是测试环境用了新 Key、某个定时任务还在用旧 Key，然后你以为已经切完了。
第三件事：把模型名当成一个会消失的东西
模型名看上去只是请求体里的一个字符串，但各家对「旧模型名到期之后怎么办」的处理方式并不一样，而且差别很大。
阶跃星辰在模型迁移页直接列了一张下线模型与推荐替代模型的对照表，明确说下线后将停止推理服务，继续调用该模型的业务将无法正常返回结果，迁移方式就是把请求中的 model 字段替换成推荐替代模型的 ID。这种做法是「硬下线」：到点就断，报错清晰，反而好处理。
xAI 的做法是另一个极端，也是这一项里更需要盯住的一种机制。它的模型退役公告写明：退役之后，指向旧模型 slug 的请求会自动重定向到新模型，slug 本身继续可以解析，所以你不需要改代码就不会中断；但同一页也提醒，新模型的定价与它所替代的那些模型不同，如果继续往已弃用的 slug 发请求，会按新模型的价格计费。文档还说明了重定向的档位规则：原先的推理类模型会被路由到新模型的 low 推理档，非推理类模型会被路由到 none 档，另有一个图像类 slug 被指向对应的替代型号。官方给的建议是在退役时点之前显式选好每个负载对应的替代模型，这样你自己控制付的是哪一档推理的钱，而不是接受重定向套上来的默认档。
要提醒一句的是，这份公告里写的生效时点已经在本篇发布之前了，所以对今天的读者来说，这条不是「提前准备」而是「回头核账」：如果你的代码里还留着那批旧 slug，按公告写的机制，这些请求已经在被重定向，实际服务你的模型和推理档位都不是配置里写的那个。核的办法也很直接——把代码和配置里出现过的模型名全部翻一遍，对照官方那张退役对照表看有没有落在里面，再去账单里看这些调用现在归到了哪个模型名下。
这就是「不报错的破坏」：监控里没有 5xx，没有 429，日志一切正常，只有账单和输出质量在变。Gemini 的弃用机制则是宣布弃用、随后停用、端点最终完全不可用这样一条链路，官方会提前通知确切的停用日期，公告发在版本说明页——所以迁移之后要把这家的版本说明页加进你的订阅列表，这件事没有 API 会替你做。
第四件事：思考参数在跨平台时最容易被静默丢掉
推理/思考这一层是最近两年才长出来的，各家的参数名和默认行为都不一样，而 OpenAI 兼容层通常只保证「不报错」，不保证「行为一致」。
智谱在迁移到 GLM-5.3 的文档里给了一份自己的迁移清单，其中几条直接和这件事相关：该模型强制默认支持深度思考（thinking={ type: "enabled" }），文档写的是强制开启、关闭报错；思考程度由 reasoning_effort 控制，取值分为 low、high、max 三档。同一份清单还要求核对采样参数，官方建议 temperature 与 top_p 只选一个来调，两者的默认值以官方文档当前版本为准。
Gemini 的 OpenAI 兼容层做了一层映射：OpenAI 的 reasoning_effort 会映射到 Gemini 3.x 的 thinking_level 或 2.5 的 thinking_budget，档位是 minimal、low、medium、high。注意这里有两条限定：一是 reasoning_effort 与 thinking_level/thinking_budget 功能重叠，不能同时使用；二是关闭思考这件事不是到处都行——2.5 系列可以把 reasoning_effort 设成 none，而 Gemini 2.5 Pro 与 Gemini 3 系列官方明文说无法关闭推理。想在兼容层里传 Gemini 专有字段，官方给的通道是 extra_body。
阶跃星辰的 step-3.7-flash 在迁移页上写的是支持 low / medium / high 三档推理强度；xAI 在介绍 grok-4.3 时列的是 none、low、medium、high 四档。档位名字长得像，但档数和「能不能关」这两件事各家并不一致，照抄一个配置常量过去很可能落到一个你没打算要的档上。
上面这四组档位取值都是逐个从各家官方文档里数出来的枚举值，不是我按经验归纳的，但档位名称、档数和默认落在哪一档都可能随版本调整，具体取值一律以官方文档当前版本为准。所以这一项的正确做法不是背下四张表，而是在迁移评审里加一条：把每个线上负载当前显式传的推理参数列出来，逐个到新平台的文档里确认这个值存不存在、存在的话语义是不是同一件事。
钱的那一头也要一起核。Gemini 定价页的表头明文写着输出价格包括思考 token；xAI 的限流页则说明推理模型的 reasoning token 会计入该模型的 TPM。也就是说思考既进成本也进限流，迁移前如果按「输出字数」估算过预算，换到强制思考的模型上这个估算会失真。
第五件事：缓存不会自己跟着搬过去
上下文缓存在几家的文档里都被摆在降本手段的头一位，也是迁移时最容易「以为还在生效、其实早就没命中」的一格。先分清两种形态。
一种是自动的。Kimi 的上下文缓存文档说得最直白：对所有模型请求自动启用，无需手动创建，无需引用缓存 ID，无需管理 TTL，调用 /v1/chat/completions 时按正常方式传 messages 即可，系统在后台自动匹配。智谱的上下文缓存也是隐式缓存，官方描述是智能识别重复的上下文内容、无需手动配置。阶跃星辰的 Prompt 缓存走的是前缀匹配：按请求 Prompt 的前缀查缓存，命中就复用、未命中就正常推理并把前缀缓存起来供下次使用，缓存淘汰采用 LRU 策略，系统请求高峰期不用的缓存更容易被逐出。
另一种是显式的。MiniMax 把这两者的区别写在了同一页上：自动识别重复上下文、无需更改接口调用方式的叫「被动缓存」，需要在 API 里显式设置 cache_control 的那种叫「主动缓存」。这里有个容易想歪的地方：区分点是请求里有没有打这个显式标记，不是你连的哪个端点——官方主动缓存那页给的示例本身就用 Anthropic 兼容接口，但换个端点并不会让一次没有 cache_control 的请求自动变成主动缓存。
两者的边界还不止使用方式这一条。官方对照表里，被动缓存那一列列的支持模型是 MiniMax-M3 以及 M2.7 / M2.5 / M2.1 系列，主动缓存那一列列的是 M2.7 / M2.5 / M2.1 / M2 系列，不含 M3（支持范围以官方文档当前版本为准）。也就是说「我改用显式缓存来精确控制命中」这个决定，可能会顺带把你能选的模型范围一起改掉。过期方式也不同：被动缓存那栏写的是根据系统负载自动调整过期时间，主动缓存那栏写的是有一个固定的过期时间、持续使用会自动续期（具体时长以官方文档当前版本为准）。计费口径同样要分开看——被动缓存写的是命中的 token 按优惠价计费、写入部分无额外计费；主动缓存则是缓存读取按优惠价计费，首次写入需要额外计费，具体单价与相对关系见官方定价页。
Gemini 则同时提供隐式缓存与显式缓存，并且有一条很容易踩的接口约束：Interactions API 仅支持隐式缓存，要用显式缓存必须改用 generateContent API。它的计费依据也比「命中按优惠价、未命中按标准价」这种两分法多了一格——官方 FAQ 列的四项是输入 token 数、输出 token 数、缓存的 token 数，以及缓存 token 的存储时长，也就是缓存的「存」这件事本身按时长计费。把 MiniMax 和 Gemini 这两处摆在一起看就能明白，迁移时真正要重新确认的不是「新平台有没有缓存」，而是「这一家的缓存在哪几个环节上会产生费用」：有的按命中收、有的还按写入收、有的连放着不动也在计时。
然后是最实际的一格：你的成本监控读的那个字段名，各家不一样。 智谱文档里的字段是 usage.prompt_tokens_details.cached_tokens；阶跃星辰的响应示例里是 usage 下的 cached_tokens；Kimi 的对话补全接口示例中，usage 里同样带 cached_tokens；Gemini 官方给的命中量查询字段则是 usage.total_cached_tokens。迁移之后如果监控代码还在读旧字段，读到的是空值，看板上会显示成「缓存命中率归零」——但真实情况可能只是字段路径变了。这类跨厂商的缓存计费口径差异，可以对照各家缓存机制横评一起看。
第六件事：限流换的不只是数值，是坐标系
很多人迁移时只关心「新平台的限流够不够用」，其实更该问的是「新平台按什么维度限」。因为你的重试逻辑、并发池、退避策略都是围着旧坐标系写的。
智谱的速率限制页写的核心维度是并发请求数：不同模型设有独立的并发限制，不同权益等级与套餐对应不同的并发限制，另外还有高峰期的动态限流与平台级保护策略。Kimi 的限速文档同时定义了四个概念：并发（同一时间内最多处理的请求数）、RPM、TPM、TPD。Gemini 的三个基本维度是 RPM、TPM（每分钟输入 token 数）、RPD，部分模型还有 IPM（每分钟图片数）或 TPD；官方特别说明超出其中任何一个维度就会触发限流错误，不是几个维度综合评估。xAI 的维度组合又不同：每个 API team 对每个模型有 RPS（每秒请求数）与 TPM 两个维度，官方解释 RPS 是从每分钟请求预算推导出来的（RPM 除以 60），目的是不让你把一整分钟的请求额度在一秒内花光。
几条容易被忽略的细则也一起记下来。Gemini 的限流按项目（project）应用，不是按 API 密钥应用——多申请几把 Key 并不能绕开限流，这是官方专门点名的常见误解；它的 RPD 配额在太平洋时间午夜重置，不是本地时间也不是 UTC；Batch API 的限流完全独立于非批量调用。xAI 那边则说明：命中缓存的 prompt token 虽然按更低的费率计费，但仍然计入 TPM。这两条合起来看，意味着「用缓存降本」和「用缓存扩容」是两件事，前者成立不代表后者成立。
限流维度的通用定义和退避写法可以看RPM 与 TPM 限流机制，这里只提醒一句：迁移时把限流参数当成配置项而不是常量，否则换一家就要改一遍代码。
第七件事：错误处理那一层基本要重写
各家的错误结构几乎没有共同约定，字段名、错误码形态、同一个状态码底下的语义都不一样，而这一层偏偏只在出事的时候才暴露，最不适合「先跑起来再说」。
Kimi 返回的错误体是一个 error 对象，带 type 和 message。它的 429 尤其值得单独看：官方把 429 拆成了语义完全不同的几类——engine_overloaded_error 是服务节点负载高，文档明说这是服务端容量导致的，充值或提升 Tier 不能直接消除它，处理方式是按 Retry-After 提示等待、降低并发并用指数退避；exceeded_current_quota_error 是欠费或额度不足，退避多少次都没用；rate_limit_reached_error 才是真正的组织级限速，又细分为并发、RPM、TPM、TPD 几种触发原因。同一个 HTTP 状态码，三种完全不同的处置，这就是为什么「遇到 429 就退避重试」这条通用策略在这里会失效。
Gemini 的错误码是 snake_case 的机器可读 code 加人类可读 message，它的两个 429 同样语义分叉：rate_limit_exceeded 是分钟级限流，退避重试即可；quota_exceeded 是每日配额耗尽，只能等重置或申请提额。更隐蔽的是错误的传递方式：非流式请求通过 HTTP 状态码加 JSON body 里的 error 对象返回，而流式请求（SSE）是通过流内的 event_type: "error" 事件发送错误的。直接后果就是——只判 HTTP 状态码的客户端，会漏掉流式过程中发生的错误。迁移之后如果发现「偶尔响应莫名其妙断在半截、日志里却一片正常」，先查这一条。
MiniMax 的风格又换了一套：错误码是数字编号，未授权/Token 不匹配与无效 API Key 分属两个不同的数字码，文档同时提示反馈问题时要带上 Header 里的 trace_id。Kimi 那边对应的追踪标识叫 request_id，官方在 500 的处置里写的是持续出现就附带 request_id 联系支持。做统一封装时，这个「每家叫法不同的追踪 ID」是必须先抽出来的一个字段，否则真出事的时候你连给对方什么都不知道。
还有两个非限流类的坑值得单列：Kimi 文档里 499 是客户端在服务端返回前断开连接，常见于流式响应被中间代理切断；504 是服务端长时间无响应导致网关返回超时页，官方给的建议是非流式长请求改用流式输出（stream: true）。这两条都不是模型能力问题，是链路问题，迁移到新平台之后网络路径变了，出现频率也会变。通用的 429 处理框架仍然适用，但记得按上面这些差异做一层平台适配。
第八件事：切流量之前，先在开发环境跑完回归
这一步各家文档罕见地口径一致，说明它确实是踩出来的。
智谱的 GLM-5.3 迁移清单里最后一项写的是开发环境验证，要求做用例测试与回归，关注随机性、延迟、工具流中的参数完整性；同一页还专门列了几个观察点：响应是否符合预期、是否出现过度随机或过度保守的输出、工具流式构建与输出是否正常、长上下文与深度思考场景下的延迟与成本。阶跃星辰的模型迁移页写的是建议完成业务全量验证后再切换线上流量，并且给出了截止时点前必须完成接口替换、参数调优及业务全量验证的要求。
流式相关的回归要单独安排。智谱的迁移清单里把流式拆成了两件事：一件是启用 stream=true 之后要正确处理 delta.reasoning_content 与 delta.content 两路内容；另一件是工具调用的流式输出需要额外打开 tool_stream=true，并且要自己按 index 把 delta.tool_calls[*].function.arguments 拼接起来。如果你的旧代码是按单一 content 流写的，换到会单独吐思考流的模型上，第一反应往往是「模型不回答了」——其实内容都在另一个字段里。
限流额度也可以在这一步一并谈妥。阶跃星辰的 OpenAI 迁移页写明，测试完成后可以联系客服，平台会提供与 OpenAI 对标的 TPM / RPM 限制。这类事情越早提越好，别等到灰度放量那天才发现新平台的默认档位撑不住你的峰值。
最后：迁移真正的成本不在改代码
把上面八项串起来看，你会发现真正花时间的不是改 base_url，而是「确认那些没报错的地方也确实没变」。旧模型 slug 被自动重定向到新模型、缓存字段路径变了导致监控读到空值、思考默认档位从关变成强制开、流式错误没走 HTTP 状态码——这四类问题的共同点是：系统看起来完全正常。
所以给一个务实的收尾建议：迁移期至少保留一个能同时打到新旧两家的对照开关，让同一批请求分别走一遍，比对的不只是回答内容，还有 usage 里的每一个字段。账单侧的监控要在切流之前就先跑通，具体做法可以看API 成本监控；换厂商的通用流程与合同、数据合规那一层，则在换厂商迁移清单里有更完整的框架。这篇的八项，是在那个框架里专门属于「模型 API 接入层」的部分。