通过中间层JSON转换器、Nginx代理重写或环境变量双字段兼容，可使旧客户端无需代码改造即适配火山引擎API字段变更。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在火山引擎的 API 配置中修改了 JSON 字段（比如把 model_name 改成 model、api_key 改成 token），旧版客户端程序会立刻报错：字段缺失、解析失败、空指针或 400 Bad Request。这类问题不改代码就无法运行，但全量重写又耗时耗力。本指南只讲怎么让老程序继续跑通新结构，不讲原理、不讲选型、不讲未来演进。
用中间层 JSON 转换器兼容字段名变更
第一步：在请求发出前、响应收到后各加一层转换逻辑。对请求体做字段映射重写，对响应体做字段还原。例如旧程序期望字段是 api_key，而火山新接口只认 token，那就用一个轻量函数做键名替换。
第二步：以 Python 为例，在调用火山 API 的封装函数开头插入如下代码：
# 替换请求字段
payload = {k.replace("api_key", "token").replace("model_name", "model"): v for k, v in payload.items()}
第三步：如果响应里也变了结构（比如返回字段从 result 变成 output），就在接收响应后立即做反向映射：
response_json = resp.json()
if "output" in response_json:
response_json["result"] = response_json.pop("output")
这一步必须在旧程序读取 response_json["result"] 之前完成，否则直接抛 KeyError。注意不要全局替换字符串，只处理顶层键名，避免误改嵌套内容里的同名字段。
用 Nginx 代理动态重写 JSON 请求体
方法一：启用 nginx 的 http_sub_module 模块（需编译时开启）
location /v1/chat/completions {
proxy_pass https://ark.cn-beijing.volces.com/v1/chat/completions;
sub_filter '"api_key":' '"token":';
sub_filter '"model_name":' '"model":';
sub_filter_once off;
}
方法二：更稳妥的做法是用 lua-resty-json 模块做结构化重写，避免正则误伤字符串值。先安装 OpenResty，再在 location 块中嵌入 Lua：
content_by_lua_block {
local cjson = require "cjson"
local data = ngx.req.get_body_data()
if data then
local obj = cjson.decode(data)
obj.token = obj.api_key
obj.model = obj.model_name
obj.api_key = nil
obj.model_name = nil
ngx.req.set_body_data(cjson.encode(obj))
end
}
【注意】Nginx 默认不缓存 POST 请求体，必须显式调用 ngx.req.read_body() 或设置 client_max_body_size，否则 get_body_data() 返回 nil。
用环境变量开关控制双版本字段输出
第一步：在旧程序初始化时读取环境变量 VOLC_JSON_COMPAT=1，判断是否启用兼容模式。
第二步：构造请求 payload 时，根据该变量决定字段写法：
if os.getenv("VOLC_JSON_COMPAT") == "1":
payload["token"] = api_key
payload["model"] = model_name
payload["api_key"] = api_key # 同时保留旧字段，供调试用
payload["model_name"] = model_name
else:
payload["token"] = api_key
payload["model"] = model_name
第三步：在火山侧 API 网关配置中，将 token 和 api_key 都视为合法认证字段，优先取 token，token 缺失时 fallback 到 api_key。这样旧程序不改代码、只加环境变量就能过渡。
第四步：上线后观察日志中 api_key 字段的调用占比，降到 5% 以下即可下掉兼容分支。
