生成

文本 → 图像

POST/v1/images

通过文本提示词生成图像,还可使用最多 4 张参考图像来引导结果。

异步 返回 id,可轮询或使用 webhook通常 ~10–40s费用 每张 ≈15–200 credits

参数

参数说明
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", … } ]
} }

参考图像(本地文件)

可以发送 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"