文生图 API 接入卡住的地方，往往不是模型本身，而是密钥怎么配、Base URL 填什么、请求体怎么写。这篇教程按“准备—配置—调用—排查”四步拆开讲，帮你把 GK Image 2.0 文生图API 真正跑通。

和纯文本模型不同，文生图接口的失败原因更分散：密钥没问题，可能是模型名称写错；模型名称对了，可能是尺寸参数超范围；参数都对了，也可能只是返回的是图片 URL 而不是 base64，而你的代码没做兼容。所以下面不会只给一段“能跑就行”的示例，而是把每个配置项的作用和检查方法讲清楚，让你在报错时知道该看哪一行。

一、接入前先确认三件事

在写第一行调用代码之前，先把下面三件事确认掉，可以省掉大部分调试时间。

1. 密钥与调用凭证

API Key 是一串绑定到你账号的凭证，它决定了调用权限、可用模型范围和费用归属。你需要先在平台控制台创建 Key，并确认它是否绑定了额度或分组。很多“401 未授权”并不是 Key 写错了，而是复制时带上了多余空格，或者 Key 已被删除、已过期、已超出配额。建议第一次调用时把 Key 放进环境变量而不是硬编码在代码里。

2. 接口地址与协议兼容方向

Base URL 是你请求发送的目标地址。如果你的项目原本就在用 OpenAI 兼容的写法，通常只需要替换 Base URL、API Key 和模型名称这三处。若你还没确定用哪个接入点，可以在 通联AI中转站 的控制台查看当前提供的接口地址与兼容协议说明，再决定是替换现有配置还是新建一套配置。

3. 模型名称与能力边界

模型名称必须和控制台或模型广场中展示的写法完全一致，大小写、连字符、版本后缀都算数。同时要确认该模型支持的能力范围——有的模型擅长写实人像，有的擅长插画或文字排版，有的支持图生图、参考图或局部重绘。把“文本生图”当成万能接口，是 prompt 写得再好也出不来满意结果的主要原因。

二、密钥配置：从获取到安全存放

密钥配置是整个接入流程里最容易埋坑的一步，按下面的顺序做，基本不会返工。

1. 在控制台创建 API Key：创建后立即复制并保存，部分平台出于安全考虑不会再次完整显示。
2. 确认 Key 的可用范围：是否限定了模型范围、是否有余额或速率限制，避免调用时被静默拦截。
3. 写入环境变量：本地开发用 .env 或系统环境变量，线上用平台的密钥管理服务，不要提交到代码仓库。
4. 做一次最小连通性测试：先用最简单的请求确认鉴权通过，再去调复杂的图片参数。
5. 记录 Key 的用途：不同环境、不同项目使用不同 Key，方便后续定位消耗来源和随时吊销。

提示：接口地址、模型名称、支持的尺寸与计费规则都可能随平台更新而变化。动手前请以控制台和接口文档当前显示的内容为准，不要直接照搬网上旧教程里的模型名或参数值。

三、调用示例：一次最小可用的文生图请求

下面是一个最小可用的请求结构。它只保留鉴权、模型、提示词和输出尺寸四个必要部分，方便你先跑通链路，再逐步加参数。

curl -X POST "https://你的BaseURL/v1/images/generations" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "控制台显示的模型名称", "prompt": "一只戴宇航头盔的橘猫，居中构图，柔和侧光，纯净背景", "size": "1024x1024", "n": 1 }'

Python 侧的逻辑完全一致，只是把上面的请求体换成 SDK 或 requests.post 调用。真正需要逐项核对的是参数本身，下面这张表可以作为配置自查清单。

返回结果怎么处理

文生图接口的返回通常有两种形态：直接返回图片的临时链接，或返回 base64 编码的图像数据。你的代码应当先判断返回结构再决定是下载保存还是直接解码，并给链接类结果加上有效期处理，避免几分钟后图片失效导致缓存里全是坏图。另外，建议把每次调用的提示词、模型名称、尺寸和返回状态一并写入日志，方便复盘哪类 prompt 效果更稳定。

四、常见报错与排查顺序

报错时不要从 prompt 开始改，按下面的顺序从外到内排查，通常两三步就能定位。

• 401 / 403 鉴权失败：优先检查 Key 是否正确、是否被删除、请求头格式是否完整。
• 404 地址不存在：Base URL 多写或少写了路径，或者请求方法用错。
• 模型不存在或无权访问：模型名称与控制台展示不一致，或该 Key 未开通对应模型。
• 参数错误：尺寸、数量、返回格式等参数超出允许范围，先去掉所有可选参数只留必填项。
• 请求超时：图像生成耗时通常高于文本请求，需要适当延长客户端超时时间并做好重试去重。
• 内容被拦截：提示词触发了安全策略，可调整描述方式后再试。

五、把 GK Image 2.0 文生图API 接入做稳的三条建议

第一，把配置集中管理。Base URL、模型名称、Key 都放到统一配置文件或环境变量中，切换环境时不改业务代码。第二，把失败做成可观测的。记录状态码、错误信息和消耗情况，出问题时能第一时间判断是额度、权限还是参数问题。第三，不要一开始就追求参数堆满。先用一句提示词确认链路通、出图正常，再逐步加入负向提示、比例控制和风格描述，这样每一步变化都能归因。

如果你的项目后续还要接入对话、图像、视频、语音等多种能力，可以考虑用一套统一接口来管理。像 通联AI中转站 这类 AI 中转站的做法是提供一个 Base URL 和统一的 Key 管理入口，在控制台里查看模型广场、模型排行与接入文档，按任务选择合适的能力，减少在多平台之间来回切换配置的工作量。实际可用的模型清单、兼容协议与计费方式，请以官网页面当前展示的信息为准。