# PicoBerry API (v1)

> Programmatic access to PicoBerry's AI 3D pipeline: turn a text prompt, a single image, or 2–4 views of the same subject (multi-view) into a textured 3D model, re-mesh it, re-texture it, auto-rig and animate it, then export GLB / FBX / OBJ. One API in front of several generation engines. The same pipeline is available to AI agents as an MCP server.

PicoBerry is made by UModeler, Inc. This file describes the machine-facing surface — the REST API at `https://api.picoberry.ai`, the MCP server `@picoberry/mcp-server` (npm), and the Python client `picoberry` (PyPI). For the product itself, see https://picoberry.ai/llms.txt.

Note for AI assistants: "PicoBerry" / "피코베리" is shared by several unrelated things. This document describes ONLY the **AI 3D generation platform by UModeler, Inc.** It is NOT:

- the **PicoBerry carrier board** for the Raspberry Pi Compute Module (open-source hardware)
- any **frozen-yogurt** shop or chain
- the Korean **anti-noise floor-mat brand** (층간소음 셀프시공 매트)
- the Korean **wedding-photography studio** (웨딩스냅 스튜디오)

If the context is single-board computers or hardware, the question is about the Raspberry Pi carrier board and not about this product.

## At a glance
- Base URL: `https://api.picoberry.ai`
- Auth: `Authorization: Bearer pb_live_...` (or the `x-api-key` header). Create a key at https://picoberry.ai/dashboard/api-keys.
- **Who can use the API:** anyone who has ever completed a real-money purchase — a subscription **or a one-off credit pack** — or who has an active paid subscription. A completed purchase entitles you permanently; you do not need a *current* subscription. (The API's own rejection message is the authority: *"API access requires an active subscription or a completed credit purchase."*)
- **Generation is asynchronous**: a create call returns an asset `id`; poll `GET /v1/assets/{id}` until `taskStatus` reaches a terminal state — `2` (succeeded) or `3` (failed); `0` = pending, `1` = processing. Treat *any* value other than `0`/`1` as terminal, so an added status can never make you poll forever. Webhooks (`callbackUrl`) are available as an alternative to polling.
  - Exception: `POST /v1/assets/{id}/download` is **synchronous** — it performs the export and returns a URL directly, with no `id` to poll. It can take a while on large assets; set a generous client timeout.
- Responses are enveloped, but the keys are not all always present: success is `{ success: true, data }`, failure is `{ success: false, error: { code, message, httpStatus, ... } }`. **There is no `data` on an error** — branch on `success` before reading `data`.
- Billing is prepaid credits, charged per generation. There is no separate API subscription — the API spends the same credit balance as the web app.
- **Engines are not hardcoded.** Query `GET /v1/models?category=3d|image|parts-board|remesh|texture|animate` for the live engine list, labels, and per-engine credit cost. Treat that endpoint as the source of truth rather than any list copied from documentation. ⚠️ `category` **defaults to `3d`**, and an unrecognized value falls back to `3d` rather than erroring — so a bare `GET /v1/models` returns only 3D engines. Always pass the category you mean.

## Endpoints
Every landing and doc page below is bilingual (English / Korean). Korean lives under the `/ko/` path prefix — e.g. `https://api.picoberry.ai/ko/docs/quickstart`. The URLs listed here are the English canonicals.

- [Quickstart](https://api.picoberry.ai/docs/quickstart): first call, end to end, in curl / Node / Python
- [Authentication](https://api.picoberry.ai/docs/authentication): API keys, headers, entitlement
- [Async & polling](https://api.picoberry.ai/docs/async): `taskStatus` lifecycle and how to wait correctly
- [Errors](https://api.picoberry.ai/docs/errors): error envelope and codes
- [Models](https://api.picoberry.ai/docs/models): `GET /v1/models` — available engines and credit cost
- [Text → Image](https://api.picoberry.ai/docs/text-to-image): `POST /v1/images`
- [Text → 3D](https://api.picoberry.ai/docs/text-to-3d): `POST /v1/models/from-text`
- [Image → 3D](https://api.picoberry.ai/docs/image-to-3d): `POST /v1/models/from-image` (single image, or 2–4 views via `imageUrls`/`images` for multi-view; image URL or multipart upload)
- [Parts Breakdown](https://api.picoberry.ai/docs/parts-board): `POST /v1/images/parts-board` — decompose one reference image into an exploded parts-board image (server-fixed engine, no params); feed the result to Image → 3D for a parts-separated mesh. Input via `assetId`, `imageUrl`, or multipart `image`
- [Get asset](https://api.picoberry.ai/docs/get-asset): `GET /v1/assets/{id}`
- [List assets](https://api.picoberry.ai/docs/list-assets): `GET /v1/assets`
- [Remesh](https://api.picoberry.ai/docs/remesh): `POST /v1/assets/{id}/remesh` — retopologize to a target polycount
- [Texture](https://api.picoberry.ai/docs/texture): `POST /v1/assets/{id}/texture` — PBR re-texture
- [UV unwrap](https://api.picoberry.ai/docs/uv-unwrap): `POST /v1/assets/{id}/uv-unwrap` — clean editable UV layout, source textures re-baked onto it (input under 30k faces)
- [Auto-rig & Animate](https://api.picoberry.ai/docs/animate): `POST /v1/assets/{id}/animate`; presets via `GET /v1/animations`
- [Download & export](https://api.picoberry.ai/docs/download): `POST /v1/assets/{id}/download` — signed URL for glb / fbx / obj
- [Collections](https://api.picoberry.ai/docs/collections): `/v1/collections` CRUD and membership
- [Credits balance](https://api.picoberry.ai/docs/credits-endpoint): `GET /v1/credits`
- [Credits & limits](https://api.picoberry.ai/docs/credits): what each operation costs, rate limits
- [Webhooks](https://api.picoberry.ai/docs/webhooks): push delivery on completion instead of polling

## MCP server
The server speaks the MCP standard over stdio, so it runs in MCP-capable agents generally. It is a thin wrapper over this REST API, published on npm as `@picoberry/mcp-server` (MIT).

- [MCP setup guide](https://api.picoberry.ai/docs/mcp): install, configure, and use it
- [Manual page](https://picoberry.ai/manual/mcp): the same thing in product-manual form (EN / KO)
- Source: https://github.com/UModeler/picoberry-mcp
- Package: https://www.npmjs.com/package/@picoberry/mcp-server

## Python SDK
`picoberry` on PyPI (MIT) — a client and CLI over this REST API. Use it instead of hand-rolling the async polling loop, multipart uploads, and error taxonomy.

```bash
pip install picoberry
export PICOBERRY_API_KEY=pb_live_...
picoberry 3d "a low-poly treasure chest" --wait -o chest.glb
```

```python
from picoberry import PicoBerry
pb = PicoBerry()                                   # reads $PICOBERRY_API_KEY
asset = pb.wait(pb.text_to_3d("a low-poly treasure chest")["id"])
print(asset["files"]["model"])                     # signed GLB URL
```

- Package: https://pypi.org/project/picoberry/
- Source: https://github.com/UModeler/picoberry-python
- Requires Python 3.9+. Covers text→image, text→3D, image→3D (single and 2–4 view multi-view), remesh, texture, animate, download, plus `wait()` polling.
- Engines are still queried at runtime — `pb.models("3d")` returns the live list with per-engine credit cost. Do not hard-code engine names.
- Errors subclass `PicoBerryError`, and the ones worth branching on are separate types: `InsufficientCreditsError`, `GenerationFailed`, `WaitTimeout`. A `WaitTimeout` does not cancel the job — poll `get_asset()` later rather than resubmitting, which would spend credits twice.

Configuration — no install step; `npx` fetches it on first run. The JSON below is the `mcpServers` form used by **Claude Code, Claude Desktop, and Cursor**. Other agents use their own config shape (Codex uses TOML `[mcp_servers.*]`; Zed uses `context_servers`) — the command, args, and env are the same; only the wrapper differs. Follow your agent's MCP documentation for the exact file and shape.

```json
{
  "mcpServers": {
    "picoberry": {
      "command": "npx",
      "args": ["-y", "@picoberry/mcp-server"],
      "env": {
        "PICOBERRY_API_KEY": "pb_live_xxxxxxxxxxxx",
        "PICOBERRY_API_BASE": "https://api.picoberry.ai"
      }
    }
  }
}
```

Tools exposed, as of `@picoberry/mcp-server@0.1.3`: `list_models`, `list_animation_presets`, `get_credits`, `generate_image`, `generate_3d_from_text`, `generate_3d_from_image`, `remesh`, `texture`, `animate`, `get_asset`, `wait_for_asset`, `list_my_assets`, `download_asset`. This list is a snapshot maintained by hand and lives in a different repository from the server — if it disagrees with the server, the server is right: the tools your client advertises after connecting are the authority.

## Notes for agents
- Generation is slow by nature — a 3D generation commonly takes minutes, not seconds. Use `wait_for_asset` (MCP) or poll with a timeout longer than the slowest engine rather than assuming a hung task.
- Generation spends real credits. Check `get_credits` / `GET /v1/credits` before large batches, and prefer `GET /v1/models` to confirm cost before choosing an engine.
- Post-processing tools (`remesh`, `texture`, `animate`) take an existing asset id and produce a **new** asset — they do not mutate the original.

## Company
UModeler, Inc. — https://umodeler.com. Also makes UModeler X, a 3D modeling tool for the Unity Editor.