批量生图 API

一次 HTTP 调用就能把一组提示词变成一整批图片。为脚本、流水线和 AI agent 而建——提交后轮询到完成，再下载结果。

快速开始

在控制台侧边栏「开发者 → API 密钥」创建密钥，并写入环境变量 BULKIMAGEN_API_KEY。
调用 GET /v1/models 选择模型，读取它的积分单价。
用 POST /v1/batches 提交提示词。积分在此刻立即扣除。
轮询 GET /v1/batches/{id} 直到 batch.done 为 true，然后下载每个任务的 resultUrls。

curl -X POST https://bulkimagen.com/api/v1/batches \
  -H "Authorization: Bearer $BULKIMAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["a red fox in snow", "a red fox in autumn leaves"],
    "model": "nano-banana-pro",
    "aspectRatio": "16:9",
    "resolution": "1K",
    "countPerCombo": 4
  }'

# {"id":"b_9f2c…","total":8,"creditsCharged":40,"status":"pending"}

鉴权

把密钥放进 HTTP bearer 头：Authorization: Bearer bik_live_… 所有接口都需要。撤销后下一个请求就会立即失效。

三条要紧的规则

只在服务端使用。本接口不返回 CORS 头，因此密钥无法安全地用在浏览器或移动端。
完整密钥只在创建时显示一次。我们只保存哈希，无法找回。
如果密钥交给自动化 agent 持有，请设置每日积分上限——脚本失控时能把损失兜住。

接口一览

接口	作用
`GET /v1/models`	模型目录：各分辨率的积分单价，以及所有合法的比例 × 分辨率组合。
`GET /v1/me`	账户信息、积分余额、套餐限额，以及该密钥当天已用掉多少上限额度。
`POST /v1/batches`	创建批次。立即扣积分并返回，生图过程是异步的。
`GET /v1/batches`	按时间倒序列出批次，配游标翻页。
`GET /v1/batches/{id}`	单个批次及其全部任务、状态和结果图地址。轮询就用这个接口。
`POST /v1/uploads`	上传参考图，拿到可用于 refImages 的地址。免费，不扣积分。

请求参数

POST /v1/batches 的请求体。只有 prompts 和 model 是必填，其余都有默认值。

字段	类型	默认值	说明
`prompts`必填	string[]	—	一个或多个提示词，批次会在它们之间展开。
`model`必填	string	—	来自 GET /v1/models 的模型 key。
`aspectRatio`	string	"1:1"	画面比例，如 16:9。必须在所选分辨率下合法——以 resolutionsByRatio 为准。
`resolution`	"1K" \| "2K" \| "4K"	"1K"	分辨率档位，决定每张图的积分单价。
`countPerCombo`	1–20	1	每个提示词出几张；refMode 为 each 时是「每张参考图」出几张。
`refMode`	"none" \| "each" \| "combined"	"none"	参考图与提示词如何配对，见下方说明。
`refImages`	string[]	[]	POST /v1/uploads 返回的地址。refMode 不是 none 时必填。
`quality`	"auto" \| "low" \| "medium" \| "high"	"auto"	只有 supportsQuality 为 true 的模型才生效，其余会被忽略。
`background`	"transparent" \| "#RRGGBB"	"auto"	BETA，不保证每张都生效。可传 "transparent"、#RRGGBB 颜色值，或不传表示自动。只有 supportsBackground 为 true 的模型才生效。
`note`	string	null	自由文本备注，显示在后台的批次旁边。

参考图

先上传图片，再把返回的地址填进 refImages。上传免费——只有创建批次时才扣积分。

用 multipart form-data 把文件 POST 到 /v1/uploads，字段名 file 可重复。支持 PNG、JPEG、WebP、GIF，单张最大 10MB，每次最多 20 张。
把每个返回文件的 url 收集进 refImages 数组。
选一个 refMode。每个模型能接受的参考图数量不同，上限见上方模型表。

curl -X POST https://bulkimagen.com/api/v1/uploads \
  -H "Authorization: Bearer $BULKIMAGEN_API_KEY" \
  -F "file=@shirt.png" -F "file=@mug.png"

# {"files":[
#   {"url":"https://s.bulkimagen.com/refs/9a1c….png","name":"shirt.png"},
#   {"url":"https://s.bulkimagen.com/refs/4f7b….png","name":"mug.png"}]}

refMode 如何影响出图数量

refMode 决定提示词和参考图怎么配对，也就决定了这一批要为多少张图付费。

refMode	出图数量	适用场景
`none`	prompts × countPerCombo	纯文生图，不用参考图。
`each`	prompts × refImages × countPerCombo	每个提示词 × 每张参考图各出一份——比如把同一个提示词套到你的每张产品图上。
`combined`	prompts × countPerCombo	所有参考图都挂到每一张结果上——比如把多个素材融合进同一个场景。

each 会把出图数量乘以参考图张数。提交前请重新算一遍花费——这是批次意外贵出好几倍最常见的原因。

curl -X POST https://bulkimagen.com/api/v1/batches \
  -H "Authorization: Bearer $BULKIMAGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompts": ["product photo on a marble table"],
    "model": "nano-banana-pro",
    "refMode": "each",
    "refImages": [
      "https://s.bulkimagen.com/refs/9a1c….png",
      "https://s.bulkimagen.com/refs/4f7b….png"
    ],
    "countPerCombo": 2
  }'

# 1 prompt × 2 reference images × 2 = 4 images

轮询与下载

生图在后台进行。大约每 5 秒轮询一次批次，当 batch.done 为 true 时即全部结束。结果图地址是公开的，可直接下载、无需鉴权。失败的任务会自动退回积分。

curl https://bulkimagen.com/api/v1/batches/b_9f2c… \
  -H "Authorization: Bearer $BULKIMAGEN_API_KEY"

# {"batch":{"done":false,"counts":{"pending":6,"running":2,
#   "succeeded":0,"failed":0}, …},"tasks":[…]}

模型与价格

下表是每张图消耗的积分（按分辨率）。并非所有比例都支持所有分辨率——GET /v1/models 返回的 resolutionsByRatio 才是权威依据，传了非法组合会返回 size_not_allowed。

模型	每张图积分	最多参考图
`gpt-image-2`	1K 5 · 2K 10 · 4K 20	4
`nano-banana-2`	1K 4 · 2K 6 · 4K 10	4
`nano-banana-2-lite`	1K 3	4
`nano-banana-pro`	1K 5 · 2K 6 · 4K 10	4
`seedream-4-5`	2K 6 · 4K 6	4
`seedream-5-lite`	2K 5 · 4K 5	4
`seedream-5-pro`	1K 6 · 2K 12	4
`grok`	1K 4	1
`flux-2-pro`	1K 5 · 2K 6	8
`z-image`	1K 1	—

curl https://bulkimagen.com/api/v1/models \
  -H "Authorization: Bearer $BULKIMAGEN_API_KEY"

错误码

所有失败都返回下面这个结构。code 是稳定契约，请按它分支判断，不要匹配 message。标注「不可重试」的错误，在账户或请求发生改变前重试结果完全相同。

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits: this batch requires 40.",
    "details": { "required": 40 }
  }
}

错误码	HTTP	含义
`invalid_api_key`不可重试	401	密钥无法识别、已撤销或已过期。
`api_not_available_on_plan`不可重试	403	当前套餐不包含 API 访问。
`invalid_request`不可重试	400	请求体格式错误或缺少必填字段。
`unknown_model`不可重试	400	模型 key 不在目录中。
`size_not_allowed`不可重试	400	该比例在该分辨率下不可用。
`content_blocked`不可重试	400	提示词触发内容政策，请修改后再提交。
`prompt_too_long`不可重试	400	某条提示词超出该模型的长度上限，响应会指出是哪一条——请精简或拆分。
`insufficient_credits`不可重试	402	余额不足以支付本批次。
`daily_credit_cap_exceeded`不可重试	402	会超出该密钥的每日积分上限，每天 00:00 UTC 重置。
`batch_limit_exceeded`不可重试	403	单批张数超出套餐允许的上限。
`concurrent_limit_exceeded`	403	同时进行的批次过多，等一个结束再试。
`rate_limited`	429	请求过于频繁，请退避并遵守 Retry-After。
`internal_error`	500	服务端异常，可以重试。

套餐限额

套餐	API 密钥数	单批张数	并发批次
free	不支持 API	4	1
starter	2	10	1
studio	5	50	10
scale	10	100	20

让 AI agent 来调用

下面的完整参考是纯文本，专为 LLM 一次抓取读懂而写。把它交给你的 agent，或者安装 BulkImagen skill，让它照既定流程走——查模型、估算花费、向你确认、提交、轮询、下载。

完整参考（纯文本）OpenAPI 规范