1. 生图接口的图片输入到底怎么传生图接口的图片输入传递方式是很多开发者在接入多模型生图能力时第一个卡住的地方。文生图只需要给一段文字描述图生图却要把参考图和指令一起塞进请求体两者的参数结构完全不同。如果你正在做 AI 绘画工具、电商换背景、批量出图流水线或者只是想把生图能力接进自己的后端服务这篇会帮你把两种模式的传参差异彻底理清。核心问题其实就一个图片输入到底放在哪个字段里用什么格式传。OpenAI 兼容协议下文生图的content是纯字符串图生图的content是数组数组里同时包含image_url和text两种类型的元素。这个差异看起来小但传错了就是 400 报错或者模型完全忽略你的参考图。我实测下来最容易踩的坑有三个一是把本地文件路径直接塞进image_url服务端根本访问不到二是文生图和图生图共用一套请求体结果图生图模式下参考图被当成普通文本三是超时设置照抄对话接口的 30 秒图还没生成完客户端就断了钱花了图没拿到。这篇会给出 TaoToken 统一 Key 的配置骨架、文生图与图生图的请求体参数对照表以及可以直接复制的 curl 验证命令。目标很明确让你在半小时内跑通两种模式并且知道每个参数为什么这么传。2. TaoToken 统一 Key 的前置配置TaoToken 的定位是统一密钥接入多模型生图能力端点兼容 OpenAI 协议换model字符串就能切换模型不用为每个模型单独写一套 SDK。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。在开始写生图代码之前先把密钥和基础配置准备好。这一步不复杂但配置文件的字段名写错了后面会一直报 401。2.1 获取 API Key登录后进入控制台在 API Keys 页面创建一个新密钥。建议按项目或环境分开创建比如dev-image、prod-image方便后续排查是哪个环境在消耗额度。密钥只在创建时完整显示一次复制后立刻存进环境变量或密钥管理服务不要硬编码进代码仓库。如果你用的是 Claude Code 或类似的编码 Agent 工具长期跑生图任务的话可以看下 Coding Plan额度模型和按次计费不太一样批量场景下更划算。2.2 settings.json 配置片段如果你用的是支持settings.json的工具链比如某些 CLI 或 IDE 插件配置骨架大概长这样{ image: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, defaultModel: gpt-image-2, timeoutMs: 120000, models: { draft: nano-banana2, final: gpt-image-2, wide: nano-banana-pro } } }这里把模型分了三档draft跑量试错final出终稿wide处理超宽超高比例。超时统一给到 120 秒因为生图是整张图生成完才返回中间没有任何流式输出。2.3 config.toml 配置片段如果你的项目用 TOML 管理配置等价写法如下[image] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} default_model gpt-image-2 timeout_ms 120000 [image.models] draft nano-banana2 final gpt-image-2 wide nano-banana-pro两种格式选一种就行关键是base_url不要带多余的路径/v1之类的后缀由具体端点拼接时处理。TaoToken 的 API 地址就是https://taotoken.net/api不要自己加 UTM 参数到 API 调用里那些参数只用于官网跳转统计。注意环境变量TAOTOKEN_API_KEY要在启动服务前注入不要写死在配置文件里提交到 Git。CI/CD 环境用 secrets 管理。3. 文生图与图生图的请求体参数对照这是整篇最核心的部分。文生图和图生图在 OpenAI 兼容协议下走的是同一个端点区别只在messages[].content的结构。下面用表格把两种模式的参数差异列清楚。参数文生图图生图说明model必填必填模型 ID如gpt-image-2messages[0].roleuseruser固定值messages[0].content字符串数组核心差异所在content[].type无image_url/text图生图必须显式声明类型content[].image_url.url无可访问的 URL本地文件需先上传content[].text无指令文本描述要改什么timeout建议 120s建议 120s生图比对话慢得多文生图的content就是一段描述文字模型根据文字从零生成图片。图生图的content是一个数组里面至少有一个image_url元素和一个text元素模型根据参考图和指令做修改、换背景、局部调整。3.1 文生图请求体{ model: gpt-image-2, messages: [ { role: user, content: 一只橘猫坐在窗台上午后阳光浅景深胶片质感 } ] }content直接给字符串不需要任何类型声明。这是最简单的形式也是很多人第一次接生图接口时唯一会写的模式。3.2 图生图请求体{ model: gpt-image-2, messages: [ { role: user, content: [ { type: image_url, image_url: { url: https://your-cdn.example.com/input/cat.jpg } }, { type: text, text: 把背景换成海边日落猫的位置和姿态保持不变 } ] } ] }注意content从字符串变成了数组每个元素都有type字段。image_url的url必须是服务端能访问到的公网地址内网地址、localhost、本地文件路径都不行。3.3 两种模式共用一个封装函数既然只有content一处不同完全可以封装成一个函数根据是否传入参考图自动切换async function generateImage({ prompt, imageUrl, model gpt-image-2 }) { const content imageUrl ? [ { type: image_url, image_url: { url: imageUrl } }, { type: text, text: prompt }, ] : prompt; const res await fetch(https://taotoken.net/api/v1/chat/completions, { method: POST, headers: { Authorization: Bearer ${process.env.TAOTOKEN_API_KEY}, Content-Type: application/json, }, body: JSON.stringify({ model, messages: [{ role: user, content }], }), signal: AbortSignal.timeout(120000), }); if (!res.ok) { const err await res.text(); throw new Error(${model} HTTP ${res.status}: ${err}); } return res.json(); }调用文生图时只传prompt调用图生图时同时传prompt和imageUrl。这样业务层不用关心底层是哪种模式传参逻辑收敛在一个地方后面排查问题也方便。4. 用 curl 验证两种模式配置和封装写完之后先用 curl 把两种模式各跑一遍确认密钥、端点、参数都没问题再往业务代码里集成。这样出问题时能快速定位是配置层还是业务层。4.1 文生图验证curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: nano-banana2, messages: [ { role: user, content: 一只柴犬在草地上奔跑晴天运动模糊背景 } ] }跑量场景先用nano-banana2出图快、成本低适合验证链路通不通。返回结果里会包含图片的 URL 或 base64 数据具体格式取决于模型。4.2 图生图验证curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-image-2, messages: [ { role: user, content: [ { type: image_url, image_url: { url: https://your-cdn.example.com/input/dog.jpg } }, { type: text, text: 把草地换成雪地柴犬的毛色和姿态不变 } ] } ] }图生图验证时先把参考图上传到自己的对象存储或图床拿到公网可访问的 URL 再填进image_url.url。这一步不能省直接填本地路径一定会失败。4.3 成功返回的特征两种模式成功后返回的结构类似都会包含生成结果。你需要关注的是HTTP 状态码 200、返回体里有图片数据或图片 URL、没有error字段。如果返回 200 但内容为空大概率是模型 ID 写错了或者content结构不符合该模型的要求。拿到返回的图片 URL 后立刻转存到自己的存储。返回链接通常有有效期过期就取不回来了数据库里应该存自己的地址而不是上游的临时链接。5. 本篇常见传参报错排查生图接口的报错信息有时候不太直观下面把最常见的几类问题和排查方向列出来。5.1 400 报错content 类型不匹配如果你在文生图模式下传了数组或者图生图模式下传了字符串都会触发 400。排查方法很简单看你的content是字符串还是数组。文生图必须是字符串图生图必须是数组且每个元素带type。还有一种情况是图生图的数组里只有text没有image_url或者只有image_url没有text。两种元素至少要各有一个否则模型不知道你要改什么。5.2 图片 URL 无法访问图生图最常见的失败原因是参考图 URL 服务端拉不到。可能的原因包括用了内网地址、用了localhost、图片需要鉴权、URL 有防盗链、图片格式不被支持。排查时先用curl -I检查这个 URL 在公网能不能直接访问返回 200 且Content-Type是图片类型才行。5.3 超时导致图丢失把超时设成 30 秒是很多人的默认习惯因为对话接口 30 秒够用。但生图是整张图生成完才返回重模型可能要一两分钟。客户端提前断开后服务端其实已经出图成功这次调用照样计费但图拿不到。解决办法是按模型分档设置超时跑量的快模型给 60 秒终稿的重模型给 120 秒。重试之前先确认上一次是真失败还是只是客户端超时否则会重复计费。5.4 前端直接调接口导致密钥泄露生图接口不应该由前端直接调用。一是前端等两分钟不现实二是密钥会打进前端包。正确做法是后端收到请求先落一条任务记录返回任务 ID后台异步跑生图前端轮询自己的任务表。这样既避免了密钥泄露也避免了前端超时。5.5 返回链接过期上游返回的图片链接是有有效期的直接存进数据库过几天就失效了。拿到结果后立刻转存到自己的对象存储数据库里存自己的地址。这一步在批量场景下尤其重要否则历史记录里的图全变成裂图。6. 把生图能力稳定接进业务跑通两种模式只是第一步真正上线还要考虑成本控制和稳定性。核心思路是分级跑量用便宜的快模型多出几版挑中的才用贵的出终稿。一上来就用最贵的模型试错钱都花在废图上了。再加一层结果缓存同样的描述和参数如果已经出过图直接返回旧结果不要重复调用。批量场景下这一层省下的比换模型还多。如果你需要长期跑生图任务或者在做编码 Agent 相关的图像生成功能可以看下 Coding Plan 的额度模型。模型对话页面可以直接测试不同模型的出图效果接入文档里有完整的端点和参数说明API Keys 页面管理你的密钥。生图接口的图片输入传递说到底就是记住一件事文生图content给字符串图生图content给数组数组里image_url和text各司其职。把这个结构记牢剩下的就是超时、重试、转存这些工程细节。