生图接入指南

本页说明如何通过 We-AI 接入图片生成与图片编辑能力。示例默认使用兼容 OpenAI Images API 的调用方式，并以 gpt-image-2 作为需要稳定指定输出尺寸时的推荐模型。

一、接入前准备

你需要先准备：

• API 地址：当前可用入口如下，接入时选择其中一个即可。
  • https://us-la.we-token.cc/：国际加速路线。
  • https://asian-acc.we-token.cc/：亚太加速路线。
  • https://sub2api.we-token.cc/：国内加速路线。
  • https://sub2api.aitu.art/：Aitu 独立站点入口；它是早先单独的独立站点，与 we-token.cc 的用户体系不打通。
• API 密钥：在请求头中使用 Authorization: Bearer YOUR_API_KEY
• 一个服务端运行环境：不要把 API 密钥直接写在浏览器前端代码里
• 足够长的请求超时：建议客户端和中转站的超时时间都设置为 30 分钟左右。当前生图链路基于 OpenAI Plus 号池做 Codex 反代，遇到 OpenAI 限流或上游算力不足时，平台内部最多会重试 3 次，加上第一次请求总共可能产生 4 次生图请求，因此部分请求等待时间会比较久。

us-la.we-token.cc、asian-acc.we-token.cc 和 sub2api.we-token.cc 都是 We-AI 的 we-token.cc 站点，用户体系相同，区别只是加速区域不同。sub2api.aitu.art 是早先单独的独立站点，与 we-token.cc 的用户体系不打通，API Key、余额和账号信息请以对应站点后台为准。示例以下方国际加速路线为例，亚太或国内访问可将域名替换为 asian-acc.we-token.cc 或 sub2api.we-token.cc。

最小请求结构如下：

POST https://us-la.we-token.cc/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "model": "gpt-image-2",
  "prompt": "一只可爱的橘猫，电影感，高清",
  "size": "1024x1024"
}

二、选择调用方式

常见接入方式有两种，主要区别在请求体格式：

方式	接口	请求体格式	常用字段	适合场景
文生图	POST /v1/images/generations	application/json	model、prompt、size、n	根据提示词生成一张新图
图生图 / 图片编辑	POST /v1/images/edits	multipart/form-data	model、image、prompt、size、n	上传一张或多张参考图后进行改图、融合、风格迁移或扩图

建议使用 images/generations 和 images/edits。这两个接口接近 OpenAI Images API 的标准用法，后续切换模型或复用 SDK 时也更直接。

调用时注意：

• 文生图不上传图片，只传 JSON 请求体；prompt 是核心输入。
• 图生图必须上传图片文件，使用 multipart/form-data；单图可以传 image=@reference.png，多图建议按官方参考写法传多个 image[]=@file.png。
• 两个接口都会返回 data 数组。当前 We-AI 生图链路统一读取 data[0].b64_json，不要依赖图片 URL。
• 示例只保留当前链路建议使用的字段。quality、response_format 等官方扩展字段先不要传，避免兼容通道不识别。

三、模型说明：gpt-image-2

gpt-image-2 适合需要稳定锁定输出尺寸的图片生成任务，例如电商主图、海报模板、视频封面、信息图、桌面壁纸等。

核心特点：

• 支持文生图、单图编辑、多图融合和自然语言改图。
• 兼容 images/generations、images/edits 两类端点。
• 支持通过 size 字段指定官方常用尺寸，或传入满足官方约束的自定义 宽x高 分辨率。
• 中文提示词友好，适合直接使用中文描述画面、风格、构图和文字内容。
• 支持 n 参数生成多张图片。由于这里是 Codex 反代接口，内部会按 n 的数量轮询调用生成图片，建议 n 不超过 4，避免等待时间过长。

注意事项：

• size 请使用官方常用尺寸，或满足官方约束的精确字符串，例如 2048x1360。
• size 中的 x 使用半角小写字母，不要写成 × 或大写 X。
• 由于当前链路使用 sub2api，只有 1024x1024 会被识别为 1k 尺寸；1536x1024、1024x1536 等横竖版尺寸虽然是官方常用尺寸，但不要按 1k 档位理解。
• 不要传 quality 参数。
• 可以传 n 参数，但建议不要超过 4。
• 返回结果统一通过 b64_json 提供，不返回图片 URL。
• We-AI 平台不保存任何用户数据，包括输入图片、提示词和生成结果。
• 部分兼容通道的 b64_json 可能已经包含 data:image/png;base64, 前缀，前端使用前建议先判断是否已有 data: 前缀。

四、文生图示例

文生图接口使用 JSON 请求体，适合从零生成图片。最小可用字段是 model、prompt 和 size：

curl "https://us-la.we-token.cc/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "生成一张白色陶瓷马克杯放在灰色桌面上的产品图，柔和自然光，简洁背景",
    "size": "2048x1360"
  }'

如果需要一次生成多张，可以增加 n，但建议不要超过 4：

{
  "model": "gpt-image-2",
  "prompt": "生成 3 张不同构图的科技产品海报，干净背景，适合官网首屏",
  "size": "2048x1152",
  "n": 3
}

响应中的图片结果都会放在 b64_json 字段里。业务侧可以这样读取生成结果：

const images = response.data ?? []
const imageBase64List = images.map((image) => image.b64_json).filter(Boolean)

若拿到的是 base64，可直接写入文件或作为前端 <img> 的 src，但要先确认是否已经包含 data:image/...;base64, 前缀。

五、图生图 / 图片编辑示例

图生图和图片编辑接口使用 multipart/form-data，适合在参考图基础上改背景、换风格、保留主体、融合多图或做局部编辑。

单图编辑示例：

curl "https://us-la.we-token.cc/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@reference.png" \
  -F "prompt=保留主体产品不变，把背景改成浅灰色摄影棚，增加柔和阴影" \
  -F "size=2048x1360"

多图融合示例：

curl "https://us-la.we-token.cc/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image[]=@product.png" \
  -F "image[]=@background.png" \
  -F "prompt=保留第一张图中的产品主体，融合到第二张图的场景里，整体光线自然，边缘真实" \
  -F "size=2048x1152"

如果只上传一张图，使用 image=@reference.png 即可；如果上传多张图，建议使用 image[]=@file.png 重复传入。输入图体积过大时，容易导致请求变慢、失败或触发网关限制；建议先压缩到合理大小，再上传给接口。输出分辨率主要由 size 字段决定，不需要依赖超大的输入图来提高输出尺寸。

六、支持的 size

gpt-image-2 的 size 参考 OpenAI Image generation guide。请求体中可以直接传 size: "宽x高"，也可以传 auto 让模型自动选择尺寸。

官方常用尺寸如下：

用途	size	说明
方图	1024x1024	通用默认尺寸；在当前 sub2api 链路中，只有这个尺寸会被识别为 1k
横版	1536x1024	官方常用横版尺寸；在 sub2api 中不要按 1k 档位理解
竖版	1024x1536	官方常用竖版尺寸；在 sub2api 中不要按 1k 档位理解
2K 方图	2048x2048	适合需要更高分辨率的方图
2K 横版	2048x1152	常用 16:9 横版尺寸
4K 横版	3840x2160	高分辨率横版尺寸，上游可能更慢或更不稳定
4K 竖版	2160x3840	高分辨率竖版尺寸，上游可能更慢或更不稳定
自动	auto	不需要精确锁定尺寸时使用

如果需要其他比例，也可以传满足官方约束的自定义尺寸，例如 2048x1360：

• 宽和高都必须是 16px 的倍数。
• 最长边不能超过 3840px。
• 长边与短边比例不能超过 3:1。
• 总像素数必须在 655,360 到 8,294,400 之间。
• 超过 2560x1440 总像素量的输出属于实验性范围，可能更慢或更容易受上游波动影响。

选择建议：

• 草稿、缩略图、快速预览：优先选择 1024x1024。
• 大多数正式交付物：优先选择 2048x2048、2048x1152 或满足约束的相近自定义尺寸。
• 大屏、壁纸、印刷或高分辨率封面：选择 4K；如遇上游波动，可先降到接近比例的 2K 尺寸重试。

七、提示词建议

写提示词时，尽量把画面要求拆清楚：

• 主体：要生成什么，例如产品、人像、海报、插画、场景图。
• 构图：主体位置、镜头角度、留白、横版或竖版。
• 风格：写实摄影、3D 渲染、水彩插画、扁平矢量、电影感等。
• 光线与背景：自然光、棚拍、纯色背景、室内、户外等。
• 文字要求：如果图中需要文字，明确写出文字内容、语言、位置和样式。
• 禁止项：不需要的元素也可以写清楚，例如不要水印、不要多余文字、不要变形手指。

提示词不必写得过于复杂。尤其是画面中需要生成文案时，建议减少口号、长句和多段文字；文字越多、排版要求越复杂，越容易导致生成失败或文字效果不稳定。可以先生成主体画面，再用设计工具或后续编辑步骤补充精确文案。

示例：

生成一张 16:9 横版科技产品海报。
主体是一台银色笔记本电脑，放在深灰色桌面中央。
背景是干净的办公室，浅景深，柔和自然光。
画面右侧留出空白区域，用于后期添加标题。
不要水印，不要多余文字，不要出现品牌 Logo。

八、成功生图指南

生图成功率和准确率不只取决于模型，也取决于客户方怎么组织请求。建议把生图当成一个可控的生产流程：先明确目标，再提供参考素材，最后用较小步长迭代，不要把所有要求一次性塞进同一个请求。

通用做法

• 一次请求只解决一个主要目标，例如“换背景”“生成主图”“做海报氛围图”“统一角色形象”，避免同时要求换主体、改风格、加文案、变构图和扩尺寸。
• 需要保留真实商品、人物或角色时，优先使用图生图 / 图片编辑接口，并上传清晰参考图；不要只靠文字描述让模型凭空还原细节。
• 先用 1024x1024、1536x1024、1024x1536 等常用尺寸做预览，确认方向后再提高到 2K 或 4K，能减少等待时间和失败概率。
• 单次 n 建议从 1 开始。批量生成时由业务系统拆成多个任务排队执行，并控制并发，避免同时堆大量高分辨率请求。
• 图片输入尽量清晰、主体完整、无严重压缩噪点。商品图、角色图、背景图最好分开上传，不要把多个目标挤在一张复杂拼图里。
• 提示词按“保留什么、改变什么、不要什么”来写。需要严格保留的内容写在前面，例如主体外观、材质、比例、Logo、角色脸型、发型、服装。
• 图中文字不要交给模型承载太多精确排版。价格、促销词、剧名、字幕、按钮文案等建议后期用设计工具或业务系统叠加。
• 对失败请求做分类处理：参数错误先改参数，内容不准先改提示词或参考图，上游繁忙再稍后重试；不要把同一个失败请求无限原样重发。

关于一次性 4K 出图

很多客户希望“一个提示词直接 4K 生成最终高清图”，这类需求可以理解，但要提前说明：平台支持高分辨率输出，不代表每个创意都适合从第一步就直接 4K 出图。4K 请求耗时更长、上游波动更明显，失败重试时间也会更久；如果提示词同时包含主体、背景、风格、构图、文字、局部细节和禁止项，模型需要一次性满足太多目标，反而更容易出现不准、变形、缺图或超时。

推荐给客户的解释话术：

4K 更适合作为最终交付尺寸，不适合作为第一次试错尺寸。
建议先用较小尺寸确认主体、构图、风格和参考图是否准确，再把已经稳定的方案提高到 2K 或 4K 输出。
这样不是降低质量，而是把创意确认和高清出图分成两步，通常能减少等待、减少失败，也能提高最终图片的准确率。

建议流程：

1. 第一轮用常用尺寸生成预览图，重点确认画面方向是否正确。
2. 如果主体不准，先补参考图或改提示词；如果风格不准，先固定风格描述；如果构图不准，先改镜头和留白。
3. 预览图方向稳定后，再使用同一套提示词和参考图提高到 2K 或 4K。
4. 4K 阶段单次 n 建议保持为 1，并确保客户端和中转站端超时设置为 30 分钟。
5. 如果 4K 连续失败，先降到接近比例的 2K 尺寸确认链路和画面，再重新尝试 4K。

如果客户必须直接 4K 生成，建议把请求控制得更简单：只保留一个主要目标，上传清晰参考图，不要同时要求复杂中文排版、多个主体、多场景融合和大幅度改图。这样能尽量提高一次性出图的成功率。

电商业务示例

电商生图最重要的是商品准确。客户方如果要生成主图、场景图、详情页氛围图，建议以真实商品图作为输入，用图片编辑接口让模型“保留商品，只改环境”。

推荐流程：

1. 准备一张清晰商品图，主体完整、无遮挡，最好是白底图或干净背景图。
2. 先生成低风险版本：只换背景、灯光和构图，不改商品本体。
3. 确认商品外观准确后，再尝试增加道具、人物手持、节日氛围或更复杂场景。
4. 促销标签、价格、卖点文案、平台角标后期叠加，不建议直接让模型生成复杂中文排版。

示例提示词：

保留参考图中的商品主体不变，包括外形、颜色、材质、比例、Logo 和包装文字。
将背景改成干净的浅灰色电商摄影棚，柔和棚拍光，商品居中摆放，轻微阴影。
画面适合作为电商主图，整体真实、清晰、无多余道具。
不要改变商品结构，不要新增品牌 Logo，不要生成促销文字，不要水印。

如果要做场景图，可以在“保留商品不变”后增加具体使用场景：

保留参考图中的商品主体不变。
把商品放在现代厨房台面上，背景有柔和虚化的家居环境，自然晨光，真实摄影风格。
商品占画面中心偏下位置，四周留出适合详情页裁切的空间。
不要改变商品外观，不要添加无关文字，不要让商品被遮挡。

抖音漫剧业务示例

抖音漫剧类业务更关注角色一致性、镜头叙事和竖版画面稳定。建议先建立角色设定，再用参考图持续生成不同镜头，不要每一张都只用一段新文字从零生成角色。

推荐流程：

1. 先生成角色定妆图：正面、半身、服装、发型、年龄感和画风要固定。
2. 后续分镜都上传角色参考图，通过图生图 / 图片编辑接口保持角色一致。
3. 每次只生成一个镜头，写清楚场景、动作、表情、镜头距离和画面比例。
4. 台词、字幕、标题、集数等文字后期叠加，避免模型直接生成大量可读文字。
5. 角色、背景、道具冲突时，优先保角色；背景可以后续再单独补强。

角色定妆提示词示例：

生成一张 9:16 竖版漫剧角色定妆图。
角色是一位 24 岁女性，黑色长发，白色衬衫，深色短外套，气质冷静，现代都市风。
半身构图，正面视角，干净浅色背景，线条清晰，适合后续作为角色参考图。
不要文字，不要水印，不要夸张表情，不要复杂背景。

分镜生图提示词示例：

参考上传的角色图，保持同一个角色的脸型、发型、服装和整体画风一致。
生成 9:16 竖版画面：角色站在夜晚的写字楼大厅里，侧身回头，表情警觉。
镜头为中景，背景有冷色灯光和玻璃反射，氛围紧张，适合抖音漫剧分镜。
不要改变角色服装，不要生成字幕，不要添加水印，不要出现多余人物。

批量生产时，建议把每个镜头的提示词结构固定下来，只替换“场景、动作、表情、镜头距离”。这样更容易排查哪一类请求导致失败，也更容易保持整部漫剧的画风统一。

九、错误处理与重试

生图接口会透传部分 OpenAI 上游错误。业务侧建议同时读取 HTTP 状态码和错误消息中的 message，再决定是提示用户修改参数，还是提示稍后重试。

断连说明

为了提高生图成功率，平台会内置最多 3 次失败重试；加上第一次请求，同一个任务总共可能产生 4 次生图请求。因此有些请求会等待较久，尤其是在 OpenAI 限流、上游算力不足或图片尺寸较大时。

如果用户侧看到 do request failed、Failed to read request body、context deadline exceeded 等报错，通常属于请求过程中连接被中途断开，不一定代表生图任务本身一定失败。常见断连原因包括：用户端主动断开连接、网络波动导致断连、超过中转站连接超时时间、超过用户端超时时间。

建议用户端和中转站端都把连接超时时间设置为 30 分钟，以便覆盖平台内部重试耗时，提高最终成功率。

400：用户参数或输入数据错误

如果错误消息中包含以下关键词，通常说明用户传入的数据或参数不符合要求。客户端应提示用户修改请求后重新提交，不建议原样自动重试。

可能看到的报错 message / 关键词	常见原因	建议处理
Invalid size '3000x2000'. Width and height must both be divisible by 16.	size 不满足上游尺寸约束，例如宽高不是 16px 的倍数、比例超过限制或总像素数超限	改用上方官方常用尺寸，或确保自定义尺寸满足所有约束
The image data you provided does not represent a valid image. Please check your input and try again.	上传图片数据异常、损坏或无法读取	重新上传图片，确认图片文件完整可打开
The image data you provided does not represent a valid image. Please check your input and try again with one of the supported image formats: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'].	图片格式不受支持	改用 jpeg、png、gif 或 webp，避免只改后缀名
Invalid mask image format - mask image missing alpha channel	mask 遮罩图缺少 alpha 通道，或遮罩格式不符合要求	重新生成带透明通道的遮罩图，并确认遮罩图与输入图尺寸匹配
The 'gpt-image-2' model is not supported when using Codex with a ChatGPT account.	上游账号或通道不支持当前模型	稍后重试；如果持续出现，请联系平台处理通道配置
images[].image_url is required	调用 images/edits 编辑接口时缺少参考图	上传参考图后再请求，确认 image 字段已正确传入
image_generation_user_error	上游判断为用户输入导致的生图错误，通常会和具体 message 一起出现	按具体 message 修改提示词、图片或请求参数后重试
Your request was rejected by the safety system	提示词或图片触发了上游安全/内容审核策略，涉及违规、敏感或不允许生成的内容	修改提示词或更换参考图，去除违规、敏感或受限内容后重试，不要原样重发

400/502：OpenAI 上游繁忙或限流

如果错误消息中包含以下关键词，通常属于 OpenAI 上游限流、服务繁忙或算力不足。客户端可以提示用户稍后重试，并使用指数退避减少连续请求。

可能看到的报错 message / 关键词	常见原因	建议处理
Openai error, You can retry your request.	OpenAI 服务繁忙、限流或算力不足时，平台可能返回的通用错误	等待一段时间后重试，避免短时间内密集重发
Upstream request failed	OpenAI 上游请求失败，具体原因可能记录在上游错误详情中	稍后重试；如果持续失败，记录 request id 后联系平台排查
Rate limit reached for gpt-image-2-codex ... Please try again ...	OpenAI 生图链路触发限流	稍后重试，降低并发，减少 n 的数量
Our servers are currently overloaded. Please try again later.	OpenAI 服务繁忙或算力不足	稍后重试，必要时降低尺寸档位
An error occurred while processing your request. You can retry your request ...	OpenAI 服务繁忙或算力不足	等待一段时间后重试，避免短时间内密集重发

400/502：上游未返回图片

如果错误消息中包含 openai images upstream returned no image output，表示 OpenAI 已执行生图请求，但没有返回可用图片。常见原因包括提示词或图片请求不合规、提示词过于复杂，或上游算力不足。

建议处理：

• 先让用户审核提示词和图片请求是否合规，避免涉及违规、敏感或不允许生成的内容。
• 简化提示词，减少复杂文案、过多主体和冲突要求。
• 如果上传了图片，检查图片内容、格式、尺寸和清晰度。
• 如果同一请求连续失败，不要只原样重试，应修改提示词或输入图片后再提交。
• 如果只是偶发失败，可以稍后重试，并保持客户端和中转站端超时为 30 分钟左右。

其他常见状态

状态	可能原因	建议处理
401	API 密钥无效或请求头格式错误	检查 Authorization: Bearer YOUR_API_KEY
429	请求过于频繁或额度不足	降低并发，稍后重试
超时	生成耗时较长、OpenAI 限流、上游算力不足，或平台内部重试仍未完成	将客户端和中转站端超时设置到 30 分钟左右，压缩输入图，必要时降低尺寸档位

建议在日志中记录：

• 请求模型
• size
• n
• 提示词摘要
• 输入图片数量与大小
• 响应状态码
• 错误响应中的 message
• 响应头中的 request id 或 trace id

十、参考资料

• OpenAI Image generation guide
• OpenAI API Reference: Create image
• OpenAI API Reference: Create image edit