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–50 credits

Parameters

ParameterDescription
promptREQUIRED
string		The image prompt. Up to 5,000 characters.
modelOPTIONAL
string		Which image model — e.g. nano-banana, gpt-image-2. Omit for the default. List: GET /v1/models?category=image.
aspectRatioOPTIONAL
string		e.g. 1:1, 16:9, 9:16. Supported ratios are per-model — see supportedAspectRatios in GET /v1/models.
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.
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.

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"