scenario-meshy

Scenario Meshy 3D

概要

Scenario 上の Meshy は単一のモデルではなく、ツールチェーンです。画像から 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 スキルを参照してください。ビューアー、キャプチャー、エンジンへのインポートなど、モデルに依存しない 3D 作業については scenario-3d スキルを参照してください。ここで名前が挙がっている関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で処理を進める場合は、ツールスキーマを基に進め、不足していることを明記してください。

クイックリファレンス

メンバーと注意点（名前はライブスキーマから取得。上限は作成時点のものです）：

Member	Core input	Watch for
7 Image to 3D	image (1-4)	ultraMode は画像を 1 枚だけ受け付けます。デフォルトでは未加工のメッシュが生成されます
7 Multi Image to 3D	image (1-4, first = front view)	実行中にリメッシュします。savePreRemeshedModel を有効にすると未加工の GLB が保持されます
T2 Smart Topology	image (1-4)	アニメーション対応のトポロジーです。targetPolycount の上限は 15,000 です
6 Text-to-3D	prompt (600 chars)	デフォルトでは shouldRemesh がオフです
Retexture	model + one style input	ジオメトリは変更されません。ポリゴン数を 30K 程度に保ちます。enableOriginalUv
Remesh	model	targetPolycount は 100～300,000、resizeHeight、originAt
UV Unwrap	model	44,000 面を超えるメッシュは拒否されます。先に Remesh でポリゴン数を減らしてください
Rigging	model, heightMeters	人型スケルトンとスキンウェイト
Animation	model, actionId	自動でリギングしてから、クリップを適用します

すべてのテクスチャ設定には、ひそかな共通ルールがあります。画像はテキストより優先されます。生成機能では textureImage が texturePrompt より優先されます（テキストは無視され、組み合わされません）。また、どちらの場合も shouldTexture をオンにする必要があります（Text-to-3D にはこの切り替え機能がなく、常にテクスチャを適用します）。Retexture ではさらに厳密で、textStylePrompt、imageStyle、multiviewImage（1～4 枚のビュー。最初の画像が正面）のいずれか 1 つだけを指定します。textureResolution は 2k、4k、8k から選択します。8k の場合、PBR マップは 4K で返され、エミッションマップはありません（Meshy 7 はエミッションマップを生成しません）。また、8k と組み合わせられるのはリメッシュ時の三角形トポロジーだけです。poseMode には小文字の "a-pose" または "t-pose" を指定します。リギングを予定しているキャラクターには、どちらかを設定してください。

未加工の状態で生成し、意図して調整する

Meshy 7 Image to 3D では shouldRemesh をオフにしておいてください（スキーマでも推奨されています）。生成時には未加工のメッシュを取得し、その後 Remesh でポリゴン数を調整します。Remesh では targetPolycount、トポロジー、メートル単位の resizeHeight（0 ならスケールを維持）、原点の配置を指定できます。ジェネレーターでは、shouldRemesh がオフの間は targetPolycount は機能しません。ultraMode を使うと追加コストでジオメトリがより精細になりますが、入力画像は 1 枚だけです。微細なディテールより隠れた側面が重要な場合は、最大 4 枚のビューに予算を使ってください。コストには大きな差があります（作成時点では、単一画像の Meshy 7 の p50 は複数画像版の 3 倍でした）。そのため、バッチ処理の前に dry_run を実行してください。

リギングとアニメーションはどちらか一方を選びます

リギングとアニメーションは代替手段であり、連続した工程ではありません。アニメーションは内部で自動的にリギングを行い、Meshy のアニメーションライブラリにある actionId で指定したクリップを適用します（ID の一覧は docs.meshy.ai/en/api/animation-library にあります）。独自のクリップに使うリギング済み GLB が必要な場合は、リギングだけを実行してください。動くキャラクターが必要な場合は、アニメーションを直接実行し、必要に応じて postProcessOperation を change_fps（postProcessFps は 24、25、30、60 のいずれか）または extract_armature に設定してください。どちらも heightMeters を基にリグのスケールを調整するため、キャラクターの実際の身長を渡してください。

実例：写真からアニメーション付きキャラクターを作成する

1. target="models"、query="meshy"、public=true を指定して search します。単一画像のルートでは model_meshy-7-img23d が該当します（作成時点でのライブ検索結果です。セッションごとに再検索してください）。search ではプランの利用可否は表示されません。作成時点では、アニメーションやリギングを含む複数の Meshy メンバーはエントリープランの対象外でした。ステップ 3 の支払い前に、capability="3d23d" とアニメーションの要件を指定して recommend し、アニメーションの項目に requires_plan_upgrade が含まれている場合は、アップグレードを提示するか、静的メッシュの作成で止めてください。そうしないと、ステップ 3 の料金が請求された後、ステップ 5 でプラン名を示す 403（ModelAccessRestrictedError）が発生します。
2. この ID を使って model_schema_get を実行し、キャラクターの写真を upload_asset します（scenario スキルを参照）。
3. 料金の見積もりには、dry_run=true と parameters={"image": ["asset_photo"], "poseMode": "t-pose", "texturePrompt": "worn leather armor, muted palette", "enablePbr": true} を指定して model_run を実行します。その後、wait=false を指定して再実行し、ジョブ ID を使って jobs_wait を実行します。タイムアウトした場合は、pending_job_ids を指定して再度呼び出します。model_run を再度実行してはいけません。
4. asset_display で GLB を表示し、さらに費用をかける前にシルエットとテクスチャを確認します。
5. アニメーションのメンバーを search し、model_schema_get を実行してから、parameters={"model": "<ステップ 4 の GLB アセット ID>", "heightMeters": 1.8, "actionId": <ライブラリの ID>} を指定して model_run を実行します。
6. jobs_wait、asset_display の順に実行し、最後に asset_download でエンジンにインポートします。

よくある間違い

• ブレンドされると思って texturePrompt と textureImage を併用する：画像が優先され、テキストは無視されます。
• Retexture にスタイル入力を 2 つ指定する：プロンプト、スタイル画像、複数視点の画像のいずれか 1 つだけを指定できます。
• 複数の画像と ultraMode: true を併用する：Ultra で使える入力画像は 1 枚だけです。
• 高密度メッシュに UV Unwrap を適用する：44,000 面を超えるとジョブは拒否されます。先に Remesh でポリゴン数を減らしてください。
• アニメーションの前にリギングを実行する：アニメーションではリギングも行われるため、工程を重ねるとジョブを無駄にします。
• shouldRemesh がオフの Image to 3D または Text-to-3D で targetPolycount を指定する：この設定は適用されません。
• スキーマで配列が指定されている箇所に文字列をそのまま渡す：写真 1 枚の場合は ["asset_x"] のように渡します。
• プレースホルダーのアセット ID を使ってステップ 5 の料金を見積もる：プランの利用可否を確認する前にファイル ID が解決されるため、ドライランは 404 を返し、料金も利用可否も確認できません。