Docs/图片生成 API

IMG

图片生成 API

通过统一的接口调用多家顶级图片生成模型，支持文生图、图片编辑、蒙版修复和多图融合。

快速开始

从控制台获取 API 密钥

选择下方图片生成模型

发送 POST 请求创建任务

轮询 GET 请求获取图片链接

认证方式

所有请求需在 Header 中携带 Bearer Token：

Authorization: Bearer YOUR_API_KEY

接口端点

POST/api/v1/images/generations

创建图片生成任务

GET/api/v1/images/generations?task_id=xxx

查询任务状态并获取图片链接

API 参考

选择模型提供商查看对应的参数和示例

OpenAI

GPT Image 2 Lite

OpenAI gpt-image-2 通过 yunwu.ai 接入的最便宜通道。同步 API:同一端点自动在 /v1/images/generations(文生图) 和 /v1/images/edits(图生图 + mask) 之间路由。支持 1K / 2K / 4K 输出与 quality 控制,内置 moderation=low,扁平 $0.04/张。

可用模型

GPT Image 2 Lite

gpt-image-2-lite

$0.04/张

同步 · 平台最低价 · 1K/2K/4K · 图生图

请求参数

── 请求参数 — POST /api/v1/images/generations ──

Content-Type: application/json

model必填

string必须为 "gpt-image-2-lite"

prompt必填

string图片描述或编辑指令。多图编辑可用 "image 1"、"image 2" 引用具体参考图

size

string"auto"(默认) / 1K(1024x1024、1536x1024、1024x1536) / 2K(2048x2048、2048x1152、1152x2048) / 4K(3840x2160、2160x3840)。需满足:边长 ≤ 3840,均为 16 的倍数,长短比 ≤ 3:1

quality

string"low" / "medium"(默认) / "high" / "auto"

output_format

string"png" / "jpeg" / "webp"。映射到上游 format 字段

image_url

string单张参考图 URL,传入则走 /v1/images/edits 通道

image_urls

string[]多张参考图 URL(最多 10 张),用于多图融合

image_base64

stringBase64 或 data URI 参考图(本地文件用),自动以 multipart 转发

image_mime_type

stringimage_base64 对应的 MIME,默认 image/png

mask_url

string遮罩图 URL,白色区域被重新生成(inpainting)

mask_base64

stringBase64 遮罩图,白色区域被重新生成

integer生成数量 1-10(默认 1),按张数线性扣费

callback_url

string任务完成后的回调 URL

── 响应字段 — 2xx ──

application/json

code

integer200 表示成功;其他见错误码表

data.taskId

string任务 ID

data.state

stringcompleted / failed(同步,创建后状态通常已是 completed)

data.resultUrls

string[]R2 托管的图片 URL

data.failMsg

string失败原因(state=failed 时)

data.costTime

integer耗时(ms)

说明

-同步模型:POST 创建任务时通常已经返回 completed 与 resultUrls,无需额外轮询;但仍可走 GET ?task_id= 兼容,响应结构一致。
-端点自动路由:只传 prompt → /v1/images/generations(JSON);携带 image_url / image_urls / image_base64 / mask → /v1/images/edits(multipart)
-尺寸支持:1K / 2K / 4K(详见 size 参数)。仅当超出上游硬规则(边长 > 3840、维度非 16 倍数、长短比 > 3:1、像素总数越界)时返 400。
-内置重试:对 yunwu nginx 的瞬时 5xx(< 5s 返 HTML 500/502/503/504)自动最多重试 3 次,1s/2s 退避,通常用户感知不到
-失败不扣费:state=failed 的任务不计入账单,可安全重试
-扁平定价:$0.04/张,与 size、quality、参考图数量无关。这是平台上 GPT Image 2 系列的最低价。

代码示例

# ─── 1. Text-to-image (1024x1024, low quality, jpeg) ──────
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-lite",
    "prompt": "A children'"'"'s book drawing of a veterinarian using a stethoscope to listen to the heartbeat of a baby otter.",
    "size": "1024x1024",
    "quality": "low",
    "output_format": "jpeg"
  }'

# Response (sync — image URL returned directly):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "completed", "resultUrls": ["https://r2.apimodels.app/..."] } }


# ─── 2. Image editing with a reference URL ────────────────
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-lite",
    "prompt": "Change the season to winter with snow",
    "image_url": "https://example.com/landscape.jpg",
    "size": "1536x1024"
  }'


# ─── 3. Multi-image fusion via base64 ─────────────────────
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-lite",
    "prompt": "Combine the model from image 1 with the outfit from image 2",
    "image_base64": "BASE64_IMAGE_1",
    "image_urls": ["https://example.com/outfit.jpg"],
    "size": "1024x1536"
  }'


# ─── 4. Mask inpainting (regenerate masked region only) ───
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-lite",
    "prompt": "Replace the logo on the box",
    "image_base64": "BASE64_IMAGE",
    "mask_base64": "BASE64_MASK_PNG",
    "size": "1024x1024"
  }'


# ─── 5. Poll status (lite is sync, this returns completed) ─
curl "https://apimodels.app/api/v1/images/generations?task_id=TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应格式

创建任务响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "pending"
  }
}

成功响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "completed",
    "resultUrls": ["https://r2.apimodels.app/images/xxx.jpeg"],
    "createTime": 1705123450000,
    "completeTime": 1705123465000
  }
}

失败响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "failed",
    "failMsg": "Content policy violation"
  }
}

回调通知 (callback_url)

在创建请求中传入 callback_url 后，任务进入 completed 或 failed 终态时，我们会向该地址发起一次 HTTP POST。请求头仅包含 Content-Type: application/json，无签名头。失败会自动重试 3 次（指数退避 1s/2s/4s，单次超时 10s）；如果仍未成功，后台会在 30 分钟内继续补偿重发，直到接收端返回 2xx。

Payload 结构

POST {your callback_url}
Content-Type: application/json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "model": "<provider>/<model_name>",
    "state": "completed" | "failed",
    "param": "<JSON string>",            // request params, JSON.parse once
    "resultJson": "<JSON string> | null", // result object, JSON.parse once
    "failCode": null | "string",
    "failMsg": null | "string",
    "costTime": 12345,                    // duration in ms
    "completeTime": 1705123465000,        // ms epoch
    "createTime": 1705123450000           // ms epoch
  }
}

注意：data.param 与 data.resultJson 都是 JSON 字符串，使用前必须 JSON.parse 一次才能拿到对象。

图片任务：JSON.parse(data.resultJson) 后的结构

{
  "resultUrls": [
    "https://r2.apimodels.app/images/xxx.png"
  ]
}

resultUrls 为已上传至 Cloudflare R2 的图片 URL 数组。多图模型（如 SparkPix Image Edit、n>1 的 GPT Image 2 Lite）会返回多个；state=failed 时通常为 null 或 {"resultUrls":[]}，请不要假设一定有链接。

Node.js 接收示例

app.post('/webhook/image', express.json(), (req, res) => {
  const { taskId, state, param, resultJson, failMsg } = req.body.data
  if (state === 'completed') {
    const { resultUrls } = JSON.parse(resultJson)
    console.log('image ready', taskId, resultUrls[0])
  } else {
    console.warn('image failed', taskId, failMsg)
  }
  res.status(200).end()                 // must be 2xx, otherwise we retry
})

注意事项

- 每个任务只在送达 2xx 后停止重发，已送达后不会重复推送。
- 当前不附带签名头。建议在 callback_url 路径中放置一段随机 token，由你在收到回调时自行校验来源。
- GPT Image 2 Lite 与 SparkPix 是同步模型，POST 创建时通常已直接返回结果，回调对它们意义不大；其它模型（gpt-image-2、gpt-image-2-beta、gemini-image、kling-image 等）才是异步任务，建议生产环境优先使用回调而非轮询。
- 回调地址建议使用公网 HTTPS 端点，并且能在 10 秒内返回响应（单次超时为 10s）。

任务状态

pending任务已排队，等待处理

processing图片生成中

completed生成成功，可获取图片链接

failed生成失败

错误码

400请求参数错误或缺失

401API 密钥无效

402积分不足

404任务 ID 不存在

500服务器内部错误

注意事项

-图片文件保存 7 天，请及时下载
-生成失败不扣费
-建议每 2-3 秒轮询一次任务状态
-生产环境建议使用 callback_url 避免轮询
-请妥善保管 API 密钥

在 Playground 中试用获取 API 密钥

Docs/图片生成 API

IMG

图片生成 API

通过统一的接口调用多家顶级图片生成模型，支持文生图、图片编辑、蒙版修复和多图融合。

快速开始

从控制台获取 API 密钥

选择下方图片生成模型

发送 POST 请求创建任务

轮询 GET 请求获取图片链接

认证方式

所有请求需在 Header 中携带 Bearer Token：

Authorization: Bearer YOUR_API_KEY

接口端点

POST/api/v1/images/generations

创建图片生成任务

GET/api/v1/images/generations?task_id=xxx

查询任务状态并获取图片链接

API 参考

选择模型提供商查看对应的参数和示例

OpenAI

GPT Image 2 Lite

可用模型

GPT Image 2 Lite

gpt-image-2-lite

$0.04/张

同步 · 平台最低价 · 1K/2K/4K · 图生图

请求参数

── 请求参数 — POST /api/v1/images/generations ──

Content-Type: application/json

model必填

string必须为 "gpt-image-2-lite"

prompt必填

string图片描述或编辑指令。多图编辑可用 "image 1"、"image 2" 引用具体参考图

size

string"auto"(默认) / 1K(1024x1024、1536x1024、1024x1536) / 2K(2048x2048、2048x1152、1152x2048) / 4K(3840x2160、2160x3840)。需满足:边长 ≤ 3840,均为 16 的倍数,长短比 ≤ 3:1

quality

string"low" / "medium"(默认) / "high" / "auto"

output_format

string"png" / "jpeg" / "webp"。映射到上游 format 字段

image_url

string单张参考图 URL,传入则走 /v1/images/edits 通道

image_urls

string[]多张参考图 URL(最多 10 张),用于多图融合

image_base64

stringBase64 或 data URI 参考图(本地文件用),自动以 multipart 转发

image_mime_type

stringimage_base64 对应的 MIME,默认 image/png

mask_url

string遮罩图 URL,白色区域被重新生成(inpainting)

mask_base64

stringBase64 遮罩图,白色区域被重新生成

integer生成数量 1-10(默认 1),按张数线性扣费

callback_url

string任务完成后的回调 URL

── 响应字段 — 2xx ──

application/json

code

integer200 表示成功;其他见错误码表

data.taskId

string任务 ID

data.state

stringcompleted / failed(同步,创建后状态通常已是 completed)

data.resultUrls

string[]R2 托管的图片 URL

data.failMsg

string失败原因(state=failed 时)

data.costTime

integer耗时(ms)

说明

-同步模型:POST 创建任务时通常已经返回 completed 与 resultUrls,无需额外轮询;但仍可走 GET ?task_id= 兼容,响应结构一致。
-端点自动路由:只传 prompt → /v1/images/generations(JSON);携带 image_url / image_urls / image_base64 / mask → /v1/images/edits(multipart)
-尺寸支持:1K / 2K / 4K(详见 size 参数)。仅当超出上游硬规则(边长 > 3840、维度非 16 倍数、长短比 > 3:1、像素总数越界)时返 400。
-内置重试:对 yunwu nginx 的瞬时 5xx(< 5s 返 HTML 500/502/503/504)自动最多重试 3 次,1s/2s 退避,通常用户感知不到
-失败不扣费:state=failed 的任务不计入账单,可安全重试
-扁平定价:$0.04/张,与 size、quality、参考图数量无关。这是平台上 GPT Image 2 系列的最低价。

代码示例

# ─── 1. Text-to-image (1024x1024, low quality, jpeg) ──────
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-lite",
    "prompt": "A children'"'"'s book drawing of a veterinarian using a stethoscope to listen to the heartbeat of a baby otter.",
    "size": "1024x1024",
    "quality": "low",
    "output_format": "jpeg"
  }'

# Response (sync — image URL returned directly):
# { "code": 200, "msg": "success", "data": { "taskId": "clxxx", "state": "completed", "resultUrls": ["https://r2.apimodels.app/..."] } }


# ─── 2. Image editing with a reference URL ────────────────
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-lite",
    "prompt": "Change the season to winter with snow",
    "image_url": "https://example.com/landscape.jpg",
    "size": "1536x1024"
  }'


# ─── 3. Multi-image fusion via base64 ─────────────────────
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-lite",
    "prompt": "Combine the model from image 1 with the outfit from image 2",
    "image_base64": "BASE64_IMAGE_1",
    "image_urls": ["https://example.com/outfit.jpg"],
    "size": "1024x1536"
  }'


# ─── 4. Mask inpainting (regenerate masked region only) ───
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-lite",
    "prompt": "Replace the logo on the box",
    "image_base64": "BASE64_IMAGE",
    "mask_base64": "BASE64_MASK_PNG",
    "size": "1024x1024"
  }'


# ─── 5. Poll status (lite is sync, this returns completed) ─
curl "https://apimodels.app/api/v1/images/generations?task_id=TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

响应格式

创建任务响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "pending"
  }
}

成功响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "completed",
    "resultUrls": ["https://r2.apimodels.app/images/xxx.jpeg"],
    "createTime": 1705123450000,
    "completeTime": 1705123465000
  }
}

失败响应

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "failed",
    "failMsg": "Content policy violation"
  }
}

回调通知 (callback_url)

Payload 结构

POST {your callback_url}
Content-Type: application/json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "model": "<provider>/<model_name>",
    "state": "completed" | "failed",
    "param": "<JSON string>",            // request params, JSON.parse once
    "resultJson": "<JSON string> | null", // result object, JSON.parse once
    "failCode": null | "string",
    "failMsg": null | "string",
    "costTime": 12345,                    // duration in ms
    "completeTime": 1705123465000,        // ms epoch
    "createTime": 1705123450000           // ms epoch
  }
}

注意：data.param 与 data.resultJson 都是 JSON 字符串，使用前必须 JSON.parse 一次才能拿到对象。

图片任务：JSON.parse(data.resultJson) 后的结构

{
  "resultUrls": [
    "https://r2.apimodels.app/images/xxx.png"
  ]
}

Node.js 接收示例

app.post('/webhook/image', express.json(), (req, res) => {
  const { taskId, state, param, resultJson, failMsg } = req.body.data
  if (state === 'completed') {
    const { resultUrls } = JSON.parse(resultJson)
    console.log('image ready', taskId, resultUrls[0])
  } else {
    console.warn('image failed', taskId, failMsg)
  }
  res.status(200).end()                 // must be 2xx, otherwise we retry
})

注意事项

- 每个任务只在送达 2xx 后停止重发，已送达后不会重复推送。
- 当前不附带签名头。建议在 callback_url 路径中放置一段随机 token，由你在收到回调时自行校验来源。
- GPT Image 2 Lite 与 SparkPix 是同步模型，POST 创建时通常已直接返回结果，回调对它们意义不大；其它模型（gpt-image-2、gpt-image-2-beta、gemini-image、kling-image 等）才是异步任务，建议生产环境优先使用回调而非轮询。
- 回调地址建议使用公网 HTTPS 端点，并且能在 10 秒内返回响应（单次超时为 10s）。

任务状态

pending任务已排队，等待处理

processing图片生成中

completed生成成功，可获取图片链接

failed生成失败

错误码

400请求参数错误或缺失

401API 密钥无效

402积分不足

404任务 ID 不存在

500服务器内部错误

注意事项

-图片文件保存 7 天，请及时下载
-生成失败不扣费
-建议每 2-3 秒轮询一次任务状态
-生产环境建议使用 callback_url 避免轮询
-请妥善保管 API 密钥

在 Playground 中试用获取 API 密钥