Help — workflowsヘルプ — ワークフロー

01 A workflow is two filesワークフローは2つのファイル

In ComfyUI you build a node graph and export it with Export (API). That JSON is the first file. It is a complete, runnable graph — every value is already baked in.

ComfyUI でノードグラフを組み、Export (API) で書き出します。その JSON が1つめのファイルです。 そのまま実行できる完成したグラフで、値はすべて焼き込まれた状態になっています。

The second file is a manifest. It does not contain a graph. It contains a short list of answers to one question: which node input should each value go into? That is all grayObject needs in order to drive a graph it has never seen before.

2つめは manifest です。こちらにグラフは入っていません。入っているのは、 ひとつの問いに対する短い答えの一覧だけ —— どの値を、どのノードのどの入力に入れるのか。 初めて見るグラフでも、grayObject はこれさえあれば動かせます。

src/workflows/
  2d/
    image_z_image_turbo_fun_union_lite_2602.api.json   ← the ComfyUI graph
    image_z_image_turbo_fun_union_lite_2602.meta.json  ← the manifest
  3d/
    trellis2_grayobject.api.json
    trellis2_grayobject.meta.json

The two files must share the same name, and the manifest's id must match that name. The directory decides whether it is a 2D or a 3D workflow, and the manifest's kind has to agree. Three separate checks for the same fact, on purpose: mixing up a 2D and a 3D workflow is the one mistake that is genuinely painful to debug later.

2つのファイルは同じ名前にし、manifest の id もその名前と一致させます。 2D か 3D かはディレクトリで決まり、manifest の kind もそれに一致していなければなりません。 同じ事実を3箇所で確認するのは意図的です。2D と 3D の取り違えは、 後から追いかけると本当に厄介な唯一の間違いだからです。

02 bindings — values grayObject ownsbindings — grayObject が持っている値

A binding is written as "nodeId.inputName". The manifest below says: put the prompt text into node #8's text input, the seed into node #11's seed, and so on.

binding は "ノードID.入力名" の形式で書きます。下の manifest は 「プロンプトの文字列はノード #8 の text へ、seed はノード #11 の seed へ」と言っています。

{
  "id": "image_z_image_turbo_fun_union_lite_2602",
  "kind": "2d",
  "label": "Z-Image Turbo + Fun ControlNet Union 2.1-lite-2602",

  "bindings": {
    "prompt":     "8.text",     // node #8, input "text"
    "width":      "10.width",
    "height":     "10.height",
    "seed":       "11.seed",
    "depthImage": "1.image",
    "strength":   "6.strength"
  }
}

The // annotations above are for reading only — JSON has no comments. Use the manifest's note field if you want a remark to survive in the file.

上の // は説明のために付けたもので、JSON にコメントは書けません。 ファイルに残したい補足は manifest の note フィールドに書いてください。

These are the values grayObject already holds. You do not type them into a workflow-specific box, because they come from somewhere else in the interface: the prompt field, the aspect-ratio selector, the depth capture taken from the 3D view, a fresh random seed.

ここに並ぶのは grayObject 側がすでに持っている値 です。 ワークフロー固有の入力欄に打ち込むものではありません。値はインターフェイスの別の場所から来ます —— プロンプト欄、アスペクト比セレクタ、3Dビューから撮った depth キャプチャ、毎回新しく振る乱数 seed。

width and height are the clearest case. They are not free settings — they have to agree with the guide frame drawn over the 3D view, or "what you framed" and "what you got" stop matching. So they stay on grayObject's side of the fence, and a workflow is not allowed to override them.

width と height が一番わかりやすい例です。これは自由に決められる設定ではなく、 3Dビューに描かれるガイド枠と一致していなければなりません。ずれると「構図として合わせた範囲」と 「実際に出てきた画像」が食い違います。だからこれらは grayObject 側に置き、 ワークフローから上書きできないようにしてあります。

A 2D workflow must bind prompt, width, height, seed, and at least one image slot — either depthImage (for ControlNet-style graphs) or initImage (for img2img / edit-style graphs). A graph that consumes no capture at all is rejected: the whole point here is to turn a 3D view into an image, and a pure text-to-image graph would silently ignore the framing.

2Dワークフローは prompt / width / height / seed に加えて、画像スロットを最低1つ 束縛する必要があります —— ControlNet 系なら depthImage、img2img・Edit 系なら initImage。 キャプチャを一切使わないグラフは登録できません。ここでの目的は 「3Dビューの構図をそのまま画像にする」ことであり、純粋な text-to-image は 構図の指定を黙って無視してしまうからです。

03 params — values the workflow exposesparams — ワークフローが見せる値

Everything else — sampling steps, CFG, sampler choice — is specific to the graph. One model wants eight steps, another wants forty; some graphs have no CFG worth touching at all. These go in params, and grayObject builds the control for you.

それ以外 —— サンプリング回数、CFG、サンプラーの選択 —— はグラフごとの事情です。 8ステップで十分なモデルもあれば40必要なモデルもあり、そもそも CFG を触る意味がないグラフもあります。 こういう値は params に書きます。コントロールは grayObject が組み立てます。

"params": {
  "steps": {
    "ui":      "number",     // range | number | select | checkbox
    "label":   "ST",         // shown in the panel
    "binding": "11.steps",   // node #11, input "steps"
    "min": 1, "max": 20, "step": 1, "default": 8,
    "note":    "sampling steps — Z-Image Turbo is a few-step model"
  }
}

That one block is enough. A numeric field labelled ST appears in the generate column, remembers what you set, and its value is injected into node #11 on the next run. No markup, no CSS, no wiring.

このブロック1つで足ります。生成カラムに ST という数値入力が現れ、 設定した値を覚え、次の生成でノード #11 に注入されます。 HTML も CSS も配線コードも書きません。

There are four control types:

コントロールは4種類あります。

"cfg":      { "ui": "range",  "label": "CFG", "binding": "11.cfg",
              "min": 0, "max": 10, "step": 0.1, "default": 1 }

"sampler":  { "ui": "select", "label": "SMP", "binding": "11.sampler_name",
              "options": { "euler": "Euler", "res_multistep": "res_multistep" },
              "default": "res_multistep" }

"addNoise": { "ui": "checkbox", "label": "noise", "binding": "11.add_noise",
              "default": true }

A select injects the key string as-is, which is what node inputs like sampler_name expect. If you want to pick between numbers, use number with a coarse step instead.

select は キー文字列そのもの を注入します。 sampler_name のような入力が期待しているのはこれです。 数値から選ばせたい場合は、step を粗くした number を使ってください。

Values are remembered per workflow. Denoise 0.9 on an edit-style graph does not follow you to a ControlNet graph where the same number would mean something else; switch back and your 0.9 is still there. A reset params link restores the defaults when you have lost track.

値は ワークフローごと に記憶されます。Edit 系グラフで denoise を 0.9 にしていても、 その数字が別の意味を持つ ControlNet 系グラフには持ち込まれません。戻せば 0.9 のままです。 触りすぎて分からなくなったときのために reset params を置いてあります。

One rule worth knowing: a param may not reuse a binding's name. Both are injected through the same mechanism, so a param called prompt would quietly overwrite the real prompt. That is rejected at registration rather than left to surface as a strange result.

ひとつ覚えておくとよい規則があります。param に binding と同じ名前は使えません。 どちらも同じ仕組みで注入されるため、prompt という名前の param は 本物のプロンプトを黙って上書きしてしまいます。おかしな生成結果として表に出る前に、 登録の段階で弾いています。

04 presets — one choice, many valuespresets — ひとつの選択で複数の値

Sometimes a single decision has to move several numbers at once across several nodes. "Quality" on the 3D side is the standing example: choosing high raises the sampling steps in two different nodes, the target face count in a third, and the texture size in a fourth. A param cannot express that, so presets exists.

ひとつの判断が、複数のノードの複数の数値を同時に動かさなければならないことがあります。 3D側の「quality」がその代表です。high を選ぶと、2つのノードのサンプリング回数、 3つめのノードの目標フェイス数、4つめのテクスチャ解像度が同時に変わります。 param ではこれを表現できないので presets があります。

"presets": {
  "quality": {
    "default": "mid",
    "options": {
      "low":  { "6.shape_sampling_steps": 8,  "9.texture_size": 1024 },
      "mid":  { "6.shape_sampling_steps": 12, "9.texture_size": 2048 },
      "high": { "6.shape_sampling_steps": 25, "9.texture_size": 2048 }
    }
  }
}

The rule of thumb: one choice moving many values → preset. One value going to one place → param. Presets are drawn above params in the panel, because they read as "pick a mode first, then fine-tune".

使い分けの目安は 「ひとつの選択が複数の値を動かすなら preset、1値が1箇所へ入るなら param」。 パネルでは presets を params の上に描いています。 「まずモードを選び、そのあと微調整する」という読み順になるからです。

05 Adding one, step by step追加の手順

Build and test the graph in ComfyUI first — grayObject will not fix a graph that does not run. Then export it with Export (API), not the regular save: the two formats look similar and only the API one carries the flat nodeId → inputs shape that bindings address.

まず ComfyUI 上でグラフを組んで動作を確認します。動かないグラフを grayObject が直すことはありません。 そのうえで通常の保存ではなく Export (API) で書き出します。 2つの形式は見た目が似ていますが、bindings が指す ノードID → inputs というフラットな形を持つのは API 形式だけです。

A helper reads the exported graph and guesses the manifest for you. It follows the links backwards from the sampler and the save nodes, so it usually finds prompt, seed, size and the image inputs on its own. Treat the output as a draft, not an answer — it prints a confidence level and lists anything it was unsure about.

書き出したグラフを読んで manifest を推定するヘルパーがあります。 サンプラーや保存ノードからリンクを逆に辿るので、prompt / seed / サイズ / 画像入力は たいてい自分で見つけます。出力は答えではなく下書きとして扱ってください —— 確信度を出し、判断に迷った箇所を一覧にします。

# infer a meta.json skeleton from a graph you just exported
node scripts/gen-workflow-meta.mjs path/to/exported.api.json --kind 2d

# ...write it into src/workflows/2d/ once you have checked the report
node scripts/gen-workflow-meta.mjs path/to/exported.api.json --kind 2d --write

# verify every registered pair (this is the gate — run it after every edit)
node scripts/gen-workflow-meta.mjs --check-all

Then open the generated manifest and add what the helper cannot know: a readable label, a note naming the model files the graph needs, and any params you want on screen. The last command is the gate — run it after every edit.

そのあと生成された manifest を開き、ヘルパーには分からないことを書き足します —— 読める label、そのグラフが必要とするモデルファイルを書いた note、 画面に出したい params。最後のコマンドが門番です。編集のたびに走らせてください。

06 When it does not show up一覧に出てこないとき

A workflow that fails validation is not listed. It does not appear greyed out and it cannot be selected. This is deliberate: the alternative is a workflow that looks fine, gets picked, and fails somewhere inside ComfyUI minutes later.

検証を通らなかったワークフローは 一覧に出ません。 グレーアウトして残ることもなく、選ぶこともできません。これは意図的です。 そうしないと「見た目は正常で、選べて、数分後に ComfyUI の中で落ちる」という形になります。

The reason is printed to the browser console, and repeated by the checker:

理由はブラウザのコンソールに出ます。チェッカーも同じ内容を出します。

[workflow-registry] skipped "2d/my_workflow":
  param "steps": binding "12.steps": node #12 (KSampler) has no input "steps"

The usual causes are a typo in a node id, an input name that does not exist on that node, a default outside its own min–max, a missing required binding, or a kind that disagrees with the directory. One further trap: an input key can itself contain a dot — ComfyUI flattens dynamic widgets into keys like remesh.remesh_band — so a binding path is split at the first dot only.

よくある原因は、ノードIDのtypo、そのノードに存在しない入力名、 自分の min〜max の外にある default、 必須 binding の欠落、ディレクトリと食い違う kind です。 もうひとつ罠があります。入力キー自体にドットが含まれることがあり —— ComfyUI は動的ウィジェットを remesh.remesh_band のようなキーに畳みます —— そのため binding のパスは 最初の ドットだけで分割されます。

07 3D workflows, and multiple views3Dワークフローと多視点

A kind: "3d" workflow turns an adopted 2D back into geometry. Its required bindings are different: image, seed and filenamePrefix. The last one matters more than it looks — it is the contract with the watcher that picks the finished .glb off disk, so a workflow without it produces a file nobody collects.

kind: "3d" のワークフローは、採用した2Dをふたたび形状へ戻します。 必須の binding が2Dとは違い、image / seed / filenamePrefix の3つです。最後のものは見た目より重要で、 書き上がった .glb をディスクから拾うwatcherとの約束そのものです。 これが無いワークフローは、誰も回収しないファイルを作ることになります。

{
  "id": "trellis2_grayobject",
  "kind": "3d",

  "bindings": {
    "image":               "1.image",   // the adopted 2D — required
    "mask":                "2.image",   // its silhouette
    "seed":                ["6.seed", "7.seed"],   // same value, two nodes
    "filenamePrefix":      "10.filename_prefix",   // the .glb — required
    "imageFilenamePrefix": "11.filename_prefix"    // the 2D copy kept alongside
  }
}

mask and imageFilenamePrefix are optional, so an implementation that takes no mask can still be registered. presets and params work exactly as they do for 2D.

mask と imageFilenamePrefix は任意なので、 maskを取らない実装でも登録できます。presets と params は 2Dとまったく同じように働きます。

Extra views

追加視点

TRELLIS.2 can take up to six views — front plus back, left, right, top and bottom. Declare the ones your graph accepts as backImage, backMask and so on, and a row of toggles appears next to the Generate 3D button. Only the views you declare are offered. The front view is the adopted 2D; the extra views are captured from the source 3D model at the same distance, focal length and resolution, so the set is consistent.

TRELLIS.2 は最大6視点を取れます —— front に加えて back / left / right / top / bottom。 グラフが受け取れるものを backImage、backMask のように宣言すると、 Generate 3D ボタンの隣にトグルの行が出ます。宣言した視点だけが出ます。 front は採用した2Dそのもので、追加視点は 元の3Dモデル を 同じ距離・同じ焦点距離・同じ解像度で撮ったものです。そうしないと視点の集合が揃いません。

Worth knowing before you invest in this: the extra views only reach the shape stage. Texturing still runs from the single front conditioning. So what the extra views buy you is silhouette and orientation, not appearance — and sampling time grows in proportion to the number of views, because the model is run once per view at every step.

手を出す前に知っておく価値のあること: 追加視点が届くのは 形状 の段だけです。 テクスチャは従来どおり front 1枚の条件付けから走ります。 つまり追加視点で買えるのはシルエットと向きであって見た目ではありません。 そしてサンプリング時間は視点数に比例して伸びます。各ステップで視点の数だけモデルを回すからです。

Pruning what you did not use

使わなかったものを刈る

A view you leave off must disappear from the graph entirely — an image loader sent with an empty filename is rejected by ComfyUI before anything runs. Writing one graph per combination would mean thirty-two files, so instead each view declares the nodes that belong to it and they are removed at submit time.

OFFにした視点は、グラフから丸ごと消える必要があります —— ファイル名が空のまま送られた画像ローダーは、何かが走り出す前に ComfyUI が弾きます。 組み合わせごとにグラフを用意すると32本になるので、 代わりに各視点が「自分のノード」を宣言し、送信時に取り除く方式にしてあります。

"bindings": {
  "image": "1.image",  "mask": "2.image",
  "seed": ["6.seed", "7.seed"],
  "filenamePrefix": "10.filename_prefix",

  "backImage":  "12.image", "backMask":  "13.image",
  "leftImage":  "15.image", "leftMask":  "16.image",
  "rightImage": "18.image", "rightMask": "19.image",
  "topImage":   "21.image", "topMask":   "22.image",
  "bottomImage": "24.image", "bottomMask": "25.image"
},

"optionalGroups": {
  "back":   { "requires": "backImage",   "nodes": ["12", "13", "14"] },
  "left":   { "requires": "leftImage",   "nodes": ["15", "16", "17"] },
  "right":  { "requires": "rightImage",  "nodes": ["18", "19", "20"] },
  "top":    { "requires": "topImage",    "nodes": ["21", "22", "23"] },
  "bottom": { "requires": "bottomImage", "nodes": ["24", "25", "26"] }
}

Two rules keep this honest. List every node that belongs to that view and nothing else — there is no cascade, because a node sitting there with an unfilled optional input is indistinguishable from a healthy one. And do not list the consuming node itself: links pointing at removed nodes are dropped key and all, which is exactly how an optional input is left unspecified in the API format. Both rules are checked at registration; a node claimed by two groups is rejected.

これを健全に保つ約束が2つあります。その視点に属するノードを 漏れなく、 かつそれだけ並べること —— カスケードはしません。 optional入力が埋まっていないだけの正常なノードと区別できないからです。 そして消費側のノード自身は書かないこと。 消したノードを指すリンクはキーごと落とされ、それがAPI形式で 「optional入力を指定しない」状態そのものになります。 どちらも登録時に検査され、2つのグループが同じノードを取り合っていれば弾かれます。

One caveat specific to the TRELLIS.2 wrapper as it ships: the model is never told which direction a view came from, so it returns every prediction in a frame where that image is the front. The wrapper nonetheless assigns each view to the voxels facing it, and an asymmetric subject then comes out duplicated and rotated. This repository carries a patch — tools/comfyui/trellis2-multiview-fusion.patch — that adds a fusion choice: average every view each step, or use one view per step. Both come from the original TRELLIS multi-image pipeline and never place a view at a position, so they cannot duplicate the object. Turn the view toggles on only with that patch applied; with all of them off the workflow runs exactly like the single-view one and needs nothing.

配布されたままの TRELLIS.2 ラッパーに固有の注意がひとつあります。 モデルには「その視点がどの方向から来たか」が伝わらないため、 どの予測も その画像が正面 であるフレームで返ってきます。 それにもかかわらずラッパーは視点をvoxelの向きへ割り当てるので、 非対称な被写体では回転した2体目が生えます。 このリポジトリには tools/comfyui/trellis2-multiview-fusion.patch を 同梱してあり、fusion を選べるようにしています —— 各stepで全視点を平均するか、各stepで1視点だけを使うか。 どちらも初代 TRELLIS の多視点パイプライン由来で、視点を位置へ割り当てないため 重複が起きません。視点のトグルを入れるのはパッチを当てたときだけにしてください。 全部OFFなら単一視点のワークフローとまったく同じように走るので、何も要りません。

What the extra views actually cost

追加視点が実際に払わせるもの

Two subjects, three runs each, 1:1, same 3D seed. On a car — long, and very different from the front than from the side — front alone was good, front plus back was good, and adding left and right came out visibly squashed along the car's length. On a 3D printer, which is close to a cube, the four-view run did not collapse at all. But side by side, front alone was still the crispest of the three.

被写体2つ、それぞれ3本、1:1、3Dのseedは固定。車 —— 長く、正面と側面でまるで違う形 —— では front だけが良好、front + back も良好、left と right を足すと全長方向に目に見えて潰れました。 ほぼ立方体の3Dプリンタでは、4視点でもまったく崩れませんでした。 ただし3体を並べると、いちばんシャープなのはやはり front 単独でした。

One mechanism covers both. Every view's prediction comes back in a frame where that image is the front; the fusion patch removed the duplicate body but never made the frames agree. How much that hurts depends on how anisotropic the silhouette is. On the car the mismatch becomes a contradiction between length and width, and averaging erases the length. On the printer each view is being averaged with a 90°-rotated copy of something that looks much the same, so the shape survives and the surface detail is what gets averaged away. Back escapes the worst of it because 180° is close to a mirror — but it is still an average, so it is not free either.

機序ひとつで両方が説明できます。どの視点の予測も その画像が front であるフレームで返り、 fusion パッチが消したのは2体目だけで、フレームを噛み合わせたわけではありません。 どれだけ痛むかは、シルエットがどれだけ異方的かで決まります。 車ではそのズレが「長さ」と「幅」の矛盾になり、平均すると長さが消えます。 プリンタでは、90°回してもだいたい同じに見えるものと平均することになるので、形は生き残り、 代わりに面のディティールが平均されて消えます。 back が最悪を免れているのは 180° がほぼ鏡像だからですが、平均であることは変わらないので、 こちらもただではありません。

So the honest summary, for now: extra views buy coverage and sell sharpness, and the coverage arrives misregistered. The four 90° toggles say so and the VIEWS row warns when one is on, but nothing is blocked — your subject may be more forgiving, and a front that hides a large part of the object is still a case where coverage might win.

現時点での正直なまとめ: 追加視点は被覆を買ってシャープさを売り、 しかもその被覆はフレームがずれたまま届きます。 90°ずれた4つのトグルにはその旨を書いてあり、ONにすると VIEWS 行が警告しますが、止めはしません —— あなたの被写体はもっと寛容かもしれませんし、 front が物体の大部分を隠している場合は、依然として被覆が勝ちうる場面です。

Shoot square anyway

それでも正方形で撮る

Before it conditions on anything, the wrapper crops each view to a square around its own alpha bounding box. Each view is therefore scaled independently: a 16:9 front fills the square with the object's length, while a view straight down the side fills it with the object's width, and the model is handed a set that disagrees about how big the thing is. Choosing 1:1 before you generate the 2D removes the worst of that, because the front no longer arrives with a wildly different frame from the rest. It does not remove the effect entirely — bounding boxes follow the subject, not the canvas — so a long, front-to-back asymmetric object stays the hardest case. The VIEWS row says so when the selected card was generated at another ratio; it is advice, not a gate, and the run proceeds either way.

条件付けに入る前に、ラッパーは各視点を「その視点自身のalpha境界箱」を囲む正方形へ切り出します。 つまり視点ごとに独立して拡縮されるということです。16:9 の front は正方形いっぱいに 全長 が入り、真横からの視点は正方形いっぱいに 幅 が入る。 モデルには「その物体がどのくらいの大きさか」で食い違った集合が渡ります。 2Dを作る前に 1:1 を選んでおけば、その最悪の部分は消えます —— front だけが他とかけ離れた枠で届く、ということが無くなるからです。 ただし効果が完全に消えるわけではありません。境界箱はキャンバスではなく被写体の形で決まるので、 前後に長く非対称な物体はいちばん難しいままです。 選択中のカードが別の比率で作られていれば VIEWS 行がその旨を出しますが、 これは助言であって関門ではなく、どちらでも3D化は走ります。

Two separate things are being claimed here, and it is worth keeping them apart. The squashing above is about frames disagreeing; this is about scale. They predict the same symptom, so the car alone does not tell them apart — what it does tell us is that 1:1 is not sufficient, since the four-view run failed at 1:1. Shoot square anyway: it is free, and it removes one of the two. Then fix the 3D seed and compare against the single-view result, which is the only way to tell an improvement from a different roll.

ここでは別々のことを2つ主張しているので、混ぜないでおく価値があります。 上の「潰れ」はフレームの食い違いの話で、こちらはスケールの話です。 どちらも同じ症状を予測するので、車1件では両者を分離できません —— 分かったのは 1:1 は十分条件ではない ということだけです（4視点は 1:1 でも失敗した）。 それでも正方形で撮ってください。ただですし、2つのうち1つは確実に消えます。 そのうえで3D側のseedを固定し、単一視点の結果と比べること。 改善なのか単に別の目が出ただけなのかを見分ける方法は、これしかありません。

Last updated: 2026-08-08最終更新: 2026-08-08