Generate

Text → Image

POST/v1/images

Generate an image from a text prompt, optionally guided by up to four reference images.

Async returns an id — poll or webhookTypical ~10–40sCost ≈15–200 credits per image

Parameters

Parameter	Description
promptREQUIRED string	The image prompt. Up to 4,000 characters (longer prompts are rejected with `400` before any credits are spent).
modelOPTIONAL string	Which image model — e.g. `nano-banana`, `gpt-image-2`. Omit for the default. List: `GET /v1/models?category=image`.
aspectRatioOPTIONAL string	`W:H`, e.g. `1:1`, `16:9`, `9:16`, `21:9`. Supported ratios are per-model — see `supportedAspectRatios` in `GET /v1/models?category=image`. Nano Banana models forward the ratio to the vendor as-is, so a value outside their list is rejected with `400` before any credits are spent. `gpt-image-*` accepts any well-formed ratio and buckets it to the nearest of its three output sizes (1024×1024 / 1024×1536 / 1536×1024).
referenceImagesOPTIONAL string[]	Up to 4 image URLs used as visual guidance. Local files go in the multipart `referenceFiles` part (≤20 MB each). `nano-banana` is recommended for reference edits.
countOPTIONAL integer	How many images to generate from this request, `1`–`4` (default `1`). Each image is billed separately — see Several images in one call.

Transparent background There's no transparent-background parameter — generated images come back with a solid (usually white or light gray) background. If you need an alpha cut-out, remove the background client-side (a background-removal library, or a flood-fill from the corners) as a post-step.

Request

request

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;

Response

response · 200

{ "success": true, "data": { "id": "019…", "taskStatus": 0, "type": "image" } }

Poll GET /v1/assets/{id} until taskStatus is 2; the image URL lands in files.image.

Several images in one call

Add count (1–4) to get that many images of the same prompt from one request — for example four nano-banana-2.1 variations. The top-level fields are still the first image, so code written for one image keeps working. assets lists every image in order, and they share one batchId. Poll each id (with a callbackUrl, you get one webhook per image).

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}'

response · 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", … } ]
} }

Credits — each image is charged separately: per-image price × count (four 1K nano-banana-2.1 images = 240 credits), and that total counts toward the key's daily safety limit. If the balance can't cover every image, nothing is charged and the 402 carries the total required. An image that fails later is refunded on its own; the others are unaffected. In the rare case that some (not all) images can't be queued, the call still succeeds and lists every image in assets; the ones that couldn't be queued are failed and refunded right away — polling their id shows taskStatus: 3. If none can be queued, the call returns an error.
Concurrency — the request needs count free image slots (Free 1 · Starter 3 · Pro 6 · Max 15), so the Free plan generates one image per request. A count above your plan's limit is rejected with 400 — retrying won't help. Within the limit but with too many jobs already running, it's 429 (13002) — retry once a slot frees. Either way nothing is charged, and for count of 2 or more the error details include requested.
Rate limit — the 120 requests/min limit counts requests, not images.
Over multipart, send count as a form field like the others.

Reference images (local files)

Send multipart/form-data with up to 4 referenceFiles parts (each ≤20 MB) instead of hosted referenceImages URLs — the other fields become form fields.

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"