Endpoint

POST /v1/images

Generate an image from a text prompt, optionally guided by up to four reference images (as URLs or uploaded files).

Request body

{
  "prompt": "a stylized treasure chest, low-poly, 3/4 view",
  "model": "nano-banana",
  "aspectRatio": "1:1",
  "referenceImages": []
}

Field	Type	Required	Description
`prompt`	`string`	Yes	Text description. Up to 5,000 characters.
`model`	`string`	No	Engine identifier, e.g. `nano-banana`, `gpt-image-2`. Omit for the default. See `GET /v1/models?category=image`.
`aspectRatio`	`string`	No	e.g. `1:1`, `16:9`, `9:16`. Supported ratios are per-model.
`referenceImages`	`string[]`	No	Up to 4 `http/https` image URLs used as visual guidance.
`license`	`string`	No	Output license. Defaults to `all-rights-reserved` (private).

To upload reference files directly, send multipart/form-data with the same fields plus referenceFiles (≤ 4 files, ≤ 20 MB each — png, jpeg, webp, or gif).

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, game asset","model":"nano-banana","aspectRatio":"1:1"}'

Response

The create call returns the asset with taskStatus: 0:

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

Poll GET /v1/assets/{id} until taskStatus is 2 (succeeded); the image URL is in files.image (a short-lived signed URL):

{
  "success": true,
  "data": {
    "id": "019...",
    "taskStatus": 2,
    "type": "image",
    "files": { "image": "https://...signed.png", "thumbnail": "https://...signed.png" }
  }
}

See the overview for the taskStatus values and error format.