API 参考

图片生成 API

一个接口覆盖所有模式 — 单张生成、盲盒网格、多提示词拼图。Bearer API Key 认证，同步返回结果。

接口

主接口

POSThttps://gridbulk.com/api/v1/generate

异步 + 查询 + 历史

POSThttps://gridbulk.com/api/v1/generate/async

GEThttps://gridbulk.com/api/v1/generate/jobs/{jobId}

GEThttps://gridbulk.com/api/v1/generate/history?page=1&limit=20

POST

请求字段

POST https://gridbulk.com/api/v1/generate

字段	类型	可选值	描述
`model`	enum	gemini \| gpt-image-2	生成模型。gemini（默认）使用 Google Gemini；gpt-image-2 使用 OpenAI GPT Image 2。不同模型支持的比例不同。
`mode`required	enum	single \| gacha \| compose	生成模式。single 单张；gacha 用一个提示词填充网格；compose 每格一个提示词。
`ratio`required	enum	1:1 · 3:2 · 2:3 · 4:3 · 3:4 · 16:9 · 9:16 · 4:5 · 5:4 · 21:9 · 2:1 · 9:21 · 1:3 · 3:1 · 1:2	输出宽高比。Gemini 不支持 9:21/1:3/3:1/1:2；GPT Image 2 不支持 2:1。
`resolution`required	enum	1k · 2k · 4k	输出分辨率等级。
`gridCols`	integer	1–4	网格列数。gacha / compose 模式必填，single 模式忽略。
`gridRows`	integer	1–4	网格行数。gacha / compose 模式必填，single 模式忽略。
`prompts`required	string[]	至少 1 项	提示词数组。single 取 [0]；gacha 将 [0] 填充网格；compose 每格一个。
`references`	string[]	URL 字符串	可选的参考图 URL 列表，用于风格引导。

请求示例

cURL

curl -X POST https://gridbulk.com/api/v1/generate \  -H "Authorization: Bearer sk_live_your_key" \  -H "Content-Type: application/json" \  -d '{    "mode": "compose",    "ratio": "1:1",    "resolution": "1k",    "gridCols": 3,    "gridRows": 3,    "prompts": [      "博物馆陈列感的人像系列",      "赛博朋克城市夜景",      "水彩风格静物画"    ]  }'

响应

返回生成图片的预签名 URL、积分消耗和余额。

JSON

{  "images": [    {      "url": "https://cdn.gridbulk.com/gen/abc...?X-Amz-Expires=3600",      "key": "gen/abc.png",      "width": 1024,      "height": 1024,      "expiresAt": "2026-04-16T12:00:00Z"    }  ],  "creditsUsed": 1,  "creditsRemaining": 120}

异步请求

cURL

curl -X POST https://gridbulk.com/api/v1/generate/async \  -H "Authorization: Bearer sk_live_your_key" \  -H "Content-Type: application/json" \  -d '{    "mode": "gacha",    "ratio": "1:1",    "resolution": "1k",    "gridCols": 2,    "gridRows": 2,    "prompts": ["四种不同风格的猫"]  }'

异步响应

立即返回 jobId。轮询 GET /api/v1/generate/jobs/{jobId} 查询状态。

JSON

{  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "status": "pending"}

轮询任务状态

轮询直到 status 变为 completed 或 failed。

cURL

curl https://gridbulk.com/api/v1/generate/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \  -H "Authorization: Bearer sk_live_your_key"

响应（进行中）

JSON

{  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "status": "processing"}

响应（已完成）

JSON

{  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "status": "completed",  "images": [    {      "url": "https://cdn.gridbulk.com/gen/cat-1.png?X-Amz-Expires=3600",      "key": "gen/cat-1.png",      "width": 512,      "height": 512,      "expiresAt": "2026-04-16T12:00:00Z"    },    {      "url": "https://cdn.gridbulk.com/gen/cat-2.png?X-Amz-Expires=3600",      "key": "gen/cat-2.png",      "width": 512,      "height": 512,      "expiresAt": "2026-04-16T12:00:00Z"    }  ]}

错误响应

401 — API Key 缺失或无效：检查 Authorization 请求头。 402 — 积分不足：在定价页充值后重试。 429 — 触发限流：等待 Retry-After 指定的间隔后重试。 422 — 参数无效：按错误信息中标记的字段修正。

JSON

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Retry after 30 seconds."  }}