图像生成调用指南

GPT Image 2.5 Sunburst / Flare、gpt-image-2-count、gpt-image-2 与 Gemini 绘图模型的调用示例，以及推荐的异步提交方式。

modelsok 提供多款 AI 绘图模型。基础地址 https://modelsok.com，使用 Authorization: Bearer <API Key> 鉴权。本页说明各模型的调用方式与实用建议。

可用模型

模型	说明	调用方式
`gpt-image-2.5-sunburst`	文生图，已验证 1024×1024 PNG 输出	OpenAI 兼容接口
`gpt-image-2.5-flare`	文生图，已验证 1024×1024 PNG 输出	OpenAI 兼容接口
`gpt-image-2-count`	文生图 / 图像编辑，按次计费；输出固定约 1.5MP，`size` 只取宽高比	OpenAI 兼容接口
`gpt-image-2`	OpenAI 图像模型，输出尺寸与请求完全一致，最高 3840×2160	OpenAI 兼容接口
`gemini-2.5-flash-image-preview`	Gemini 快速绘图	OpenAI 兼容接口 / Gemini 原生
`gemini-2.5-flash-image`	Gemini 快速绘图	Gemini 原生
`gemini-3.1-flash-image-preview`	Gemini 快速绘图	Gemini 原生
`gemini-3-pro-image-preview`	Gemini 高质量绘图	Gemini 原生

异步提交（推荐）

单张图片通常需要几十秒到两分多钟。同步调用时，连接要一直挂到出图为止，跨地区网络或 CDN 容易在中途断开（客户端常见 ReadError、超时或 HTTP 524），而此时生成可能已经成功并扣费。建议出图耗时较长的请求一律使用异步提交：提交后立即拿到任务 ID，再轮询结果。

异步提交同时适用于 /v1/images/generations（文生图）和 /v1/images/edits（图像编辑），JSON 请求和 multipart 文件上传请求都可以使用。用法只有一处不同：在请求 URL 后加上 ?async=true，请求体与同步调用完全一致。

提交任务

文生图（JSON）：

curl "https://modelsok.com/v1/images/generations?async=true" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "蓝色背景，一只橙色陶瓷机器人手捧向日葵，产品摄影风格",
    "n": 1,
    "size": "1024x1024"
  }'

图像编辑（multipart 上传本地参考图）：

curl "https://modelsok.com/v1/images/edits?async=true" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2-count" \
  -F "prompt=把杯身换成哑光黑，保持构图不变" \
  -F "image=@reference.png" \
  -F "size=1024x1536"

multipart 请求不要手动设置 Content-Type，由 curl / HTTP 客户端自动生成带 boundary 的请求头。

提交成功后会在约 1 秒内返回任务信息，id 即任务 ID：

{
  "id": "task_xxxxxxxx",
  "state": "queued",
  "progress": 0,
  "create_time": 1794211200,
  "update_time": 1794211200,
  "action": "generate",
  "data": { "images": null }
}

轮询结果

使用提交时的同一把 API Key 查询任务：

curl "https://modelsok.com/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

建议每隔 3–5 秒查询一次。state 的取值：

`state`	含义	处理方式
`queued`	已提交，排队中	继续轮询
`processing`	生成中	继续轮询（另见下方「需要人工核对」）
`succeeded`	生成成功	读取 `data.images`
`failed`	生成失败	读取顶层 `error`，费用自动退回

成功时的返回示例：

{
  "id": "task_xxxxxxxx",
  "state": "succeeded",
  "progress": 100,
  "create_time": 1794211200,
  "update_time": 1794211239,
  "action": "generate",
  "data": {
    "images": [{ "url": "/api/relay-temp-images/xxxxxxxx.png" }]
  },
  "usage": {
    "total_tokens": 430,
    "input_tokens": 232,
    "output_tokens": 198
  }
}

关于结果字段：

异步结果统一以图片链接 data.images[].url 返回，不返回 b64_json，结构与同步调用的 data[].b64_json 不同。
链接存放在哪里，取决于是否开启了自有存储：
- 已开启：结果图会转存到你自己的 OSS / R2，url 是你桶里的地址，同一任务每次查询返回同一链接。
- 未开启：url 是平台临时链接，通常是相对路径（例如 /api/relay-temp-images/…png），请先拼接 https://modelsok.com 再下载。链接约 48 小时内有效，每次查询可能返回不同的链接，都可以下载，请及时保存。
- 如果转存到你的桶失败（例如密钥失效、桶不可写），会自动回退为平台临时链接，不影响拿到结果。
图像编辑任务的 action 同样显示为 generate，这是正常现象，不代表请求被当成了文生图。
一个任务只扣一次费用。查询超时或网络中断时，继续用原任务 ID 查询即可，不要重新提交，否则会产生新的计费任务。

失败与退款

生成失败时 state 为 failed，错误详情在顶层 error.code / error.message 中（不在 data 里），data.images 为空。该任务已扣的费用会自动退回，无需联系客服。

{
  "id": "task_xxxxxxxx",
  "state": "failed",
  "progress": 100,
  "create_time": 1794211200,
  "update_time": 1794211230,
  "action": "generate",
  "data": { "images": null },
  "error": {
    "code": "错误码",
    "message": "错误说明"
  }
}

可以根据 error.message 调整请求（如提示词、参考图、尺寸）后重新提交。

需要人工核对的任务

极少数情况下，任务的 state 会一直停留在 processing，同时响应里出现了 error 字段，且 error.code 为 post_dispatch_ambiguous。这表示该任务的结果需要人工核对：

不要无限轮询，这类任务要经人工处理后才会有最终结果；
不要重新提交，以免重复计费；
请保留任务 ID 并联系客服处理。

已知限制

开启了“模型限制”的 API Key 可能在查询任务时收到 403“该令牌无权访问模型”，即使生成已成功。此类密钥请先使用同步调用；不要因此关闭正式密钥的权限限制，也不要重复提交已经创建的任务。该问题不是模型生成失败。

同步调用时，把客户端超时设为 300 秒并不能延长 CDN 的等待上限；遇到 524 时请改用异步提交。

GPT Image 2.5：Sunburst / Flare

两个模型使用相同的接口和鉴权方式，切换时仅需更换 model。2026-09-09 已分别验证两个模型的文生图请求；以下为已验证的最小参数组合。模型可见性与价格以账号的模型广场为准。

curl --max-time 300 https://modelsok.com/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "蓝色背景，一只橙色陶瓷机器人手捧向日葵，产品摄影风格",
    "n": 1,
    "size": "1024x1024"
  }'

使用 Flare 时，将 model 改为 gpt-image-2.5-flare。同步响应的 data[0].b64_json 为 Base64 图像数据，解码后可保存为 PNG；示例不传 response_format 或 quality。如需避免长连接超时，在 URL 后加 ?async=true 改为异步提交，用法见上文「异步提交（推荐）」。

这两个模型目前已验证的是单张 1024×1024 文生图。其他分辨率、画质档位以及两个型号的性能差异尚未在本指南中验证；下方 gpt-image-2 的尺寸上限、默认画质和价格倍率不适用于推断这两个模型。

gpt-image-2-count

按次计费的图像模型，支持文生图（/v1/images/generations）和图像编辑（/v1/images/edits），请求参数与 OpenAI 图像接口一致。

输出尺寸：固定约 1.5MP（150 万像素）。size 中的像素数会被忽略，只保留其宽高比，例如 1024x1536 与 2048x3072 得到的都是约 1.5MP 的 2:3 图片。
图像编辑：可以用 multipart 直接上传本地参考图（字段名 image），示例见上文「异步提交（推荐）」。
耗时：单张通常 30–140 秒，建议始终使用 ?async=true 异步提交，避免长连接在跨地区网络中被断开。
计费：每次生成扣固定额度，与输出尺寸无关；生成失败的异步任务会自动退款。

gpt-image-2

尺寸规则

输出尺寸严格等于请求的 size。size 需同时满足三个条件，否则接口会明确报错（不会静默返回其它尺寸）：

条件	不满足时的报错
宽、高都必须是 16 的倍数	`Width and height must both be divisible by 16`
总像素在 655,360 ~ 8,294,400 之间	`below / exceeds the current pixel budget`
最长边 ≤ 3840	`The longest edge must be less than or equal to 3840`

常用尺寸参考：

比例	可用 `size`
1:1	`1024x1024`、`2048x2048`
4:3 / 3:4	`1024x768`、`2048x1536` / `768x1024`、`1536x2048`
3:2 / 2:3	`1536x1024` / `1024x1536`
5:4 / 4:5	`1280x1024` / `1024x1280`
16:9 / 9:16	`2048x1152`、`3840x2160` / `1152x2048`、`2160x3840`
21:9	`2688x1152`

4096x4096 超出最长边限制会被拒绝。需要 4K 请使用 3840x2160。

画质档位

可选参数 quality，取值 low / medium / high，不传时默认为 low。档位同时影响画质、耗时与价格，建议按用途显式指定。

quality	相对价格	生成耗时（1024×1024）	建议用途
`low`（默认）	1×	约 26 秒	草稿、批量预览
`medium`	约 9×	约 43 秒	日常成品
`high`	约 36×	约 109 秒	最终交付

文生图

curl https://modelsok.com/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只吃竹子的小熊猫，扁平矢量风格",
    "size": "1024x1024",
    "quality": "medium"
  }'

图生图 / 图像编辑

/v1/images/edits 支持两种传图方式：用 JSON 在 image 字段传入公网可访问的图片 URL（传数组可提交多张参考图，最多 16 张，示例如下），或用 multipart 直接上传本地文件（示例见上文「异步提交（推荐）」）。耗时较长的请求建议在 URL 后加 ?async=true 异步提交，见上文「异步提交（推荐）」。

curl https://modelsok.com/v1/images/edits \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "把杯身换成哑光黑，保持构图不变",
    "image": "https://你的图床/reference.png",
    "size": "3840x2160",
    "quality": "medium"
  }'

gpt-image-2 不接受 response_format 参数，传入会返回 400 Unknown parameter: 'response_format'。结果固定以 b64_json（Base64 图像数据）返回。

返回示例：

{
  "created": 1780888000,
  "data": [{ "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." }]
}

Python 示例

import base64, requests

resp = requests.post(
    "https://modelsok.com/v1/images/edits",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "gpt-image-2",
        "prompt": "一只吃竹子的小熊猫，扁平矢量风格",
        "image": "https://你的图床/reference.png",
        "size": "2048x2048",
        "quality": "medium",
    },
    timeout=300,
)
data = resp.json()["data"][0]["b64_json"]
open("out.png", "wb").write(base64.b64decode(data))

图生图单次耗时通常 20–110 秒（随 quality 上升）。同步调用请把客户端超时设为不低于 300 秒；更推荐改用异步提交，查询超时时继续查询原任务，不要重复提交。

Gemini 系列

方式一：OpenAI 兼容接口

适用于 gemini-2.5-flash-image-preview。

curl https://modelsok.com/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image-preview",
    "prompt": "一只吃竹子的小熊猫，扁平矢量风格",
    "n": 1,
    "size": "1024x1024",
    "response_format": "b64_json"
  }'

建议使用 response_format: "b64_json"。默认 url 返回的是对象存储上的临时链接，可能在一段时间后失效、且偶有下载超时。用 b64_json 直接拿到图像数据，集成更稳定。该参数仅 Gemini 系列可用，gpt-image-2 不支持。

方式二：Gemini 原生接口

适用于全部 Gemini 绘图模型。注意路径带尾部斜杠。

curl "https://modelsok.com/v1beta/models/gemini-2.5-flash-image:generateContent/" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "一只蓝色卡通猫，白色背景" }] }]
  }'

注意：Gemini 原生接口返回的图片通常以 Markdown 图片链接的形式包含在文本里（位于 candidates[0].content.parts[].text，形如 ![image](https://...)），而非 inlineData。集成时需从文本中提取该 URL 再下载。如需直接拿到标准图像数据，请改用 gemini-2.5-flash-image-preview 的 OpenAI 兼容接口。

返回示例：

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{ "text": "![image](https://.../xxxx.png)" }]
    }
  }]
}

计费

gpt-image-2 按 token 用量计费，费用由输出尺寸（size）、画质档位（quality）和参考图尺寸共同决定——出图越大、档位越高，费用越高。gpt-image-2-count 按次计费（每次生成扣固定额度）；其余绘图模型有的按次、有的按用量计费，以「模型广场」展示为准。异步任务生成失败时，已扣费用自动退回。

具体单价以「模型广场」展示为准，价格随账号等级不同。

本页目录