Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
The command line for the [Meshy AI API](https://docs.meshy.ai/): text-to-3D,
image-to-3D, text-to-motion, remesh, convert, resize, UV unwrap, rigging,
animation, retexture, 2D images, printability, auto split, multi-color print,
Creative Lab products, usage records, plus
photo to bas-relief and depth map, Creative Lab products, usage records, plus
the local helpers a 3D-printing or agent workflow needs. Built for people and
AI agents: a terminal gets a readable view, a pipe or an agent gets JSON.

Expand Down
43 changes: 43 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -1743,3 +1743,46 @@ behind it, and what a reviewer should check. IDs are stable; append, do not renu
before; refreshing during a wait is separate work.
- Reviewer check: a change to the window must keep a fresh token outside it,
or every command refreshes again.

## D-096 Relief: one v1 resource, a depth map asset, and the API's rules checked before the request

- `relief` is a task resource on `/openapi/v1/relief` with the full verb set
and task type `relief`. Its `image_url` takes the photo formats the API
accepts (JPG/JPEG, PNG, WebP), the same list as the Creative Lab photos
(`PHOTO_FORMATS`). The 20 MB, 32 × 32 px and aspect-ratio limits are left to
the API, which answers 400 without charging.
- Flags follow D-076: the API booleans are `--remove-base <bool>` and
`--color-mapping <bool>`. `should_generate_model: false` is `--depth-only`,
a presence flag: `--should-generate-model false` would read backwards for
the one value anyone sends, and `--data` still reaches the field. Nothing is
pinned; a flag left out is left out of the request, so the API's defaults
(low, 60 mm, GLB + STL) apply.
- Every documented range is checked on the merged payload, `--data` included.
`--mesh-resolution` is parsed as a number and must be an integer, so 1500.5
is refused rather than truncated. `target_formats` must be a non-empty list
of the documented lowercase values without repeats. `base_thickness_mm` is
0.1-10, or left out or 0 with `remove_base: true`.
- Refused as D-076 refuses settings the API would not use: `removal_threshold`
without `remove_base: true`, `bend_axis` / `bend_angle` without a convex or
concave bend, and every model setting with `--depth-only` (the variant
stays: it shapes the depth map). `carving_depth_mm: 0` with
`remove_base: true` is a request the API documents and runs (an empty
model, still billed), so it is sent with an `empty_model` warning rather
than refused.
- `--color-mapping true` with only STL / 3MF formats is sent as asked, with a
`color_not_in_formats` warning: those formats carry no color, but the API
still returns the texture.
- The TaskView gains `depth_map_url` (null for other resources), so a v1
envelope saved without `--include-raw` still names the depth map. The asset
is `depth_map` (kind `depth_map`, file `depth_map.png`); `-o` saves it with
the models, and a depth-only task saves it alone. It is never transcoded:
sharp would flatten its 16 bits to 8, so a request for `.jpg` keeps the PNG
under its own extension (`extension_corrected`).
- `--model-format` naming a format the task lacks now lists the formats it has
(or says it has no model file). The 402 hint names both causes the API gives
it, no credits or a plan without the endpoint.
- A relief task cannot be the input of another endpoint (403); the help, the
usage guide and the skill say so. Its own `relief delete` is the documented
delete; the shared `meshy delete` was not checked against relief tasks.
- Reviewer check: a new rule must come from the API reference, and must hold
for the same field in `--data`.
4 changes: 2 additions & 2 deletions docs/scripting.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,8 +97,8 @@ one JSON document (`ndjson` streams emit one line per event plus a final
in every output format, and in `ndjson` the final `outcome` line carries the
download manifest.
- `-o` on `get`/`wait`/`stream`/`make` saves the primary files of a SUCCEEDED
task: the model formats it produced, the primary thumbnail, images and
reports, and the rig or animation result in GLB. `result.downloads.files` is a
task: the model formats it produced, the primary thumbnail, the relief depth
map, images and reports, and the rig or animation result in GLB. `result.downloads.files` is a
per-file manifest (stable `key` as `meshy download --asset` takes it, real
`path`, bytes, sha256, status). `result.downloads.skipped` lists
`{key, reason}` for what stayed on the server: `embedded_textures`,
Expand Down
59 changes: 57 additions & 2 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -217,6 +217,11 @@ meshy animate create --rig-task-id <rig-id> --motion-task-id <text-to-motion-id>
meshy auto-split create --input-task-id <id> --mode by_parts --prompt "head, torso, legs" --connectors true
meshy usage tasks --start-time 2026-08-01T00:00:00Z --endpoints image-to-3d --page-size 100

# photo → bas-relief model + 16-bit depth map (3D print, laser engraving, CNC); 20 credits, paid plan
meshy relief create --image-url ./photo.jpg -o out/relief/ # GLB, STL, depth map, preview
meshy relief create --image-url ./photo.jpg --variant high --size-mm 120 --target-formats 3mf
meshy relief create --image-url ./photo.jpg --depth-only -o heightmap.png # the depth map alone

# Enterprise showcases (billed per request)
meshy showcases list --search car --page-size 3 --model-format glb

Expand Down Expand Up @@ -295,6 +300,7 @@ local commands with their kind.
| `analyze-printability` | `/print/analyze` | [docs](https://docs.meshy.ai/en/api/analyze-printability) |
| `repair-printability` | `/print/repair` | [docs](https://docs.meshy.ai/en/api/repair-printability) |
| `auto-split` | `/print/split` | [docs](https://docs.meshy.ai/en/api/auto-split) |
| `relief` | `/relief` | [docs](https://docs.meshy.ai/en/api/relief) |
| `creative-lab <product> prototype\|build` | `/openapi/creative-lab/<product>/v1/<stage>` | [figure](https://docs.meshy.ai/en/api/creative-lab-figure) · [vinyl-figure](https://docs.meshy.ai/en/api/creative-lab-vinyl-figure) · [brick-figure](https://docs.meshy.ai/en/api/creative-lab-brick-figure) · [lamp](https://docs.meshy.ai/en/api/creative-lab-lamp) · [keychain](https://docs.meshy.ai/en/api/creative-lab-keychain) · [fridge-magnet](https://docs.meshy.ai/en/api/creative-lab-fridge-magnet) · [keycap](https://docs.meshy.ai/en/api/creative-lab-keycap) · [fidget-pixel](https://docs.meshy.ai/en/api/creative-lab-fidget-pixel) |
| `creative-lab fidget-collapsible` | `/openapi/creative-lab/fidget-collapsible/v1` | [docs](https://docs.meshy.ai/en/api/creative-lab-fidget-collapsible) |
| `animation-catalog list` | `GET /animations/library` (free) | [docs](https://docs.meshy.ai/en/api/animation#list-animations) |
Expand Down Expand Up @@ -369,6 +375,55 @@ in the web app are rejected by the server (404).
a printable STL (plus a preview GLB when available), with the same
get/list/wait/stream/delete verbs.

### Relief

`relief` turns one photo into a bas-relief model and a 16-bit grayscale depth
map, for 3D printing, laser engraving and CNC carving. A task costs 20 credits,
depth map only included, and needs a paid plan (`402` on the free plan). The
photo is a JPG, PNG or WebP of at most 20 MB and at least 32 × 32 px; a local
file is sent inline.

```bash
meshy relief create --image-url ./photo.jpg -o out/relief/
meshy relief create --image-url ./photo.jpg --variant high --carving-depth-mm 10 \
--bend-mode convex --bend-angle 90 --color-mapping true --target-formats glb,obj,stl -o out/plaque/
meshy relief create --image-url ./logo.png --remove-base true --removal-threshold 0.05 --target-formats stl
meshy relief create --image-url ./photo.jpg --depth-only -o heightmap.png
```

- `--variant low` (the default) carves shallow, for laser engraving, CNC and
thin plaques; `high` carves deeper, for printed pieces. The variant shapes the
depth map and sets the default `--carving-depth-mm` (3 or 6).
- `--depth-only` returns only the depth map: no model, no preview image, the
same price. The model settings do not apply to it, so the CLI refuses them.
- `--size-mm` (20-250, default 60) is the photo's longer side on the model.
`--carving-mode engrave` cuts the subject in instead of raising it.
`--remove-base true` cuts the background away and builds no plate; with it,
`--base-thickness-mm` is left out or 0 and `--removal-threshold` (0.01-1)
sets what counts as background. `--bend-mode convex|concave` with
`--bend-axis` and `--bend-angle` curves the relief.
- `--target-formats` (default `glb,stl`) lists the only formats generated:
`glb`, `obj` (with its MTL), `fbx`, `stl`, `usdz`, `3mf`. STL and 3MF keep the
real size in millimetres. `--color-mapping true` colors GLB, OBJ, FBX and
USDZ with the photo and returns the texture; STL and 3MF stay white.
- Files are large: at the default `--mesh-resolution 1024` a GLB is about
40-50 MB and an STL 80-105 MB; at 2048 about 150 MB and 300 MB, and a bend
makes them larger still. List only the formats you need.

Every documented range and rule is checked before the request, also for the
same fields in `--data`. A parameter the API would ignore in the combination
asked for (a threshold without `--remove-base true`, a bend angle with no bend)
is refused rather than sent, and so is `--carving-depth-mm 0` with
`--remove-base true`, which builds an empty model that is still billed.

`-o <dir>` saves every model format, the depth map (`depth_map.png`), the
preview and, when an OBJ or FBX needs it, the texture; `meshy download
--asset depth_map` fetches the depth map alone. The depth map is never
converted to another image format: that would drop its 16-bit levels.

A relief task cannot be the input of another command (`remesh`, `convert`,
`resize`, `auto-split` …): the API answers 403.

## Saving artifacts with `-o` and `meshy download` (selective)

When `-o` is set on a `create`/`wait`/`get`/`stream` or on `make`, the CLI
Expand All @@ -383,8 +438,8 @@ The primary files are:

- every model format the task produced. That is GLB unless `--target-formats`
asked for more.
- the primary thumbnail, the generated images, motion clips, `processed_*`
outputs and reports (`printability.json`).
- the primary thumbnail, the relief depth map, the generated images, motion
clips, `processed_*` outputs and reports (`printability.json`).
- the rig or animation result in GLB (`rigged_character.glb`, `animation_glb.glb`).

Left on the server by default, and listed under `result.downloads.skipped`
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "meshy-cli",
"version": "0.8.7",
"description": "Official command-line interface for the Meshy AI API — text-to-3D, image-to-3D, text-to-motion, remesh, UV unwrap, rigging, animate, retexture, 2D images, printability, auto split, multi-color print, Creative Lab, balance and usage — plus selective downloads, project folders, face checks, OBJ print preparation and slicer launch.",
"description": "Official command-line interface for the Meshy AI API — text-to-3D, image-to-3D, text-to-motion, remesh, UV unwrap, rigging, animate, retexture, 2D images, printability, auto split, multi-color print, relief, Creative Lab, balance and usage — plus selective downloads, project folders, face checks, OBJ print preparation and slicer launch.",
"license": "MIT",
"type": "module",
"packageManager": "pnpm@11.24.0",
Expand Down
36 changes: 35 additions & 1 deletion skills/meshy-cli/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: meshy-cli
description: "Generate 3D models, motion clips, 2D images and Creative Lab print products with the Meshy API through the meshy-cli command — text-to-3D, image-to-3D, text-to-motion, remesh, UV unwrap, rigging, animation, retexture, printability, auto split into printable parts, per-task credit usage, selective downloads, face checks, OBJ print preparation and slicer launch. Use for any Meshy asset or 3D-printing request."
description: "Generate 3D models, motion clips, 2D images, bas-reliefs and Creative Lab print products with the Meshy API through the meshy-cli command — text-to-3D, image-to-3D, text-to-motion, remesh, UV unwrap, rigging, animation, retexture, printability, auto split into printable parts, photo to relief model and depth map (3D print, laser engraving, CNC), per-task credit usage, selective downloads, face checks, OBJ print preparation and slicer launch. Use for any Meshy asset or 3D-printing request."
license: MIT
compatibility: Requires meshy-cli on PATH (Node 22.12+, no Python) and a stored credential, MESHY_API_KEY or --api-key-file for API commands; network access to api.meshy.ai. Local helpers work offline.
metadata:
Expand Down Expand Up @@ -118,6 +118,40 @@ output `lamp_stl`/`base_stl` or `bundle_zip`; keychain/fridge-magnet `obj` and
keycap `obj_zip` are ZIP bundles saved as `.zip`; fidget-pixel builds a 3MF.
Never call `showcases` in a health check.

## Relief (photo → bas-relief model and depth map)

```bash
meshy relief create --image-url ./photo.jpg -o out/relief/ # GLB + STL + depth_map.png + preview
meshy relief create --image-url ./photo.jpg --variant high --size-mm 120 --target-formats 3mf -o out/plaque/
meshy relief create --image-url ./photo.jpg --depth-only -o heightmap.png # the 16-bit depth map alone
```

Use `relief` when the user wants a photo turned into a relief, plaque, medallion
or engraving, or a height map for laser or CNC software; the Creative Lab
keychain and fridge magnet are styled products with a prototype stage, not this.
Every task costs 20 credits, a depth-map-only task too, and needs a paid plan
(exit 9 on the free plan or without credits: relay it, do not retry).

- `--variant low` (default) is shallow, for laser engraving, CNC and thin
plaques; `high` is deeper, for 3D-printed pieces.
- `--depth-only` returns only `depth_map_url` (a 16-bit grayscale PNG, relative
heights): no model, no preview. Use it when the user asked for a height or
depth map only. Model settings are refused with it.
- `--target-formats` (default `glb,stl`) is the only set generated: `glb`, `obj`
(+ MTL), `fbx`, `stl`, `usdz`, `3mf`. STL and 3MF are in real millimetres, for
printing. `--color-mapping true` colors GLB/OBJ/FBX/USDZ only; STL and 3MF stay
white. Ask only for the formats the user needs: an STL is 80-105 MB at the
default `--mesh-resolution 1024` and about 300 MB at 2048 (more with a bend).
- `--remove-base true` cuts the background away (then `--base-thickness-mm` is
left out or 0); `--bend-mode convex|concave` curves it. Ranges and the
combinations the API would ignore are refused before the request (exit 2).
- `-o <dir>` saves the models, `depth_map.png` and the preview;
`meshy download --task-json <file> --asset depth_map --output <file.png>`
fetches the depth map alone. It is never converted to another image format.
- **A relief task cannot feed another command** (`remesh`, `convert`, `resize`,
`auto-split`, `multi-color-print` …: 403). Pick the formats, size and depth at
create time; to change them, create a new relief.

## Downloads, printing (local, no key)

```bash
Expand Down
8 changes: 5 additions & 3 deletions src/client/resource-registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,8 @@ export const CREATIVE_LAB_PRODUCTS: readonly CreativeLabProduct[] = [
"fidget-pixel",
];
export const CREATIVE_LAB_STAGES: readonly CreativeLabStage[] = ["prototype", "build"];
const CREATIVE_LAB_IMAGE_FORMATS = ["jpg", "jpeg", "png", "webp"] as const;
/** The photo inputs of Creative Lab and Relief: JPG/JPEG, PNG or WebP. */
const PHOTO_FORMATS = ["jpg", "jpeg", "png", "webp"] as const;

function creativeLab(product: CreativeLabProduct, stage: CreativeLabStage, summary: string): TaskResourceDescriptor {
const relativePath = `/${product}/v1/${stage}`;
Expand All @@ -131,7 +132,7 @@ function creativeLab(product: CreativeLabProduct, stage: CreativeLabStage, summa
relativePath,
endpoint: `/openapi/creative-lab${relativePath}`,
supports: ALL_VERBS,
mediaFields: stage === "prototype" ? [image("image_url", false, CREATIVE_LAB_IMAGE_FORMATS)] : [],
mediaFields: stage === "prototype" ? [image("image_url", false, PHOTO_FORMATS)] : [],
taskTypes: [`creative-lab-${product}-${stage}`],
billing: { create: "may-charge" },
automaticRetry: false,
Expand All @@ -150,7 +151,7 @@ function creativeLabSingle(product: CreativeLabSingleProduct, summary: string):
relativePath,
endpoint: `/openapi/creative-lab${relativePath}`,
supports: ALL_VERBS,
mediaFields: [image("image_url", false, CREATIVE_LAB_IMAGE_FORMATS)],
mediaFields: [image("image_url", false, PHOTO_FORMATS)],
taskTypes: [`creative-lab-${product}`],
billing: { create: "may-charge" },
automaticRetry: false,
Expand Down Expand Up @@ -189,6 +190,7 @@ export const TASK_RESOURCES: readonly TaskResourceDescriptor[] = [
v1("repair-printability", "/print/repair", { mediaFields: [inlineModel("model_url")], taskTypes: ["print-repair"], summary: "fix non-watertight / non-manifold geometry" }),
v1("auto-split", "/print/split", { taskTypes: ["print-split"], summary: "split a model into printable parts (auto / by named parts / by colour; optional connectors)" }),
v1("uv-unwrap", "/uv-unwrap", { mediaFields: [model("model_url", ["glb"])], taskTypes: ["uv-unwrap"], summary: "generate fresh UVs for a GLB (≤40k faces) — a UV white model for external texturing" }),
v1("relief", "/relief", { mediaFields: [image("image_url", false, PHOTO_FORMATS)], taskTypes: ["relief"], summary: "photo → bas-relief model + 16-bit depth map (3D print, laser engraving, CNC)" }),
creativeLab("figure", "prototype", "Creative Lab figure: photo → styled concept image"),
creativeLab("figure", "build", "Creative Lab figure: prototype → textured GLB/OBJ/MTL"),
creativeLab("lamp", "prototype", "Creative Lab lamp: photo → concept image + lampshade GLB"),
Expand Down
2 changes: 2 additions & 0 deletions src/client/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,8 @@ export const TaskSchema = z
thumbnail_url: z.string().nullable().optional(),
thumbnail_urls: z.record(z.string(), z.string().nullable()).nullable().optional(),
alpha_thumbnail_url: z.string().nullable().optional(),
/** Relief: the 16-bit grayscale depth map the model is built from ("" until it exists). */
depth_map_url: z.string().nullable().optional(),

image_urls: z.array(z.string()).nullable().optional(),

Expand Down
4 changes: 2 additions & 2 deletions src/cmd/download.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ import { buildLocalRuntime, buildRuntime } from "../internal/runtime.js";
import { extractTaskObject } from "../internal/task-view.js";

const TASK_JSON_MAX_BYTES = 16 * 1024 * 1024;
const KINDS: readonly AssetKind[] = ["model", "image", "texture", "thumbnail", "rig", "animation", "motion", "report"];
const KINDS: readonly AssetKind[] = ["model", "image", "texture", "thumbnail", "depth_map", "rig", "animation", "motion", "report"];

interface DownloadOpts {
taskJson?: string;
Expand Down Expand Up @@ -92,7 +92,7 @@ export const downloadCommand = new Command("download")
.option("--url <url>", "download exactly one asset URL (no task context)")
.option("--resource <id>", "with --task-id: fetch the task from the API first (one GET)")
.option("--task-id <id>", "with --resource: the task to fetch")
.option("--asset <key>", "stable asset key to download (repeatable), e.g. model.glb, thumbnail.primary, result.basic_animations.walking_glb_url", collect)
.option("--asset <key>", "stable asset key to download (repeatable), e.g. model.glb, thumbnail.primary, depth_map, result.basic_animations.walking_glb_url", collect)
.option("--model-format <fmt>", "select the model of this format (glb, obj, fbx, usdz, stl, 3mf, …)")
.addOption(new Option("--kind <kind>", "select every asset of one kind").choices([...KINDS]))
.option("--all", "select every asset")
Expand Down
Loading
Loading