千问-image-max 属于图像生成方向的模型。调用它的 API 时，真正让人卡住的往往不是提示词，而是鉴权头写错、参数单位理解偏差，最后收到一个 401 或者一张空白图。

这篇指南不从概念讲起，而是按“接入前确认 → 鉴权写法 → 参数解析 → 联调排查”的顺序展开，尽量把容易忽略的细节提前说清楚，让你在第一次发起请求时就能知道自己错在哪一环。

接入前先确认三件事：地址、模型名、鉴权方式

很多“接口调不通”的问题，其实在写第一行代码之前就已经埋下了。动手前，请先把下面三项核对一遍。

1. 接口地址（Base URL）：图像生成接口通常挂在某个版本路径之下，有的服务商要求地址结尾带 /v1，有的则已经内置。路径拼接错误会直接返回 404，而不是提示参数问题。
2. 模型名称：模型名通常是一个大小写敏感的字符串，多一个连字符、少一个后缀都会导致“模型不存在”。必须以文档或控制台中实时显示的模型名称为准，不要凭记忆拼写。
3. 鉴权方式：目前主流图像生成 API 走 HTTP 请求头鉴权，但字段名可能是 Authorization，也可能是 x-api-key 或类似的私有字段。这一点必须在文档里确认，不能想当然。

如果只需要对接一个模型，把这些信息记在配置里就够了。但如果同时要调用对话、图像、视频等多类模型，分别维护 Key、地址和模型名会很快变得难以追踪。这时可以考虑用一个统一的入口来集中管理，例如 通联AI中转站 这类 AI 聚合平台，把 API Key、Base URL 和模型选择放在一处维护，减少在多个后台之间来回切换的成本。

鉴权方式解析：从 API Key 到请求头的完整链路

Bearer Token 是图像接口的常见写法

对于 OpenAI 兼容风格的接口，鉴权信息一般放在请求头里，格式如下：

Authorization: Bearer sk-你的APIKey
Content-Type: application/json

这里有两个极易出错的地方。第一，Bearer 和 API Key 之间必须有一个空格，不能写成 Bearer:sk-xxx 或 Bearersk-xxx。第二，API Key 前后不能有多余的空格或换行，从网页复制的 Key 有时会带上不可见字符，粘贴进配置文件后就会一直鉴权失败。

此外，Content-Type 需要是 application/json。图像生成请求体是 JSON 结构，如果这一项缺失或写成了 text/plain，服务端可能无法正确解析你的参数，返回的错误信息往往还会指向别处，让人误判。

区分 401 与 403：鉴权失败的两层含义

收到 401 Unauthorized，通常意味着 Key 本身没有被识别——可能写错了、被截断了，或者该 Key 已经失效。收到 403 Forbidden，则更可能是 Key 有效、但当前账号没有该模型的调用权限，或者余额状态不允许继续调用。

排查时建议按这个顺序：先确认请求头字段名与文档一致，再确认 Key 字符串完整，最后确认账号侧的权限与余额状态。这三步能覆盖绝大多数鉴权类报错。

Key 的存放方式与轮换习惯

无论用哪种语言，API Key 都不应该硬编码进前端代码或提交到代码仓库。推荐放进环境变量或密钥管理服务，代码里只读取变量名。如果需要多人协作，建议为不同成员或不同项目分配独立的 Key，方便定位用量来源，也方便在某个 Key 泄露时单独吊销而不影响其他服务。

任何字符级细节的差异都不会被服务端“自动纠正”。模型名、请求头字段、地址路径这三类信息，请始终以控制台或官方文档当前显示的内容为准，而不是以事前的记忆或第三方教程为准。

关键参数解析：真正影响出图结果的字段

图像生成接口的参数通常分成三类：身份类、内容类、输出类。下面这张表把常见配置项的用途与自查方法做了对照，具体字段名请以你所用服务的文档为准。

内容类参数：提示词决定上限

正向提示词负责描述你想要什么，负向提示词负责排除你不想要什么。实践中的经验是：主体、风格、构图、光线分句描述，比堆砌一长串同义形容词更有效。如果模型支持负向提示词，把常见的干扰项（例如多余文字、畸变结构）写进去，往往比反复调整正向提示词更快见效。

输出类参数：尺寸、数量与返回格式

尺寸参数是最容易踩坑的一项。有的接口接收宽高两个数值，有的接收 1024x1024 这样的字符串，有的直接接收比例描述。字段类型写错，请求会在参数校验阶段就被拒绝。

生成数量通常由类似 n 的字段控制，取值上限受服务端限制。返回格式则决定你拿到的是图片 URL 还是 Base64 字符串——如果要做二次处理，Base64 更方便；如果只是展示，URL 更省带宽。这两类参数都需要按照你的实际使用场景来选，而不是照抄示例。

一次完整的接入与联调流程

1. 在服务商控制台创建 API Key，并记录它对应的权限范围。
2. 从文档或控制台复制 Base URL，确认是否需要在代码中额外拼接路径。
3. 确认要调用的模型名称，逐字符比对，不要凭印象填写。
4. 用一条最简请求做连通性测试：只保留鉴权头、模型名和一句简短提示词。
5. 连通后再逐步加入尺寸、返回格式等参数，每次只改一项，便于定位问题来源。
6. 把验证通过的配置抽成常量或环境变量，避免散落在代码各处。

第 4 步尤其重要。很多人一上来就把完整参数写齐，结果报错时无法判断是鉴权问题还是参数问题。先用最小请求确认链路通畅，是效率最高的调试方式。

常见报错与排查方向

• 401 鉴权失败：检查请求头字段名、空格位置、Key 是否完整且未过期。
• 404 找不到路径：检查 Base URL 末尾斜杠与路径拼接，确认版本号是否需要保留。
• 模型不存在：模型名拼写错误，或当前 Key 没有该模型权限。
• 参数校验失败：尺寸字段类型不符、取值范围越界，或必填字段缺失。
• 请求超时：图像生成耗时通常高于文本请求，客户端超时时间设得过短会被提前中断，需要适当放宽。

多模型场景下如何统一管理鉴权与参数

当项目里同时用到对话模型和图像模型时，鉴权和参数的差异会成倍增加：不同厂商的 Base URL 不同，请求头字段可能不同，参数命名也可能不一致。一个务实的做法是先把接口协议收敛到同一套风格，再逐步替换配置，而不是一次性全量改造。

如果希望减少在多平台之间切换的成本，可以在 通联AI中转站 的控制台里查看当前可用的模型与接口说明，确认 Base URL、模型名称与兼容协议后再逐项替换。这样做的价值不在于省掉几行代码，而在于把 Key 管理、模型选择和用量查看集中到一处，出问题时排查路径更短。

最后提醒一句：本文提到的所有字段名称与结构，都只是接入层面的通用说明。千问-image-max AI绘图API 的具体鉴权字段、参数命名、取值上限与计费方式，请以你实际使用平台的控制台和文档当前展示的信息为准。接入前多花十分钟核对，往往比事后花一小时排查更划算。