scenario-meshy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scenario Meshy 3D

Overview

概述

Meshy on Scenario is a toolchain rather than one model: image-to-3D generators (Meshy 7 Image to 3D, Meshy 7 Multi Image to 3D, Meshy T2 Smart Topology), Meshy 6 Text-to-3D, and GLB-in, GLB-out utilities (Retexture, Remesh, UV Unwrap, Rigging, Animation). Work runs as a pipeline: generate a mesh, refine it, then rig or animate, each stage its own

model_run

whose

model

parameter takes the 3D asset id the previous stage returned. Discover members with

search

and treat

model_schema_get

as the contract: members disagree on defaults as basic as

enablePbr

(true on Image to 3D, false on Multi Image and Retexture at authoring time).

Connection and the core loop: see the

scenario

skill in this repo; model-agnostic 3D work (viewer, capture, engine import): the

scenario-3d

skill. If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add scenario-labs/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

Scenario上的Meshy并非单一模型，而是一套工具链：包含image-to-3D生成器（Meshy 7 Image to 3D、Meshy 7 Multi Image to 3D、Meshy T2 Smart Topology）、Meshy 6 Text-to-3D，以及GLB输入输出工具（Retexture、Remesh、UV Unwrap、Rigging、Animation）。工作以流水线形式运行：生成网格、优化网格，然后绑定或制作动画，每个阶段都有对应的

model_run

，其

model

参数接收上一阶段返回的3D资产ID。可通过

search

查找成员，并将

model_schema_get

视为约定：不同成员的默认值存在差异，哪怕是

enablePbr

这类基础参数（编写本文时，Image to 3D默认为true，Multi Image和Retexture默认为false）。

连接方式与核心循环：参见本仓库中的

scenario

skill；与模型无关的3D工作（查看器、捕获、引擎导入）：参见

scenario-3d

skill。如果你可用的skill中缺少此处提到的同类skill，请让用户安装（命令：

npx skills add scenario-labs/skills --skill <name>

）；若处于无人值守模式，可依据工具schema继续操作并标记缺失项。

Quick reference

快速参考

Members and their traps (names from the live schema, caps at authoring time):

Member	Core input	Watch for
7 Image to 3D	`image` (1-4)	`ultraMode` takes a single image only; raw mesh by default
7 Multi Image to 3D	`image` (1-4, first = front view)	remeshes in-run; `savePreRemeshedModel` keeps the raw GLB
T2 Smart Topology	`image` (1-4)	animation-ready topology; `targetPolycount` caps at 15,000
6 Text-to-3D	`prompt` (600 chars)	`shouldRemesh` off by default
Retexture	`model` + one style input	geometry untouched; keep inputs near 30K polys; `enableOriginalUv`
Remesh	`model`	`targetPolycount` 100 to 300,000, `resizeHeight` , `originAt`
UV Unwrap	`model`	rejects meshes above 44,000 faces; Remesh down first
Rigging	`model` , `heightMeters`	humanoid skeleton and skin weights
Animation	`model` , `actionId`	auto-rigs, then applies the clip

One silent rule runs through every texture control: an image beats text. On the generators

textureImage

overrides

texturePrompt

(the text is ignored, not blended), and both need

shouldTexture

on (Text-to-3D has no such toggle: it always textures). Retexture is stricter: exactly one of

textStylePrompt

imageStyle

, or

multiviewImage

(1 to 4 views, first is the front).

textureResolution

runs 2k, 4k, or 8k; at 8k the PBR maps come back at 4K with no emission map (Meshy 7 never produces one), and 8k pairs only with triangle topology when remeshing.

poseMode

takes lowercase

"a-pose"

"t-pose"

: set one on any character headed for rigging.

各成员及其常见坑点（名称来自实时schema，大小写以编写本文时为准）：

成员	核心输入	常见坑点
7 Image to 3D	`image` （1-4张）	`ultraMode` 仅支持单张图片；默认输出原始网格
7 Multi Image to 3D	`image` （1-4张，第一张为正视图）	运行过程中会自动重网格化；开启 `savePreRemeshedModel` 可保留原始GLB
T2 Smart Topology	`image` （1-4张）	拓扑支持直接制作动画； `targetPolycount` 上限为15000
6 Text-to-3D	`prompt` （600字符以内）	`shouldRemesh` 默认关闭
Retexture	`model` + 1个风格输入	不改变几何形状；输入模型面数建议接近30K；注意 `enableOriginalUv` 参数
Remesh	`model`	`targetPolycount` 范围为100到300000，支持 `resizeHeight` 、 `originAt` 参数
UV Unwrap	`model`	面数超过44000的网格会被拒绝；请先使用Remesh降低面数
Rigging	`model` 、 `heightMeters`	生成人形骨骼与蒙皮权重
Animation	`model` 、 `actionId`	自动绑定后应用动画片段

所有纹理控制都遵循一条隐含规则：图片优先级高于文本。在生成器中，

textureImage

会覆盖

texturePrompt

（文本会被忽略，而非混合），且两者都需要开启

shouldTexture

（Text-to-3D没有此开关：它始终会生成纹理）。Retexture的要求更严格：必须且只能提供

textStylePrompt

、

imageStyle

、

multiviewImage

中的一种（multiviewImage为1到4个视角，第一张为正视图）。

textureResolution

支持2k、4k或8k；选择8k时，PBR贴图会以4K分辨率返回，且不包含自发光贴图（Meshy 7从不生成自发光贴图），此外8k分辨率在重网格化时仅支持三角拓扑。

poseMode

接受小写的

"a-pose"

或

"t-pose"

：任何需要绑定的角色都应设置该参数。

Generate raw, refine on purpose

先生成原始网格，再有针对性地优化

Keep

shouldRemesh

off on Meshy 7 Image to 3D (the schema recommends it): take the raw mesh at generation, then control polycount with Remesh, which owns

targetPolycount

, topology,

resizeHeight

in meters (0 keeps scale), and origin placement. On the generator,

targetPolycount

does nothing while

shouldRemesh

is off.

ultraMode

buys finer geometry for extra cost but accepts one input image; when hidden sides matter more than micro detail, spend the budget on up to four views instead. Costs spread widely (at authoring time the single-image Meshy 7 p50 ran three times the multi-image one), so

dry_run

before batches.

在Meshy 7 Image to 3D中请保持

shouldRemesh

关闭（schema也推荐如此）：先生成原始网格，再通过Remesh工具控制面数——Remesh支持

targetPolycount

、拓扑类型、以米为单位的

resizeHeight

（设为0则保持原有比例）以及原点位置设置。在生成器中，当

shouldRemesh

关闭时，

targetPolycount

参数不会生效。

ultraMode

可生成更精细的几何结构，但成本更高，且仅支持单张输入图片；如果相比微观细节，你更看重模型背面的效果，建议将预算投入到最多4个视角的输入上。成本差异很大（编写本文时，单图Meshy 7的p50成本是多图版本的三倍），因此批量处理前请先使用

dry_run

预估。

Rig or animate, not both

绑定和动画二选一，不要同时使用

Rigging and Animation are alternatives, not stages. Animation auto-rigs internally, then applies the clip named by

actionId

, a number from Meshy's animation library (ids listed at docs.meshy.ai/en/api/animation-library). Run Rigging alone when you want a rigged GLB for your own clips; go straight to Animation for a moving character, optionally setting

postProcessOperation

change_fps

(

postProcessFps

24, 25, 30, or 60) or

extract_armature

. Both scale the rig from

heightMeters

, so pass the character's real height.

Rigging和Animation是替代关系，而非先后步骤。Animation会在内部自动完成绑定，然后应用由

actionId

指定的动画片段——

actionId

是Meshy动画库中的数字编号（ID列表可查看docs.meshy.ai/en/api/animation-library）。如果你需要绑定好的GLB来自定义动画片段，请单独运行Rigging；如果需要可动角色，可直接使用Animation，还可选择将

postProcessOperation

设为

change_fps

（

postProcessFps

支持24、25、30或60）或

extract_armature

。两者都会根据

heightMeters

缩放绑定，因此请传入角色的真实身高。

Worked example: photo to animated character

实战示例：从照片生成动画角色

```
search
```
with
```
target="models"
```
,
```
query="meshy"
```
,
```
public=true
```
. Single-image route:
```
model_meshy-7-img23d
```
(a live hit at authoring time: re-discover each session).
```
model_schema_get
```
with that id, then
```
upload_asset
```
the character photo (see the
```
scenario
```
skill).

model_run

with

dry_run=true

and

parameters={"image": ["asset_photo"], "poseMode": "t-pose", "texturePrompt": "worn leather armor, muted palette", "enablePbr": true}

for the estimate; then re-run with

wait=false

and

jobs_wait

with the job id, re-called with

pending_job_ids

on timeout, never a second

model_run

```
asset_display
```
the GLB; check silhouette and texture before spending further.

search

for the animation member,

model_schema_get

, then

model_run

with

parameters={"model": "<GLB asset id from step 4>", "heightMeters": 1.8, "actionId": <id from the library>}

```
jobs_wait
```
,
```
asset_display
```
, then
```
asset_download
```
for engine import.

使用
```
search
```
接口，设置
```
target="models"
```
、
```
query="meshy"
```
、
```
public=true
```
。单图路线对应的模型为
```
model_meshy-7-img23d
```
（编写本文时可正常访问：每次会话都需重新查找确认）。
用该ID调用
```
model_schema_get
```
，然后
```
upload_asset
```
上传角色照片（参见
```
scenario
```
skill）。

调用

model_run

，设置

dry_run=true

，

parameters={"image": ["asset_photo"], "poseMode": "t-pose", "texturePrompt": "worn leather armor, muted palette", "enablePbr": true}

来预估成本；之后使用

wait=false

重新运行，并用任务ID调用

jobs_wait

，超时则通过

pending_job_ids

重新查询，切勿重复调用

model_run

。

用
```
asset_display
```
查看GLB；在投入更多成本前，先检查轮廓和纹理是否符合要求。

用

search

查找动画成员，调用

model_schema_get

，然后运行

model_run

，设置

parameters={"model": "<第4步得到的GLB资产ID>", "heightMeters": 1.8, "actionId": <动画库中的ID>}

。

调用
```
jobs_wait
```
等待完成，用
```
asset_display
```
预览，最后
```
asset_download
```
下载资产以便导入引擎。

Common mistakes

常见错误

```
texturePrompt
```
next to
```
textureImage
```
expecting a blend: the image wins, the text is ignored.
Two style inputs on Retexture: it takes exactly one of prompt, style image, or multi-view images.
```
ultraMode: true
```
with several images: Ultra requires a single input image.
UV Unwrap on a dense mesh: above 44,000 faces the job is rejected; Remesh down first.
Rigging before Animation: Animation rigs by itself, so the chain wastes a job.
```
targetPolycount
```
on Image to 3D or Text-to-3D with
```
shouldRemesh
```
off: it does not apply.
A bare string where the schema says array: one photo goes as
```
["asset_x"]
```
.

同时设置
```
texturePrompt
```
和
```
textureImage
```
并期望两者混合：图片优先级更高，文本会被忽略。
给Retexture传入两个风格输入：它仅支持提示词、风格图片、多视角图片中的一种。
开启
```
ultraMode: true
```
的同时传入多张图片：Ultra模式仅支持单张输入图片。
对高面数网格直接使用UV Unwrap：面数超过44000的任务会被拒绝；请先使用Remesh降低面数。
在Animation之前先运行Rigging：Animation会自动完成绑定，这样的流程会浪费一次任务。
在
```
shouldRemesh
```
关闭的情况下，给Image to 3D或Text-to-3D设置
```
targetPolycount
```
：参数不会生效。
schema要求数组的地方传入了裸字符串：单张照片应以
```
["asset_x"]
```
的形式传入。