生图 API · gpt-image-2 / grok-imagine

文生图与图生图接入，使用 OpenAI 图片协议 POST /v1/images/generations 与 POST /v1/images/edits。生图比例通过 size 字段以 宽x高 像素形式指定。

Base URL

https://yyds.seqnode.com/v1

模型

gpt-image-2 / grok-imagine / grok-imagine-image / grok-imagine-image-quality

鉴权

Authorization: Bearer <Key>

最大尺寸

4K（长边 3840）

01 · 端点与协议

能力	创建接口	格式
文生图	POST `/v1/images/generations`	application/json
图生图 / 编辑	POST `/v1/images/edits`	multipart/form-data（推荐）或 application/json

统一鉴权：Authorization: Bearer YOUR_API_KEY。示例中 YOUR_API_KEY 替换为平台分配的 API Key，图片为 multipart 上传文件。

02 · 模型能力差异

能力	gpt-image-2	grok-imagine / -image / -image-quality
文生图	支持	支持
图生图 / 编辑	支持	支持（编辑模型 `grok-imagine-edit`）
参考图片数	按分组：#127 明确 10 张；#75 代理限制 15 张，其余以专项文档为准	单张
尺寸分档	按最长边划分 1K / 2K / 4K	按所选模型的 `size` 规则处理
高级参数 `quality` / `style` / `background`	支持	按所选模型支持范围处理

模型别名

grok-imagine 是可直接使用的兼容模型名；也可显式填写 grok-imagine-image 或 grok-imagine-image-quality。
图生图 / 编辑使用 grok-imagine-edit。

03 · 生图比例（size）如何指定

比例通过 OpenAI 标准字段 size 以 宽x高 像素指定，比例即 宽:高。系统根据 size 生成图片，并按对应档位计费。

格式：宽x高，例如 1536x1024（3:2）、1024x1024（1:1）。分隔符支持 x、X、×。
不传 size 时使用所选模型的默认比例（通常 1:1）。

最长边分档（仅适用于 gpt-image-2）

本站拟按最长边 max(宽, 高) 划分档位。官方三个常用 1K 尺寸，以及最长边不超过 1536 的自定义尺寸，均归为 1K。

档位	最长边规则	常用比例与尺寸
1K	`max(宽, 高) ≤ 1536`	`1024x1024`、`1536x1024`、`1024x1536`
2K / 超分	`1536 < max(宽, 高) < 3840`	`2048x2048`、`2048x1152`、`1152x2048`
4K / 超分	`max(宽, 高) ≥ 3840`	`3840x2160`、`2160x3840`

自定义尺寸约束

宽高必须是 16 的倍数。
任一边 ≤ 3840。
宽高比 ≤ 3:1。
总像素 655,360 ~ 8,294,400。

注意：1024x1536 的最长边为 1536，属于 1K；2048x768 的最长边为 2048，属于 2K。该拟定规则只作用于 gpt-image-2，Grok 图片模型继续按各自的 size 规则处理。

规则状态：gpt-image-2 的计费已统一采用此最长边规则：≤1536 为 1K，1537–3839 为 2K，≥3840 为 4K；Grok 图片模型继续按各自规则处理。

04 · 通用字段规则

字段	必填	说明
`model`	是	`gpt-image-2`、`grok-imagine`、`grok-imagine-image`、`grok-imagine-image-quality`（编辑用 `grok-imagine-edit`）。
`prompt`	文生图必填	图片内容描述；图生图建议提供，部分模型允许只传图片。
`size`	否	`宽x高` 像素，见「03 · 生图比例」。默认使用所选模型的默认比例。
`n`	否	生成张数，默认 1。
`quality`	否	auto / high / medium / low，默认 auto（gpt-image-2 支持）。
`style`	否	auto / vivid / natural，默认 auto。
`background`	否	auto / transparent / opaque，默认 auto。
`output_format`	否	png / jpeg / webp，默认 png。
`response_format`	否	`b64_json` 或 `url`；不传时默认返回 base64。
`image` / `images`	图生图必填	输入图片；multipart 上传文件，或 JSON 中的 data URL 数组。gpt-image-2 按分组：#127 明确 10 张；#75 代理限制 15 张，其余以专项文档为准。

05 · 文生图示例（gpt-image-2）

代码

curl -X POST "https://yyds.seqnode.com/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫坐在窗台上，午后阳光",
    "size": "1536x1024",
    "n": 1,
    "quality": "high",
    "output_format": "png",
    "response_format": "b64_json"
  }'

06 · 图生图 / 编辑示例

multipart 上传输入图片与掩码（可选）：

代码

curl -X POST "https://yyds.seqnode.com/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=把背景换成海边日落" \
  -F "image=@input.png" \
  -F "size=1536x1024" \
  -F "response_format=b64_json"

多参考图：重复提交 image 字段，gpt-image-2 按分组：#127 明确 10 张；#75 代理限制 15 张，其余以专项文档为准。

07 · Grok 图片模型示例

7.1 文生图（grok-imagine）

代码

curl -X POST "https://yyds.seqnode.com/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine",
    "prompt": "A red apple on a white background",
    "size": "1024x1024",
    "n": 1
  }'

grok-imagine 可直接用于文生图；也可填写 grok-imagine-image 或 grok-imagine-image-quality。

7.2 图生图 / 编辑（grok-imagine-edit）

代码

curl -X POST "https://yyds.seqnode.com/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=grok-imagine-edit" \
  -F "prompt=edit this private image" \
  -F "image=@input.png"

08 · 响应格式

统一为 OpenAI Images 响应，图片位于 data 数组：

代码

{
  "created": 1700000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUg...",
      "revised_prompt": "..."
    }
  ]
}

response_format=b64_json（默认）返回 data[].b64_json。
response_format=url 返回 data[].url。

09 · 常见错误检查

返回 400 / 403 时优先检查：

是否遗漏 model。
API Key 是否属于已启用生图的分组。
size 是否合法：宽高为 16 的倍数、任一边 ≤ 3840、宽高比 ≤ 3:1、总像素在 655,360 ~ 8,294,400 之间。
图生图是否遗漏 image，或参考图是否超过模型上限（gpt-image-2 以分组专项文档为准）。
是否把编辑请求发到了 /v1/images/generations（编辑必须用 /v1/images/edits）。
quality / style / background 是否为合法枚举值。