企业官网建设流程全解析

那种“标题看着简单，真上手一堆暗坑”的项目，最近刚好把某套支持图像生成与编辑的 API 完整接入了一个 Node.js 后台服务，整个流程跑通之后回头整理这份教程。这套接口在 2.5 版本里同时支持从文本描述直接生成图片、基于已有图片做二次编辑，还允许用自然语言描述修改内容，比如“把背景换成傍晚的橙色天空”这种指令，接口会直接对原图做语义理解再输出结果。如果你正在做内容生产工具、设计辅助平台，或者想给博客、小程序加一个“AI 配图”功能，这份实操笔记可以直接照着抄，每一步我都会说明参数为什么那样写、响应为什么要那样解析，而不是只贴一段能跑的代码。

我尽量把代码、参数、报错场景都拆开讲，适合刚接触这类接口的开发者，也适合已经调过基础版本、想升级到 2.5 能力的同学。

1. 项目背景与能力边界

先把这套 API 到底能做什么说清楚。2.5 版本的能力可以大致分成三块。

1.1 文本生成图片

给一句描述性的 prompt，比如“一只戴牛仔帽的柴犬坐在复古皮卡后座，窗外是荒漠夕阳”，接口返回一张符合描述的图片。这个能力最直接的使用场景就是配图、封面、海报底图、素材占位。和早期版本相比，2.5 对长文本描述的还原度明显更好，尤其是包含多个物体、相对位置关系、光线方向的描述，不再容易出现“元素堆在一起”的僵硬感。

1.2 图片编辑与局部重绘

输入一张原图、一段修改指令，接口返回修改后的图片。这里要特别注意，它并不是简单的滤镜叠加，也不是画板式的涂改，而是理解原图内容后再做生成。举个例子，你给一张室内装修实拍照，说“把沙发换成墨绿色天鹅绒材质，保持其他家具不变”，输出结果会在保留房间结构、其他物品的前提下更换沙发材质。这个能力是所有编辑功能里使用频率最高的，适合电商产品图替换背景、设计稿换配色、摄影作品调整元素。

1.3 图片理解与指令式修改

同样支持“把图片里人物的笑容调整得更自然”“去掉背景里路过的人”“把光线改成清晨的柔光”这类需要先理解画面内容、再做局部修改的指令。本质上这依赖多模态理解能力，接口内部会先分析画面中都有什么对象、它们的位置和关系，再根据指令生成新的画面。

从实际开发角度，这三个能力对应三种不同的接口调用方式，但请求结构高度相似，无非是传的参数不同。所以下面我统一按“生成”和“编辑”两条主线来讲。

2. 环境准备与 API 接入前置工作

这部分主要解决三件事：拿到调用凭证、装好 HTTP 请求库、确定输出格式。

2.1 获取 API 凭证与安全策略

无论你用的是哪家服务商的接口，第一步永远是搞到 key。通常在服务商控制台创建一个应用，得到一串 API Key，有些平台还区分 Secret Key 和 Access Key 两个字段，签名方式也略有不同。这一步没什么技术含量，但有几个安全工作必须提前做：

• key 绝对不要写死在代码仓库里。哪怕项目是私有的，也不建议。我用的是dotenv加载.env文件，并把.env加进.gitignore。
• 服务端调用时把 key 放在后端，不要在前端代码里暴露。因为接口费用是跟 key 走的，一旦前端暴露 key，等于把钱包敞开给所有人。
• 如果服务商支持子 Key 或者 IP 白名单，建议按环境分别配置，测试环境一个 key，生产环境一个 key，出问题时方便按 key 排查。

2.2 安装依赖与初始化项目

既然标题明确使用 Node.js，我就以 Node.js 环境为例。初始化一个项目并安装依赖：

mkdir image-api-demo cd image-api-demo npm init -y npm install dotenv # 如果习惯用官方 SDK 就装 SDK，如果没有官方 SDK 或不想受限制，直接装 axios 或 fetch npm install axios

Node.js 18 及以上版本自带全局 fetch，如果不想引入 axios，直接用内置 fetch 也完全没问题。不过我在实际项目里倾向用 axios，因为它的超时配置、错误处理、请求拦截器比原生 fetch 顺手，尤其当你要对多个接口做统一鉴权时，axios 拦截器能省不少重复代码。

2.3 理解请求与响应结构

不管具体接口路径长什么样，这类生成式图片 API 的请求结构基本是：

{ "model": "image-gen-2.5", "prompt": "一只戴牛仔帽的柴犬坐在复古皮卡后座", "n": 1, "size": "1024x1024", "response_format": "b64_json" }

响应通常是：

{ "created": 1731234567, "data": [ { "b64_json": "这里是base64编码的图片数据" } ] }

如果你设置了response_format: "url"，响应里的data会是一个图片临时链接，有效期一般只有几分钟到一小时不等。这个细节很关键，我在 4.3 节会展开讲为什么推荐直接拿 base64 而不是拿 url。

3. 文本生成图片：从请求到保存文件

这是最简单的一条链路，但很多新手会在“图片怎么落盘”这一步卡住。我不光写怎么调用，还把参数选择的逻辑讲清楚。

3.1 文生图核心代码

import dotenv from "dotenv"; import axios from "axios"; import fs from "node:fs/promises"; dotenv.config(); const API_KEY = process.env.IMAGE_API_KEY; const BASE_URL = process.env.IMAGE_API_BASE_URL; async function generateImage({ prompt, size = "1024x1024", n = 1 }) { const response = await axios.post( `${BASE_URL}/images/generations`, { model: "image-gen-2.5", prompt, n, size, response_format: "b64_json", }, { headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, timeout: 60000, } ); const results = response.data.data; const saveTasks = results.map(async (item, index) => { const buffer = Buffer.from(item.b64_json, "base64"); const filename = `output_${Date.now()}_${index}.png`; await fs.writeFile(filename, buffer); return filename; }); const filenames = await Promise.all(saveTasks); return filenames; } generateImage({ prompt: "一只戴牛仔帽的柴犬坐在复古皮卡后座，窗外是荒漠夕阳，电影感构图", }) .then((filenames) => console.log("已保存:", filenames)) .catch((err) => console.error("生成失败:", err.message));

这段代码的核心只有三部分：拼接请求体、发送 POST 请求、把返回的 base64 转成 Buffer 写入文件。Buffer.from(item.b64_json, "base64")这一步是把 URL-safe 的 base64 字符串还原为二进制的标准做法。

3.2 为什么 prompt 要写这么多细节

很多人第一次调用时只写“狗、车、沙漠”这类简单词，生成结果往往很普通。这跟接口能力没关系，是输入的信息量不够。以我测试多次的经验来看，prompt 至少应该包含这几个维度：

• 主体对象：什么东西，数量多少
• 外观特征：颜色、材质、穿着、状态
• 环境与背景：地点、时间、天气、光线
• 风格参考：摄影风格、构图方式、画风、镜头焦段
• 画质要求：高清、细节丰富、专业摄影等

前面的示例 prompt 就包含了全部五个维度。“戴牛仔帽的柴犬”是主体加外观，“复古皮卡后座”是环境，“荒漠夕阳”是光线，“电影感构图”是风格，“专业摄影”这类词虽然笼统，但确实会引导模型往高质量方向走。

3.3 size 参数怎么选择

size 直接影响生成图的宽高比，不同服务商支持的分辨率集合不同，常见的有：

• 1024x1024：正方形，适合头像、封面、通用素材
• 1024x1792：竖版 9:16 比例，适合海报、小红书配图、手机壁纸
• 1792x1024：横版 16:9 比例，适合公众号头图、视频封面、PPT背景
• 512x512：小尺寸，生成速度快，适合快速迭代预览

我这里建议默认用1024x1024，因为很多模型的细节表现力在这个尺寸下最稳定。等 prompt 调合适了，再按最终使用场景换成对应的宽高比，不要一开始就用竖版长图去调试 prompt，会同时遇到构图和细节两个变量叠加的问题，很难定位是描述的问题还是分辨率的问题。

# 输出效果不理想时优先排查：prompt 是否足够具体，size 是否匹配场景 # 再用同一条 prompt 在不同 size 下对比，观察差异

3.4 一次生成多张图的取舍

请求参数里的 n 表示一次返回几张候选图。部分服务商会把 n 上限限制在 1 到 4 之间，而且 n 越大，整体耗时越长、费用越高。我的习惯是调试阶段 n 设为 2 或 3，挑一张满意的，正式生产环境 n 设为 1 或 2，避免浪费配额和等待时间。

如果你要做批量生成，比如一次生成 20 张不同描述的图片，不要在一个请求里塞多个 prompt，而是写循环分批请求，每批控制在 2 到 3 个并发，既能充分利用接口能力，又不容易触发热点限制。

4. 图片编辑：基于原图的三种玩法

图片编辑的接口调用跟生成接口很像，但请求体里多了一个image字段，用来传原图数据。这里要注意的是原图数据的格式，以及编辑模式和生成模式的参数差异。

4.1 基于原图的对象修改

适用场景：替换产品颜色、换背景、改人物服装。先把原图读成 base64，再放进请求体。

import fs from "node:fs/promises"; async function editImage({ imagePath, prompt, size = "1024x1024" }) { const imageBuffer = await fs.readFile(imagePath); const imageBase64 = imageBuffer.toString("base64"); const response = await axios.post( `${BASE_URL}/images/edits`, { model: "image-gen-2.5", image: imageBase64, prompt, size, response_format: "b64_json", }, { headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, timeout: 120000, } ); const result = response.data.data[0]; const outputBuffer = Buffer.from(result.b64_json, "base64"); const filename = `edited_${Date.now()}.png`; await fs.writeFile(filename, outputBuffer); return filename; } editImage({ imagePath: "./input/product.jpg", prompt: "把产品背景替换成干净的浅灰色摄影棚背景，产品本身不变", }).then((filename) => console.log("已保存:", filename));

有几个细节值得展开。第一，image字段传的是 base64 字符串，不是文件路径。如果你用的是官方 SDK，有些 SDK 会直接接受本地文件路径并帮你处理编码，但手动请求时必须自己转。第二，编辑接口的超时时间要比生成接口设得更长，因为模型需要先分析原图内容，再执行生成，整个链路更耗时。

4.2 局部重绘：让模型只动某个区域

部分接口支持用mask参数指定重绘区域。所谓 mask，是一张与原图同尺寸的图片，需要重绘的区域用白色标注，其他区域用黑色覆盖。这个能力非常适合“只想改画面中的一小部分，不破坏整体结构”的场景。

const maskBuffer = await fs.readFile("./mask.png"); const maskBase64 = maskBuffer.toString("base64"); const response = await axios.post( `${BASE_URL}/images/edits`, { model: "image-gen-2.5", image: imageBase64, mask: maskBase64, prompt: "把白色区域替换成一只橙色花纹猫", size: "1024x1024", response_format: "b64_json", }, // headers 同前 );

mask 必须由开发者自己准备，常用做法是先用程序把原图中想要修改的区域标出来，生成 mask。如果你不想手动做 mask，可以用不带 mask 的编辑接口，靠 prompt 指定要修改的内容。两者的区别在于：带 mask，模型只会在指定区域生成，其他区域完全保持原样，可控性更高；不带 mask，模型会根据 prompt 在整幅图上做调整，修改范围可能超出预期。

以我测试过的项目为例，处理“把照片里的路人挪走”这个需求，不带 mask 硬调很容易连带改变天空颜色或建筑细节，后来改成先手动圈出路人所在区域生成 mask，再用 mask 编辑，效果就稳定多了。如果讲究工作流效率，建议写一个简单的 Canvas 服务，让用户在网页上框选需要重绘的区域，后端根据框选坐标生成 mask，然后调用接口。

4.3 编辑结果返回 URL 还是 Base64

这是很多人忽略的一个关键点。请求体里response_format设置为url，接口会返回一个临时链接，你可以直接把这个链接给前端展示，看起来省事。但临时链接有效期通常只有几十分钟，而且你在服务器上还要再额外向后端存储服务转发一次，增加一道不稳定环节。

设置为b64_json后，接口直接把图片数据打包在 JSON 里返回，虽然单个响应体积会变大一点，但免掉了“拉取临时链接”的额外请求，也不存在链接过期的问题。我的建议是：如果图片需要长期保存，一律用b64_json，服务器直接落盘或者上传对象存储；如果只是临时展示，比如返回给前端预览几秒钟，url模式也够用，但要注意有效期。

4.4 编辑时 prompt 的修辞策略

编辑用的 prompt 跟生成用的 prompt 不一样，重点是描述“差异”，而不是描述完整画面。比如原图是一只柯基坐在草地上，你想让它变成坐在雪地里，两个写法：

• 普通写法：“柯基坐在雪地里”
• 高效写法：“保持柯基的姿势和朝向不变，把草地改为覆盖薄雪的冬季地面，光线变柔和，背景的树加上雪挂”

第二种写法效果明显更好的原因，是它明确告诉了模型哪些东西要保持不变。如果你只描述目标效果，模型可能会把狗的形态、角度、甚至品种一起改了，这不是你想要的。所以编辑场景的 prompt，尽量带“保持某某不变”这样的限制性描述。

5. 工程化落地：文件处理、并发与容错

到这里，接口调用本身已经可以跑通了。但要真正用到生产环境，还必须处理文件格式校验、重试机制、错误响应解析、并发控制等工程问题。

5.1 图片格式与大小预处理

不是所有图片传给编辑接口都能被正确处理。以我实际使用的接口来说，支持的输入格式通常是 PNG、JPEG、WEBP，并且图片不能太大，有些平台要求小于 5MB。如果你接入的业务经常有用户上传大图，必须在调用前做压缩处理。

Node.js 里我用sharp做图片预处理，它很成熟，性能也好。

npm install sharp

import sharp from "sharp"; async function preprocessImage(inputPath, outputPath) { await sharp(inputPath) .resize(1024, 1024, { fit: "inside" }) .jpeg({ quality: 85 }) .toFile(outputPath); }

.resize(1024, 1024, { fit: "inside" })表示在保持宽高比的前提下，把图片缩放并限制在 1024x1024 的边框内。为什么限制在这个尺寸？因为大多数图像生成模型会把输入图片缩放到固定分辨率再处理，如果你原图是 4000 像素宽，模型内部照样会先压缩，但压缩质量和直接传一张优化过的图是不同的，提前在本地压缩能保证细节损失更可控。同时，缩到 1024 的图片传输体积会小很多，上传更快，接口处理也更快。

5.2 重试机制：接口超时的兜底方案

生成式接口的耗时波动很大，高峰期可能 10 秒，也可能 60 秒。网络抖动、服务端排队都会造成偶发失败。我建议不是简单捕获异常就退出，而是写一层重试逻辑。

async function callWithRetry(fn, retries = 3, delayMs = 1000) { for (let attempt = 1; attempt <= retries; attempt++) { try { return await fn(); } catch (err) { if (attempt === retries) throw err; const isTimeout = err.code === "ECONNABORTED" || err.response?.status >= 500; if (!isTimeout) throw err; console.warn(`请求失败，第 ${attempt} 次重试: ${err.message}`); await new Promise((r) => setTimeout(r, delayMs * attempt)); } } }

这里的关键判断是：只有超时和 5xx 服务端错误才值得重试。如果是 4xx，比如prompt被内容审核拦截，或者image格式不对，那重试多少次都没用，反而会消耗配额。我的经验是，重试次数设为 3 次就够了，再多反而容易造成堆积。每次重试的间隔用指数退避，第一次 1 秒，第二次 2 秒，第三次 4 秒，避免服务端还没恢复就频繁重试。

5.3 常见错误码速查与排查思路

调这类接口，错误响应一般会带一个error对象，包含code和message。我把自己遇到过的典型错误整理成一个速查表：

尤其要注意内容违规这个错误。它跟代码无关，是 prompt 或图片触发服务商的内容审核机制。遇到这种问题，不要尝试绕过，而是修改描述方式。比如把带有特定品牌 logo 的图片改成“抽象的红色圆形标志”，既保持生成需求，又不触犯规则。

5.4 并发控制与任务队列

如果你要接入的是一个批量出图的后台系统，并发问题必须提前设计。我最早做的时候图省事，直接用Promise.all一次发 10 个请求，结果触发了限流，好几个请求返回 429。后来改成任务队列方案，一次只跑 2 个并发，每个请求完成后再从队列里取下一个任务。

async function runConcurrent(tasks, limit = 2) { const results = []; const queue = [...tasks]; const workers = Array.from({ length: limit }, async () => { while (queue.length) { const task = queue.shift(); try { results.push(await task()); } catch (err) { results.push({ error: err.message }); } } }); await Promise.all(workers); return results; }

队列的长度要根据接口的限流文档来定。有的接口允许每分钟 60 次请求，那就把并发控制在 1 比 2 更安全，给重试留出余量。不要满打满算地去压上限，一旦有重试挤进来，立马就会超出限制，反而导致连环失败。

5.5 图片后处理：检查结果是否可用的方法

接口返回图片后，不要直接信任它。生成式模型偶尔会输出“看起来正常但仔细看有畸变”的图，比如手指数不对、文字乱码、画面里出现奇怪的异物。对于半自动化流程，我建议至少要做三层检查：

• 尺寸检查：确保返回图片宽高比符合预期，不出现莫名的拉变形
• 文件大小检查：生成结果如果只有几 KB，大概率是一张纯色或模糊图，不可用
• 人工抽检：批量流程里随机抽取 5% 的结果人工审核，尤其在正式对外发布前

如果是做自动化封面生成，建议再加一道“文字拼写检测”，因为很多模型画文字还是不强，经常出现错字。这个可以利用 OCR 服务识别生成图里的文字内容，检查有没有大段乱码，有就直接重新生成一次。

6. 完整示例：把图片生成与编辑封装成一个服务

前面几节都是拆开的片段，这节给一个完整可运行的服务封装示例。实际项目里，我会把生成和编辑统一封装成一个模块，对外只暴露两个方法，调用方不需要关心接口细节。

// imageService.js import dotenv from "dotenv"; import axios from "axios"; import fs from "node:fs/promises"; import sharp from "sharp"; dotenv.config(); const API_KEY = process.env.IMAGE_API_KEY; const BASE_URL = process.env.IMAGE_API_BASE_URL; const TIMEOUT = 120000; const client = axios.create({ baseURL: BASE_URL, timeout: TIMEOUT, headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, }); async function saveBase64Image(b64, prefix = "output") { const buffer = Buffer.from(b64, "base64"); const filename = `${prefix}_${Date.now()}.png`; await fs.writeFile(filename, buffer); return filename; } export async function generateImage(prompt, options = {}) { const { size = "1024x1024", n = 1 } = options; const response = await client.post("/images/generations", { model: "image-gen-2.5", prompt, n, size, response_format: "b64_json", }); const filenames = []; for (const item of response.data.data) { const filename = await saveBase64Image(item.b64_json, "gen"); filenames.push(filename); } return filenames; } export async function editImage(imagePath, prompt, options = {}) { const { size = "1024x1024" } = options; const imageBuffer = await fs.readFile(imagePath); let processedBuffer = imageBuffer; // 如果图片太大，压缩到 1024 以内 if (imageBuffer.length > 4 * 1024 * 1024) { processedBuffer = await sharp(imageBuffer) .resize(1024, 1024, { fit: "inside" }) .jpeg({ quality: 85 }) .toBuffer(); } const imageBase64 = processedBuffer.toString("base64"); const response = await client.post("/images/edits", { model: "image-gen-2.5", image: imageBase64, prompt, size, response_format: "b64_json", }); const filename = await saveBase64Image(response.data.data[0].b64_json, "edit"); return filename; }

调用方只需要这样用：

import { generateImage, editImage } from "./imageService.js"; const genFiles = await generateImage("夏日海边沙滩上的白色遮阳伞，阳光明媚，高清摄影"); console.log(genFiles); const editFile = await editImage("./input/room.jpg", "把沙发的颜色改成墨绿色，材质换成天鹅绒"); console.log(editFile);

这样一个封装，调用方注意不到 base64 转换、图片压缩、响应解析这些细节，对上层业务来说，就是一个纯异步的“生图”和“改图”函数。后面想换别的服务商，也只需要改这一个文件，上层完全不用动。

7. 常见问题与排查技巧实录

做这个项目时我踩过不少坑，这里挑几个最有代表性的记录一下，供大家排查时参考。

7.1 base64 图片损坏，生成结果打不开

表现：接口返回成功，代码也执行完了，但生成的 PNG 文件打不开。排查后发现，有的接口会对 base64 做 URL 编码，字符串里的+会被替换成空格，直接拿来转 Buffer 就会损坏。

解决办法：保证拿到 base64 后先解码decodeURIComponent，或者把字符串里的空格替换成+。有些服务商还会在 response 里把\n保留在 base64 字符串中，需要先去掉所有换行符。

const cleanBase64 = item.b64_json.replace(/\s/g, ""); const buffer = Buffer.from(cleanBase64, "base64");

7.2 背景被意外修改

编辑接口不带 mask 时，模型对“保持背景不变”的理解是有限的。避免方案有两个：一是用 mask 精确控制可修改区域；二是在 prompt 里反复强调“背景保持不变”“其他区域完全不变”。我用过多次之后发现，后者只是降低概率，不能完全杜绝，要求高的话还是要做 mask。

7.3 反复触发 429 限流

触发限流时，接口会返回 429 状态码。除了降低并发，我建议记录请求时间戳，在本地做滑动窗口计数。比如已知限制是每分钟 60 次，那就写一个计数器，每分钟重置一次，在达到 55 次时主动等待几十秒再发送，这样比依赖服务端的 429 响应更稳。

7.4 n=1 时 data 数组为空

极少数情况下，接口请求成功但data数组是空的。这通常不是网络问题，而是内容审核阶段模型认为结果有风险，直接把生成结果丢弃了。遇到这种情况，调整 prompt 再试一次，尤其是把描述改得更中性，往往就能正常返回。

7.5 长 prompt 反而效果变差

很多新手以为 prompt 越长越好，其实不是。当 prompt 超过 500 字以后，模型对关键信息的抓取会明显变弱，甚至会出现细节冲突。我的经验是，控制在 100 到 300 字之间，把最重要的特征放在前面，比如“主体是什么、什么颜色、在什么环境、什么光线下”，句首信息对结果的影响权重更高。

8. 结束语：再分享两个小技巧

整套流程跑下来，最大的体会是“接口接入只是第一步，稳定地产出才是工程重点”。生成式接口天然带不确定性，所以在代码架构上一定要把错误处理、重试、输出校验当成一等公民来设计，而不是跑通就完事。

最后再分享两个小技巧。第一个，调试 prompt 时，建议用同一句话跑 2 到 3 次，观察结果是否存在明显差异，因为这类模型本身有随机性，一次结果不满意不代表 prompt 不行。第二个，如果在做内容平台，建议在生成图片后自动拼接一个“AI 生成”的水印文字标记，既是合规需要，也方便后续追踪图片来源。

如果你在实际接入中遇到了上面没写到的奇葩问题，欢迎和我交流，我这边也还在持续更新对这个接口的踩坑记录。