文本 → 图像
POST/v1/images
通过文本提示词生成图像,还可使用最多 4 张参考图像来引导结果。
参数
| 参数 | 说明 |
|---|---|
| prompt必填 string | 图像提示词。最多 4,000 个字符(超出会在扣除积分之前以 400 拒绝)。 |
| model可选 string | 使用的图像模型。例如 nano-banana、gpt-image-2。省略则使用默认模型。列表:GET /v1/models?category=image。 |
| aspectRatio可选 string | W:H 格式,例如 1:1、16:9、9:16、21:9。支持的宽高比因模型而异,请参见 GET /v1/models?category=image 中的 supportedAspectRatios。Nano Banana 系列会将比例原样传给供应商,因此不在列表中的值会在扣除积分之前以 400 拒绝。gpt-image-* 接受任意格式正确的比例,并归并到三种输出尺寸(1024×1024 / 1024×1536 / 1536×1024)中最接近的一种。 |
| referenceImages可选 string[] | 用作视觉引导的图像 URL,最多 4 个。本地文件放入 multipart 的 referenceFiles 部分(每个 ≤20 MB)。参考图编辑推荐使用 nano-banana。 |
| count可选 integer | 本次请求生成的图像张数,1–4(默认 1)。每张单独计费,参见一次生成多张。 |
请求
请求
curl -X POST https://api.picoberry.ai/v1/images \
-H "Authorization: Bearer pb_live_xxx" \
-H "Content-Type: application/json" \
-d '{"prompt":"a low-poly wooden barrel","model":"nano-banana","aspectRatio":"1:1"}'r = requests.post("https://api.picoberry.ai/v1/images", headers=headers,
json={"prompt": "a low-poly wooden barrel", "model": "nano-banana"})
asset_id = r.json()["data"]["id"]const res = await fetch(`${BASE}/v1/images`, {
method: "POST", headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({ prompt: "a low-poly wooden barrel", model: "nano-banana" }),
});
const { id } = (await res.json()).data;响应
响应 · 200
{ "success": true, "data": { "id": "019…", "taskStatus": 0, "type": "image" } }轮询 GET /v1/assets/{id} 直到 taskStatus 变为 2;图像 URL 会出现在 files.image 中。
一次生成多张
加上 count(1–4),即可用同一提示词在一次请求中获得相应张数的图像,例如 4 张 nano-banana-2.1。顶层字段仍是第一张,因此为单张编写的代码可以照常运行。assets 按顺序列出所有图像,它们共享同一个 batchId。请分别轮询每个 id(设置 callbackUrl 时,每张图像各发送一次 webhook)。
curl -X POST https://api.picoberry.ai/v1/images \
-H "Authorization: Bearer pb_live_xxx" \
-H "Content-Type: application/json" \
-d '{"prompt":"a low-poly wooden barrel","model":"nano-banana-2.1","count":4}'响应 · 200
{ "success": true, "data": {
"id": "019…a0", "taskStatus": 0, "type": "image", "batchId": "019…b0",
"assets": [ { "id": "019…a0", … }, { "id": "019…a1", … }, { "id": "019…a2", … }, { "id": "019…a3", … } ]
} }- 积分 — 每张单独扣除:单张价格 ×
count(4 张 1Knano-banana-2.1= 240 credits),合计计入密钥的每日安全上限。余额不足以覆盖全部张数时不扣除任何积分,并在402中返回总的required。之后失败的图像只退还该张,其他图像不受影响。极少数情况下部分(并非全部)图像未能加入队列时,调用仍会成功,所有图像都会列在assets中;未能入队的图像会立即被标记为失败并退款,轮询其id时为taskStatus: 3。若一张都未能入队,调用会返回错误。 - 并发 — 需要有
count个空闲的图像槽位(Free 1 · Starter 3 · Pro 6 · Max 15),因此 Free 套餐每次请求只能生成 1 张。超过套餐上限的count会以400拒绝(重试也不会通过)。未超上限但因正在运行的任务导致槽位不足时返回429(13002),槽位空出后可重试。两种情况都不会扣费;count为 2 及以上时,错误 details 中包含requested。 - 速率限制 — 每分钟 120 次的限制按请求数计算,而不是按图像张数。
- 使用 multipart 时,
count也与其他值一样作为表单字段发送。
参考图像(本地文件)
可以发送 multipart/form-data,包含最多 4 个 referenceFiles 部分(每个 ≤20 MB),以替代托管的 referenceImages URL,其余字段将作为表单字段。
curl -X POST https://api.picoberry.ai/v1/images \
-H "Authorization: Bearer pb_live_xxx" \
-F "prompt=a low-poly wooden barrel" -F "model=nano-banana" \
-F "referenceFiles=@./ref1.png" -F "referenceFiles=@./ref2.png"