图片生成 API

路梦云图提供图片生成接口，支持 OpenAI 兼容格式 与 Gemini 原生格式，可以完成文生图、图生图（编辑）、多图参考，以及固定 4K / 2K / 1K 清晰度的生成任务。

前置条件

图片生成需要 Key 所在分组开启图片生成权限（由管理员配置）。未开启时，OpenAI 格式返回 403 permission_error（Image generation is not enabled for this group），Gemini 原生格式返回 400；Key 分组平台不匹配时会返回 404 Images API is not supported for this platform。

使用 Grok 分组？请看另一篇

本页的 size 写法与 1K / 2K / 4K 档位规则不适用于 Grok 分组：Grok 图片用 aspect_ratio + resolution（1k / 2k）控制画面，计费规则也不同；图生图、图生视频的参考图字段同样和本页不一样。详见 Grok 生图与生视频。

鉴权与基础配置

项目	值
文生图	`POST https://xmlumen.org/v1/images/generations`
图生图（编辑）	`POST https://xmlumen.org/v1/images/edits`
OpenAI 格式认证	`Authorization: Bearer YOUR_API_KEY`
Gemini 原生入口	`POST https://xmlumen.org/v1beta/models/{MODEL}:generateContent`
Gemini 格式认证	`x-goog-api-key: YOUR_API_KEY`

请使用控制台创建的 API Key，并确认 Key 绑定了包含图片模型的分组。

OpenAI 格式生图

OpenAI 兼容格式使用 gpt-image-* 系列模型，以你分组实际开放的模型名为准。目前最新的是 gpt-image-2.5-flare（速度优先）和 gpt-image-2.5-sunburst（编辑精度优先），上一代 gpt-image-2 仍可使用。下文生图示例用 gpt-image-2.5-flare，图生图示例用 gpt-image-2.5-sunburst。

固定清晰度的关键

size 请填真实宽高（如 3840x2160、2048x1152），不要写 "4K" / "2K" 这类档位字符串，宽高还要满足上游的尺寸约束。平台按 size 的最长边划分计费档位（≤1024 记 1K / ≤2048 记 2K / >2048 记 4K），不填 size 或填 auto 时按 2K 计费。尺寸写法见下方推荐尺寸。

文生图

bash

curl https://xmlumen.org/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "一张电影感的小猫照片，毛发清晰，干净背景",
    "size": "3840x2160",
    "quality": "high",
    "response_format": "url"
  }'

提示词建议覆盖主体、风格、构图、背景、光线与细节要求，描述越具体结果越稳定。测试时不要只写 test，请写有实际画面含义的内容。

图生图（编辑）

图生图使用 multipart/form-data：

bash

curl https://xmlumen.org/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=gpt-image-2.5-sunburst \
  -F prompt="改成赛博朋克夜景风格，保持主体不变" \
  -F size=2048x1152 \
  -F quality=high \
  -F response_format=url \
  -F image=@input.png

需要多张参考图时，重复追加 image 字段即可：

bash

-F image=@a.png -F image=@b.png -F image=@c.png

请求参数

参数	说明
`model`	图片模型名，如 `gpt-image-2.5-flare`，以分组实际开放为准
`prompt`	图片描述，必填
`size`	真实宽高，如 `3840x2160`（4K）、`2048x1152`（2K）、`1024x1024`（1K）；须满足尺寸约束，按最长边决定计费档位
`quality`	`low` / `medium` / `high` / `auto`；`gpt-image-2.5-*` 另支持 `xhigh` / `max`
`response_format`	`url` 返回图片链接；`b64_json` 返回 base64 数据。官方 GPT 图片模型只产出 base64，拿不到链接时改用 `b64_json`
`output_format`	输出图片格式：`png` / `jpeg` / `webp`
`image`	仅 `/v1/images/edits`：参考图文件，可重复传多张

background、style、output_compression、input_fidelity 等 OpenAI 原生参数会透传给上游，是否生效取决于上游模型支持。

比例	4K 档	2K 档	1K 档	适用场景
1:1	`2160x2160`	`2048x2048`	`1024x1024`	头像、App 图标、商品主图、社交方图
16:9	`3840x2160`	`2048x1152`	—	桌面壁纸、视频封面、PPT 配图、网站 Banner
9:16	`2160x3840`	`1152x2048`	—	手机壁纸、短视频封面、竖版海报、开屏页
4:3	`2880x2160`	`2048x1536`	`1024x768`	文章配图、平板壁纸、课件插图
3:4	`2160x2880`	`1536x2048`	`768x1024`	小红书封面、电商详情图、竖版人像
3:2	`3072x2048`	`1536x1024`	`1008x672`	摄影感画面、横版插画、印刷照片
2:3	`2048x3072`	`1024x1536`	`672x1008`	书籍封面、电影海报、竖版摄影
21:9	`3808x1632`	`2016x864`	—	超宽横幅、带鱼屏壁纸、网站 Hero 图

响应格式

response_format: "url" 时返回图片链接：

json

{
  "created": 1782997587,
  "data": [{ "url": "https://…/images/xxx.png" }]
}

response_format: "b64_json" 时返回 base64 图片数据，适合不希望依赖外链的场景：

json

{
  "created": 1782997587,
  "data": [{ "b64_json": "BASE64_IMAGE_DATA" }]
}

WARNING

返回的图片 URL 可能有有效期，请尽快下载保存。

SDK 示例

PythonNode.js

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://xmlumen.org/v1",
)

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="一张电影感的小猫照片，毛发清晰，干净背景",
    size="2048x1152",
    quality="high",
    response_format="url",
)
print(result.data[0].url)

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: 'https://xmlumen.org/v1',
})

const result = await client.images.generate({
  model: 'gpt-image-2.5-flare',
  prompt: '一张电影感的小猫照片，毛发清晰，干净背景',
  size: '3840x2160',
  quality: 'high',
  response_format: 'url',
})
console.log(result.data[0].url)

Gemini 原生格式生图

客户端使用 Gemini 调用格式时，走 Gemini 原生路径（不要再调 OpenAI 的 /v1/images/generations）：

POST https://xmlumen.org/v1beta/models/{MODEL}:generateContent

图片模型名以分组实际开放为准，常用的有 gemini-3.1-flash-image（Nano Banana 2，速度快）和 gemini-3-pro-image（Nano Banana Pro，擅长复杂排版与文字渲染）。旧的 gemini-3-pro-image-preview 已停用，请改用正式版模型名。可先查询模型列表：

bash

curl https://xmlumen.org/v1beta/models \
  -H "x-goog-api-key: YOUR_API_KEY"

文生图

清晰度通过 generationConfig.imageConfig.imageSize 控制，可选 1K / 2K / 4K（K 必须大写），比例用 aspectRatio：

bash

curl https://xmlumen.org/v1beta/models/gemini-3.1-flash-image:generateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{ "text": "画一张水彩风格的蓝色机器人头像，干净背景" }]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": { "imageSize": "1K", "aspectRatio": "1:1" }
    }
  }'

务必显式填写 imageSize

不填 imageSize 时上游默认输出 1K，平台却按 2K 档计费；gemini-3.1-flash-image 额外支持的 512 档，平台目前同样按 2K 档计费。想按哪一档付费，就显式填写对应的 1K / 2K / 4K。

图生图 / 多图参考

参考图以 inlineData（base64）放进 contents.parts，多张参考图就追加多个 inlineData：

json

{
  "contents": [{
    "role": "user",
    "parts": [
      { "text": "参考这些图片，生成一张同角色、电影海报风格的新图" },
      { "inlineData": { "mimeType": "image/png", "data": "BASE64_IMAGE_1" } },
      { "inlineData": { "mimeType": "image/jpeg", "data": "BASE64_IMAGE_2" } }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": { "imageSize": "2K", "aspectRatio": "16:9" }
  }
}

Gemini 原生格式默认在响应的 candidates[].content.parts[].inlineData 中返回 base64 图片数据。

错误处理

状态码 / 错误	原因与处理
`400 Invalid image size`	`size` 不合规：写了 `4K` / `2K` 档位字符串，或宽高不满足尺寸约束（16 的倍数、比例、像素范围）——改用推荐尺寸表中的写法
`400`（Gemini 原生格式，提示未开启生图）	Key 所在分组未开启图片生成权限，联系管理员开通
`401 authentication_error`	Key 无效或认证头不对：OpenAI 格式用 `Authorization: Bearer`，Gemini 格式用 `x-goog-api-key`
`403 permission_error`	OpenAI 格式下 Key 所在分组未开启图片生成权限（`Image generation is not enabled for this group`），联系管理员开通
`404 Images API is not supported for this platform`	Key 分组不是 OpenAI 平台，或客户端还在用 OpenAI 路径调 Gemini 模型——请切换分组或改用 `/v1beta/models/...:generateContent`
`429`	触发速率限制或上游繁忙，稍后重试
`5xx`	上游波动，稍后重试；持续出现请联系管理员查看渠道监控

注意事项

固定 4K / 2K / 1K 时，OpenAI 格式用满足尺寸约束的真实宽高；Gemini 格式用 imageSize 档位，并且务必显式填写。
计费档位只看 size 的最长边：≤1024 记 1K，≤2048 记 2K，>2048 记 4K。2560x1440 这类写法会落到 4K 档，别被「2K 分辨率」的习惯叫法误导；不填 size 时按 2K 计费。
4K 图片生成明显更慢，实际可能需要约 1 分钟，高峰期更久；客户端超时建议设为 180–300 秒，复杂图生图可再放宽。
竖图把宽高对调即可（4K 竖图 2160x3840，2K 竖图 1152x2048）；9:16 没有合规的 1K 尺寸。
实际可用模型、尺寸、参考图数量与返回格式，以你的分组与后台配置为准。

图片生成 API ​

鉴权与基础配置 ​

OpenAI 格式生图 ​

文生图 ​

图生图（编辑） ​

请求参数 ​

推荐尺寸 ​

响应格式 ​

SDK 示例 ​

Gemini 原生格式生图 ​

文生图 ​

图生图 / 多图参考 ​

错误处理 ​

注意事项 ​

图片生成 API

鉴权与基础配置

OpenAI 格式生图

文生图

图生图（编辑）

请求参数

推荐尺寸

响应格式

SDK 示例

Gemini 原生格式生图

文生图

图生图 / 多图参考

错误处理

注意事项