Base URL

https://api.picoberry.ai

All endpoints are versioned under /v1. The API accepts JSON (and multipart/form-data where files are uploaded), returns JSON, and uses standard HTTP status codes.

Authentication

Every request authenticates with an API key, sent in either header:

Authorization: Bearer pb_live_xxxxxxxxxxxx

x-api-key: pb_live_xxxxxxxxxxxx

The API is available to paying customers — see Authentication.

Response format

Every response is wrapped in a { success, data } envelope:

{ "success": true, "data": { /* ... */ } }

Errors return success: false with an error object:

{
  "success": false,
  "error": {
    "code": 1001,
    "message": "Missing API key. Send \"Authorization: Bearer pb_...\" or \"x-api-key\" header.",
    "httpStatus": 401
  }
}

Status	Meaning
`400`	Validation error — bad/missing parameter, unsupported model/image.
`401`	Missing, invalid, or revoked API key (`code 1001`).
`403`	Account not entitled to the API, or insufficient credits.
`404`	Asset/collection not found, or not owned by your account.
`429`	Rate limit exceeded (`code 10003`).

Async generation pattern

Generation is asynchronous. A create call returns immediately with an asset id and taskStatus: 0; you then poll or await a webhook.

POST /v1/images (or /v1/models/from-text, /v1/models/from-image, …) returns { "id": "019...", "taskStatus": 0 }.
Poll GET /v1/assets/{id} until taskStatus is 2 (succeeded) or 3 (failed).
On success, the output URLs are in files (short-lived signed URLs).

taskStatus values:

Value	Meaning
`0`	Queued
`1`	Processing
`2`	Succeeded
`3`	Failed

Poll on a sensible interval (e.g. every 3–5 s) with backoff, or register a callbackUrl to be pushed the result. A 3D generation typically takes a few minutes; an image, a few seconds.

Rate limits

Limit	Scope	On exceed
240 req / min	per client IP	`429` with `error.code: 10003`
120 req / min	per user (generation `POST`s)	`429` with `error.code: 10003`

There is no per-request idempotency key yet — retry a create call only when you didn't receive a response, or you may produce a duplicate generation.

Generation spends credits from your unified wallet. Credits are deducted when a job is accepted and automatically refunded if generation fails. Fetch your live balance with GET /v1/credits; per-model cost is listed by GET /v1/models.