Text-to-3D and image-to-3D are separate endpoints. Both return an asset with taskStatus: 0; poll GET /v1/assets/{id} until taskStatus is 2.

Text → 3D

POST /v1/models/from-text

{
  "prompt": "a stylized treasure chest, low-poly",
  "engine": "tripo",
  "polycount": 10000,
  "texture": true
}

Field	Type	Required	Description
`prompt`	`string`	Yes	The generation prompt. Up to 1,024 characters.
`engine`	`string`	No	Engine / model, e.g. `tripo`, `tripo-v3.1`, `hunyuan-3.1`. See `GET /v1/models?category=3d`.
`polycount`	`integer`	No	Target polygon count, 100–2,000,000. Clamped to the model's supported range.
`texture`	`boolean`	No	Generate PBR textures. Defaults to `true`.
`license`	`string`	No	Defaults to `all-rights-reserved`.

Image → 3D

POST /v1/models/from-image

Pass an imageUrl (JSON) or upload the file directly (multipart/form-data with an image field, ≤ 20 MB — png, jpeg, webp, or gif). One of the two is required. A PicoBerry-generated image URL works as input.

curl -X POST https://api.picoberry.ai/v1/models/from-image \
  -H "Authorization: Bearer pb_live_xxx" \
  -F "engine=tripo" \
  -F "image=@./ref.png"

engine, polycount, texture, and license behave as for Text → 3D.

Response

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

On success (taskStatus: 2), files.model holds a signed GLB URL and files.thumbnail / files.textures the preview and maps:

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

Export to another format

To download as FBX or OBJ (bundled as a .zip with textures), call POST /v1/assets/{id}/download with { "format": "glb" | "fbx" | "obj" }. See the Download page.

Follow-up operations

The finished asset id can be fed into post-processing:

POST /v1/assets/{id}/remesh — retopologize to a target polygon count.
POST /v1/assets/{id}/texture — re-generate PBR textures.
POST /v1/assets/{id}/uv-unwrap — re-lay the UV map into clean, editable islands.
POST /v1/assets/{id}/animate — auto-rig and optionally retarget an animation.

Each returns a new asset (the source is left untouched) with taskStatus: 0, so poll it exactly like a generation.

UV unwrap

POST /v1/assets/{id}/uv-unwrap

Re-parameterizes an existing 3D asset into a clean, editable UV layout and re-bakes the original textures onto it. Geometry and appearance are unchanged — only the UV layout is replaced. There are no tuning parameters.

curl -X POST https://api.picoberry.ai/v1/assets/019.../uv-unwrap \
  -H "Authorization: Bearer pb_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"engine": "pb-uv"}'

Field	Type	Required	Description
`engine`	`string`	No	`pb-uv` (default) or `hunyuan-uv`. See `GET /v1/models?category=uv-unwrap`.
`license`	`string`	No	Defaults to `all-rights-reserved`.

Engine	Max input faces	Notes
`pb-uv`	100,000	Self-hosted. Cheaper, and no vendor concurrency limit.
`hunyuan-uv`	30,000	Tencent Hunyuan's UV job.

Exceeding the engine's face limit fails the job with invalid_input and the credits are refunded — run POST /v1/assets/{id}/remesh first to reduce the mesh. Per-engine credit cost is returned by GET /v1/models?category=uv-unwrap.

Both engines require an active paid plan. An account entitled to the API through a credit-pack purchase alone gets 403 here.