Sculpt commands
Sculpt from consistent reference views, retain the provider master, and derive a scene-ready mesh.
A picture or a prompt becomes a mesh. Normal keeps the existing textured generation; Geometry asks for untextured geometry. Your own keys spend no Puni credits; providers bill their calls. Puni's keys use credits when available. Read Import for the result and Credits for the total cost.
puni sculptMake a textured object from a picture or a prompt, and split it into named parts.
| Command | What it does |
|---|---|
puni sculpt | Sculpt with your own fal key from Settings → Providers, or with Puni's keys for credits when they are available. A prompt first becomes a transparent picture through OpenAI. |
puni sculpt status | Read a sculpt and advance its progress. A split sculpt lists its parts and their faces. |
puni sculpt list | List your twenty most recent sculpts. |
puni sculpt segment | Split a ready sculpt while keeping its textures and UVs. A one-part answer can be re-rolled; the previous source stays available. |
#sculpt
Sculpt a picture into a textured or untextured mesh.
puni sculpt --prompt "a small felt red panda plush, sitting"
| Flag | Type | Default | Values | What it does |
|---|---|---|---|---|
--image | string | A PNG, JPEG or WebP file under 12 MB. Choose image or prompt. | ||
--prompt | string | Describe one object in at most 4,000 characters. Choose prompt or image. | ||
--name | string | Name the sculpt. | ||
--image-back | string | Additional back reference file; requires --image for the front view. | ||
--image-left | string | Additional left reference file; requires --image for the front view. | ||
--image-right | string | Additional right reference file; requires --image for the front view. | ||
--image-top | string | Additional top reference file; requires --image for the front view. | ||
--image-bottom | string | Additional bottom reference file; requires --image for the front view. | ||
--image-left-front | string | Additional left-front reference file; requires --image for the front view. | ||
--image-right-front | string | Additional right-front reference file; requires --image for the front view. | ||
--generate-type | string | Normal, Geometry | Textured Normal mesh or untextured Geometry mesh. | |
--lip | string | strip, keep | Erase a sticker outline, or keep it. Pictures default to strip; prompts to keep. | |
--faces | number | Provider mesh target between 40,000 and 500,000 faces. | ||
--request-id | string | Reuse this ID with identical input to retry an attempt after a lost response. | ||
--no-wait | boolean | Return the sculpt id without waiting for the mesh. | ||
--output | string | Write the finished source reference to a JSON file. | ||
--overwrite | boolean | false | Replace the output file if it already exists. | |
--base-url | string | The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback. | ||
--auth-file | string | Read and write credentials in this file instead of ~/.config/puni/credentials.json. | ||
--json | boolean | false | Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope. | |
--help -h | boolean | Print the command list. |
#Run sculpt
puni sculpt --image panda.png --base-url https://puni.design#Separate reference views
--image is the front view. Add any of --image-back, --image-left, --image-right, --image-top, --image-bottom, --image-left-front and --image-right-front to send separate images of the same object. They should agree on proportions and pose; a collage is still only one view. Additional views require a front image and cannot be combined with --prompt.
puni sculpt --image blobby-front.png --image-back blobby-back.png \
--image-left blobby-left.png --image-left-front blobby-three-quarter.png \
--name Blobby --lip keep --generate-type Geometry --faces 120000 \
--request-id blobby-master-001 --no-wait --jsonUse --lip keep for intentional silhouettes and narrow features. strip retains the existing sticker-outline treatment. Puni keeps each original file and the prepared PNG actually sent to the provider, with their hashes and view names in sculpt.input.references.
The REST and MCP equivalents use generateType: "Geometry" and a views object such as { "back": { "imageUrl": "https://example.com/back.png" } }. A view accepts exactly one base64 image (with optional mime) or public HTTPS imageUrl. Browser tools use URLs. A base64 image keeps the 12 MB input limit. An imageUrl picture must be HTTPS on the default port and at most 4 MiB. Prepared PNGs are at most 8 MB and 2048 pixels on the long side. The total request limits still apply: 4 MB for one REST call and 768 KB for MCP. Prefer image URLs whenever base64 pictures would exceed that budget.
Reuse the same request ID and identical images and options after a lost response. Changing a view, mode or other generation option under that ID is refused. The default Normal single-image and prompt requests keep their existing retry identity.
#Provider master and delivery source
sculpt.master.source identifies the provider's untouched GLB, retained before optimization. sculpt.source remains the delivery mesh, simplified toward 60,000 triangles with textures sized for scenes. These are separate references; --output continues to write the delivery source. Read sculpt status ID --json for both sources, the provider request and model, image provenance, seed when returned, and before/after ingest figures.
If optimization fails after master retention, a later authorized read resumes from the stored master without another provider call or charge. Older sculpts without a retained master remain readable; their original GLBs cannot be reconstructed from their optimized files. The existing 64 MB asset limit applies to masters too. An oversized provider GLB stops before optimization and reports the limit; this capability does not increase storage limits.
#sculpt status
Read progress, source references and faces per part.
puni sculpt status ID
| Flag | Type | Default | Values | What it does |
|---|---|---|---|---|
--base-url | string | The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback. | ||
--auth-file | string | Read and write credentials in this file instead of ~/.config/puni/credentials.json. | ||
--json | boolean | false | Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope. | |
--help -h | boolean | Print the command list. |
#Run sculpt status
puni sculpt status sculpt-… --base-url https://puni.design#sculpt list
Read your twenty most recent sculpts.
puni sculpt list
| Flag | Type | Default | Values | What it does |
|---|---|---|---|---|
--base-url | string | The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback. | ||
--auth-file | string | Read and write credentials in this file instead of ~/.config/puni/credentials.json. | ||
--json | boolean | false | Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope. | |
--help -h | boolean | Print the command list. |
#Run sculpt list
puni sculpt list --base-url https://puni.design#sculpt segment
Split a ready sculpt while keeping its textures and UVs. A one-part answer can be re-rolled; the previous source stays available.
puni sculpt segment ID [--again --request-id stable-id --no-wait --output source.json]
| Flag | Type | Default | Values | What it does |
|---|---|---|---|---|
--again | boolean | Start another paid attempt after the last one finishes. | ||
--request-id | string | Reuse this ID to retry a split after a lost response. | ||
--no-wait | boolean | Return without waiting for the split. | ||
--output | string | Write the segmented source reference to this file. | ||
--overwrite | boolean | false | Replace the output file if it already exists. | |
--base-url | string | The studio origin, such as https://puni.design. Defaults to PUNI_BASE_URL, else the one studio you are signed in to. HTTPS, except loopback. | ||
--auth-file | string | Read and write credentials in this file instead of ~/.config/puni/credentials.json. | ||
--json | boolean | false | Answer with one JSON envelope instead of the shell view. Exception: agent serve streams raw lifecycle JSON lines before its final envelope. | |
--help -h | boolean | Print the command list. |
#Run sculpt segment
puni sculpt segment sculpt-… --again --base-url https://puni.designBack to the command line index for every group.
Was this useful?