higgsfield-3d

Higgsfield 3D — Meshes, Rigs, and 3D Jutsu Scenes

QUICK FACTS

*Routing aids — read the linked sections for the full rules. Nothing in this sub-skill is field-tested.*

• 17 3D models in the 2026-09-26 snapshot, six jobs: single image→3D, multi-view→3D, text→3D, rig, remesh / retexture, 3D Body →
• THE law: the mesh reproduces only what is in the source image — to add or change props, clothing or held objects, edit the IMAGE first, then convert the edited result →
• Multi-view beats single-view for geometry: 2–4 views of the same subject → multi_image_to_3d / tripo_h3_1_multiview_to_3d →
• The prompt field: the MCP schema says only sam_3_3d accepts one; the CLI marks it REQUIRED on the three text→3D models — send it there, confirm with get_cost →
• Server-enforced rules: animation needs rigging; texture options need texturing ON; Hunyuan std caps the prompt at 200 characters and has no PBR →
• Rig + animate: humanoids rig best; animation_action_id comes from a 678-action library (ids 0–696, not contiguous — look up, never guess) →
• get_cost: true preflights for free; never auto-resubmit after a transport timeout →
• 3D Jutsu = private Blender 5.2 scene projects: inspect (query) → guarded edit (run) → show_scene LAST →
• A generated GLB cannot enter a 3D Jutsu scene — imports are curated-catalog assets only in this version →
• Film use 1: a mesh turnaround as a multi-angle reference — UNMEASURED →
• Film use 2: a 3D blockout rendered front-on from the camera's side becomes the SOURCE FRAME for the staging template — UNMEASURED →

---

What this sub-skill is for

Higgsfield now generates 3D assets (GLB meshes, optionally textured, PBR-mapped, rigged

and animated) and hosts 3D Jutsu, a private Blender scene editor driven through Python.

This sub-skill documents what each surface is for, what its parameters are, the rules the

server enforces, and the two uses that matter to this repo's film work: a consistent

multi-angle reference, and a physical staging reference.

It is a routing and discipline layer, the same as the rest of this library: it picks

the model and writes the inputs; the execution surface (MCP connector, CLI, web UI) runs

the job — see ../higgsfield-stack/SKILL.md.

Everything here comes from the platform's own schemas (provenance at the end). No 3D

job and no 3D Jutsu edit has been run from this repo. There are no quality rankings, speed

claims or prices in this file — none were measured, so none are stated.

Not this sub-skill: Cinema Studio 2.5's *3D Mode* (Gaussian splatting inside a

generated image) — that is ../higgsfield-cinema/SKILL.md § 3D Mode. And not a Blender

tutorial: 3D Jutsu's Python surface is documented only as far as its tool contracts go.

---

The catalog — 17 models, six jobs

[OFFICIAL — platform, 2026-09-26] — ../../specs/models_explore_snapshot_3d_2026-09-26.json.

../../scripts/sync_specs.py has no 3D type yet, so there is no generated 3D spec table: this

table is read straight from the snapshot. Names and providers are as the snapshot states

them.

| Job | Model id | Snapshot name · provider | Input |

|---|---|---|---|

| Single image → 3D | sam_3_3d | SAM 3 3D Objects · Meta | 1 image (role image) |

| Single image → 3D | image_to_3d | Image to 3D · Meshy | 1 image (role image) |

| Single image → 3D | meshy_image_to_3d | Image to 3D · Meshy | 1 image (role image) |

| Single image → 3D | meshy_v7_image_to_3d | Meshy 7 Image to 3D · Meshy | image (role image_references) |

| Single image → 3D | tripo_h3_1_image_to_3d | Tripo H3.1 Image to 3D · Tripo | image (role image_references) |

| Single OR multi-view → 3D | hunyuan3d_v3_image_to_3d | Hunyuan3D v3 Image to 3D · Tencent | "one image or multiple views" (role image_references) |

| Multi-view → 3D | multi_image_to_3d | Multi-Image to 3D · Meshy | 1–4 images of the same subject (role image) |

| Multi-view → 3D | meshy_multi_image_to_3d | Multi-Image to 3D · Meshy | 1–4 images of the same subject (role image) |

| Multi-view → 3D | tripo_h3_1_multiview_to_3d | Tripo H3.1 Multiview to 3D · Tripo | 2–4 ordered views (role image_references) |

| Text → 3D | meshy_v6_text_to_3d | Meshy 6 Text to 3D · Meshy | prompt |

| Text → 3D | hunyuan3d_v3_1_text_to_3d | Hunyuan 3D v3.1 Text to 3D · Tencent | prompt |

| Text → 3D | tripo_3d | Text to 3D · *(provider, description and tags blank in the snapshot)* | prompt |

| Rig an existing mesh | 3d_rigging | 3D Rigging · Meshy | model_url (a GLB) |

| Rig an existing mesh | meshy_rigging | 3D Rigging · Meshy | model_url (a GLB) |

| Remesh | meshy_v5_remesh | Meshy 5 Remesh · Meshy | model_url |

| Retexture | meshy_v5_retexture | Meshy 5 Retexture · Meshy | model_url + text or image style |

| Human body → 3D | sam_3_3d_body | 3D Body · Meta | 1 photo of people (role image_references) |

Three duplicate pairs. image_to_3d / meshy_image_to_3d, multi_image_to_3d /

meshy_multi_image_to_3d and 3d_rigging / meshy_rigging carry the same name, provider

and parameter list in the snapshot. The MCP generate_3d schema names the unprefixed

ids as its defaults, and CLI 1.1.23 model get knows only the unprefixed ids (the

meshy_-prefixed three return No model with job_type). Use the unprefixed ids. Whether

the pairs share a backend is not stated anywhere — do not claim it.

Picking a model

| You have / want | Use | The schema's reason |

|---|---|---|

| One image, one object in a busy frame — lift just that object | sam_3_3d | "Lift a single image of an object"; the only image→3D model that takes a prompt — "to disambiguate which object to lift"; detection_threshold 0–1; export_textured_glb:false for a white mesh |

| One image, texture + PBR + rig + animation in one job | image_to_3d | Optional texturing, PBR, rigging, animation. should_texture defaults OFF |

| Same, with a low-poly geometry mode or higher-fidelity geometry | meshy_v7_image_to_3d | model_type standard / lowpoly; ultra_mode ("higher-fidelity geometry and finer surface detail"); should_texture defaults ON |

| Face-count control, quads, real-world scale, orientation matched to the photo | tripo_h3_1_image_to_3d | face_limit 1,000–2,000,000; quad; auto_size; orientation: align_image; texture_alignment |

| Geometry-only or low-poly output | hunyuan3d_v3_image_to_3d | generate_type Normal / LowPoly / Geometry; face_count 40,000–1,500,000 (default 500,000). The densest ceiling in the catalog is Tripo H3.1's face_limit (up to 2,000,000) |

| 2–4 views of the same subject | multi_image_to_3d | "More views = better geometric accuracy"; same feature set as image_to_3d |

| 2–4 views, Tripo controls | tripo_h3_1_multiview_to_3d | "2 to 4 ordered views" — the order convention is not in the schema; check the model page before relying on it |

| Only a description | meshy_v6_text_to_3d | mode preview (geometry only) / full (textures); lowpoly; can rig + animate |

| Only a description, Tencent | hunyuan3d_v3_1_text_to_3d | mode std ("rapid") / pro ("higher-quality"); PBR, generate_type, face_count are pro-only |

| Only a description, with a negative prompt | tripo_3d | negative_prompt; texture + PBR default ON; texture_quality / geometry_quality standard / detailed |

| A mesh that needs a skeleton | 3d_rigging | Takes model_url, not images |

| A mesh with bad topology or the wrong size / pivot | meshy_v5_remesh | topology triangle / quad; target_polycount 100–300,000; resize_height; origin_at bottom / center |

| A mesh that needs a new surface | meshy_v5_retexture | text_style_prompt or image_style_url (image wins when both are set); enable_original_uv default ON |

| A photo of a person — body shape + pose | sam_3_3d_body | "Reconstruct human body shape and pose as a GLB"; per-person PLY meshes, 3D keypoints, Meta Human Representation (MHR) metadata |

When unsure, the connector's own instruction is to call models_explore(action:'recommend')

before any generate_* tool [OFFICIAL — Higgsfield MCP server instructions, 2026-09-26].

---

The source-image law

[OFFICIAL — Higgsfield MCP tool schema, generate_3d, 2026-09-26] verbatim:

> "The mesh reproduces only what is in the source image — to add or change props,

> clothing, or held objects, edit the image first with generate_image, then convert the

> edited result."

What that means in practice (the first three lines restate the schema; the rest is labeled):

• Fix it in 2D, then lift it. A missing prop, the wrong jacket, an empty hand — all

of it is an image edit before it is a 3D job. There is no mesh-side "add a sword".

• Retexturing is the one post-hoc surface change the catalog offers

(meshy_v5_retexture); geometry changes go back to the image.

• The image-side tools for that edit are the image sub-skills this library already has —

../higgsfield-gpt-image-2/SKILL.md (reference sheets, edits) and

../../templates/ad-asset-prep.md (prop three-views, product sheets).

• [INFERENCE — untested] A single-view source shows one side of the subject; the model

has to supply the rest. That is the problem multi-view input exists to reduce (next

section) — plan the source images for the angles you will need, not just the pretty one.

---

Multi-view beats single-view

[OFFICIAL — platform, 2026-09-26] multi_image_to_3d: *"1-4 images of the same subject

from different angles … More images improve geometric accuracy."* The MCP schema says the

same: use it "when 2-4 views of the same subject are available (better geometric

accuracy)".

• Same subject is the whole condition. Four images of four slightly different

characters are not four views. [INFERENCE — untested] Views cut from one generated

sheet are more likely to agree than four separate generations — the same reasoning the

cinema sub-skill applies to location sheets (../higgsfield-cinema/SKILL.md § Location

Reference Sheets: alt angles "from a single seed" keep light and material consistent).

• Role names differ by model: Meshy multi-image takes role image (max 4); Tripo

multiview and Hunyuan take image_references. The server "may auto-coerce when

unambiguous" — still pass the declared role.

• Tripo wants its views ordered, and the order is not published in the schema. Do not

guess a front / left / back / right convention into a delivery.

---

The prompt field — two surfaces disagree

• [OFFICIAL — Higgsfield MCP tool schema, generate_3d, 2026-09-26]: *"Optional text

guidance. Only sam_3_3d accepts a prompt (to disambiguate which object to lift). Other 3D

models ignore it."*

• [OFFICIAL — platform CLI 1.1.23, higgsfield model get <id> --json, 2026-09-26]: prompt

is required on meshy_v6_text_to_3d, hunyuan3d_v3_1_text_to_3d and tripo_3d;

optional (default empty) on sam_3_3d; absent from every image-input, rig, remesh,

retexture and body model.

The MCP sentence is accurate for the image-input models and cannot be literally true for

text→3D (a text→3D job with its prompt ignored has no input). **Do not settle it by

guessing:** for text→3D, send the prompt, and run get_cost: true first — the server

returns adjustments showing what it did with the request before anything is spent. For

texture direction on the image-input models, the fields are texture_prompt /

texture_image_url (Meshy) — not prompt.

---

Parameter rules the server enforces

[OFFICIAL — platform CLI 1.1.23, model get rules, 2026-09-26] — each is a server-side

constraint; breaking one rejects the job.

| Model(s) | Rule |

|---|---|

| image_to_3d, multi_image_to_3d, meshy_v7_image_to_3d, meshy_v6_text_to_3d | enable_animation requires enable_rigging=true |

| image_to_3d, multi_image_to_3d, meshy_v6_text_to_3d | animation_action_id is required when enable_animation=true (meshy_v7 defaults it to 92) |

| image_to_3d, multi_image_to_3d, meshy_v7_image_to_3d | texture_prompt, texture_image_url and enable_pbr each require should_texture=true |

| meshy_v6_text_to_3d | texture options (texture_prompt, texture_image_url, enable_pbr) require mode=full; rigging_height_meters requires enable_rigging=true |

| hunyuan3d_v3_1_text_to_3d | in mode=std: prompt ≤ 200 characters, no generate_type, no face_count, no enable_pbr (PBR needs pro); enable_pbr is ignored with generate_type=Geometry |

| hunyuan3d_v3_image_to_3d | enable_pbr unsupported with generate_type=Geometry; polygon_type=quadrilateral requires generate_type=LowPoly |

| meshy_v5_retexture | text_style_prompt or image_style_url is required |

| tripo_h3_1_* | "Enabling PBR also enables textures" (schema description) |

Two defaults that bite: image_to_3d / multi_image_to_3d return an untextured

mesh unless should_texture: true is set; meshy_v7_image_to_3d textures by default.

Meshy target_polycount defaults to 30,000 (range 100–300,000); Meshy should_remesh

defaults on, and when off, "returns the raw triangular mesh and topology/target_polycount

are ignored".

---

Rigging and animation

[OFFICIAL — platform, 2026-09-26] + [OFFICIAL — Higgsfield MCP tool schema, 2026-09-26]

• Two routes to a rig: enable_rigging: true on a generating model (Meshy image,

multi-image, 6 text, 7 image), or 3d_rigging on a mesh you already have. 3d_rigging

takes model_url — a public HTTPS GLB without embedded credentials, or (per the MCP

schema) a prior 3D job_id.

• Humanoids rig best. The schema's own caveat: "Works best on humanoid/character

subjects; non-bipeds (animals, objects) may rig poorly."

• Pose: pose_mode a-pose / t-pose — "Recommended with enable_rigging for cleaner

skeletons." rigging_height_meters (default 1.7) scales the skeleton.

• Animation: enable_animation: true + animation_action_id. The library holds **678

actions with ids in 0–696** — the ids are not contiguous, so never compute or guess

one. The schema's named picks: idle 0, walk 30 (Casual_Walk), run 16 (RunFast),

jump 466 (Regular_Jump), wave 28 (Big_Wave_Hello), dance 64 (All_Night_Dance).

• Look it up: MCP animation_actions (read-only, no job; groups WalkAndRun,

BodyMovements, DailyActions, Dancing, Fighting; each result carries a preview GIF — when

several fit, show the previews and let the user pick) or CLI

higgsfield preset list animation-action --query walk.

• Rigging and animation each add cost (schema wording) — preflight.

---

Cost and submission discipline

• Preflight is free: MCP generate_3d with get_cost: true "preflights credits

without submitting"; CLI higgsfield generate cost <model_id> [--param value]…. Apply the

adjustments the server returns. This file lists no prices — they were not measured.

• Cost drivers the schema names: texturing ("Costs more credits"), rigging and

animation ("Adds cost"). count 1–4 multiplies the job.

• Timeouts: "On a transport timeout the submission outcome may be unknown: do not

automatically resubmit. Reuse returned job IDs and retry only after the original outcome

is known."

• Inputs: medias[].value is a media_id or a prior job_id, never a URL (web media

goes through media_import_url; local files through media_upload_widget). The

exception is the model_url field on rig / remesh / retexture, which is a URL — for

remesh and retexture the snapshot says to upload the GLB through the media API with

type=file and pass the returned URL.

• Surface choice and the general two-step preflight: ../higgsfield-stack/SKILL.md

§ Preflight discipline.

---

3D Jutsu (Scene Builder 3D)

[OFFICIAL — Higgsfield MCP tool schema, scene_builder_3d_*, 2026-09-26]

A private project holding a Blender scene that an agent edits by running Python

against it; results deliver as a GLB (portable) or a .blend (editable source).

| Step | Tool | Contract |

|---|---|---|

| Find or make a project | scene_builder_3d_list_projects / scene_builder_3d_create_project | Creation is not idempotent — on an interrupted or uncertain create, list projects before retrying, or you make a duplicate |

| Read state | scene_builder_3d_get_project | Revision, scene sequence, active operation, committed artifacts. An empty project is a valid empty scene at revision 0 |

| Inspect | scene_builder_3d_query_python | bpy + artifacts; temporary changes are discarded; can render and publish preview images without committing; returns the guards revisionBefore + sceneSequenceAfter |

| Edit | scene_builder_3d_run_python | One coherent edit against the exact inspected revision + expectedSceneSequence, with a stable operationId; advances revisionAfter. One mutation per project at a time; on a stale-state conflict, inspect again and regenerate with fresh guards and a new operation id |

| Add a model | scene_builder_3d_search_assets → scene_builder_3d_import_asset | Curated catalog GLBs only; copy the search result's importArguments (incl. catalogSearch); never repeat an import to poll it |

| Wait | scene_builder_3d_get_operation | Poll an active operation (waitSeconds max 8) |

| Deliver | scene_builder_3d_show_scene | The final 3D Jutsu call, with the exact committed revision. The widget is for the user — it is not visual evidence for the agent |

| Verify | scene_builder_3d_get_artifact | Fetch a render a query or edit published; inspect it before judging framing, light or geometry |

| Export | scene_builder_3d_get_glb / scene_builder_3d_get_blend | Short-lived downloads of an existing export; "a successful download does not establish that the exported scene looks correct" |

Engine facts the schema pins:

• Blender 5.2; engines BLENDER_EEVEE, BLENDER_WORKBENCH, CYCLES (not

BLENDER_EEVEE_NEXT). Query RNA rather than assuming older APIs exist.

• Build at metre scale with descriptive object names. For a new multi-object scene,

establish the delivery camera, a motivated key light, fill and ambient light in the first

blockout.

• Committed scenes are finalized with Eevee and Khronos PBR Neutral. Procedural

shaders and world lighting "do not reliably carry into GLB" — use Principled materials and

Point / Sun / Spot lights when GLB delivery matters.

• Published files: at most 8 PNG / JPEG / MP4 per operation, 512 MiB each, 1 GiB total,

images ≤ 16,384 px per side and ≤ 64 MP. Python code ≤ 256 KiB.

• Coordinates: the editor / glTF side is Y-up; bpy is Z-up — account for it when

comparing transforms.

What 3D Jutsu cannot take in

• scene_builder_3d_import_asset: "This version accepts catalog assets only." and

"Attachment IDs are not supported by this tool."

• run_python / query_python: "No network fetches or embedded model bytes; use

scene_builder_3d_import_asset."

So **a GLB from generate_3d — or the user's own model — has no documented way into a 3D

Jutsu scene** in this version. A Jutsu scene is built from catalog assets plus geometry

made in bpy. Say this before anyone promises "put my generated character in the scene".

---

Film use 1 — a 3D turnaround as a multi-angle reference

[HYPOTHESIS — UNMEASURED; nothing below has been fired]

The idea. Image-generated turnarounds draw every angle separately, and each angle can

drift. A mesh has one geometry: render it from any angle and the angles agree by

construction. That is the property worth testing.

The chain.

1. Build the source images — ideally 2–4 views of the subject as one sheet — and fix

every prop, garment and held object in the image first (§ The source-image law).

2. multi_image_to_3d (or tripo_h3_1_multiview_to_3d) with should_texture: true;

get_cost: true first.

3. Render the GLB from the angles the production needs. Where: 3D Jutsu cannot import

it (§ What 3D Jutsu cannot take in), so the renders happen in any GLB viewer or the

user's own Blender, outside Higgsfield.

4. Use the renders as image references — character-sheet panels, @ Elements, Seedance

image references.

What is not known — say it, don't paper over it:

• Whether a textured mesh holds a face's identity. For faces this library's route is

Soul ID and character sheets (../higgsfield-soul/SKILL.md); a mesh render is not a

substitute until someone measures it.

• Whether a rendered-CG reference bleeds its render look into a photoreal video. The

staging-reference work measured that a graphic-looking reference *can* bleed, and closed

it with a three-layer architecture (../../templates/seedance/staging-reference.md); the

same risk plausibly applies to mesh renders and is untested.

• A reasonable first probe: a rigid prop — no face, no cloth, nothing that deforms — is

the case with the least to lose.

Higgsfield's own image-side turnaround path is its character-sheet workflow — see

../higgsfield-stack/SKILL.md § Higgsfield's bundled workflows for when to hand off to it.

---

Film use 2 — a 3D blockout as a staging reference

[HYPOTHESIS — UNMEASURED; nothing below has been fired]

This library already names the right shape for a reference a video model sees:

../../templates/seedance/staging-reference.md — front-on, from the camera's side,

thin muted-colour outlines, attached last, described in positive form only. And

../../templates/seedance/top-down-map.md — a floor plan is for reasoning, never

attached. A 3D scene can serve both, because a camera placed in a scene renders exactly

the shape the doctrine asks for.

What 3D adds. Real perspective, relative scale in metres, and a camera you can put

where the shot's camera actually is — the geometry a hand sketch only approximates.

The chain.

1. Block it in 3D Jutsu at metre scale. Stand-in figures (bpy primitives or catalog

assets from scene_builder_3d_search_assets) with descriptive names, the anchoring

furniture, and one delivery camera at the shot's position, height and lens.

2. Render front-on through that camera with scene_builder_3d_query_python (a query

render publishes a PNG without committing a revision) and fetch it with

scene_builder_3d_get_artifact.

3. That render is not the staging reference — it is the source frame. A Blender render

has shaded, solid figures; layer 1 of the anti-bleed architecture is *outlines, never

fills*. Feed the render to Step 1 of staging-reference.md (the diagram-generation

prompt) exactly as the template feeds a real frame: it converts the frame into the thin

muted outline drawing, with the same colour legend, tag naming and QA checklist.

4. Write the words from the scene data. The template requires every figure's

position, pose and facing to be spelled out in words ("the words carry the staging").

query_python returns exact object names, positions in metres and transforms — the

per-figure lines can be read off the scene instead of eyeballed.

5. Optional floor plan: a render from an overhead camera of the same scene is a

top-down map — reasoning only, per top-down-map.md; never attached.

6. Coverage: move the camera, render again, run Step 1 again. The template's rule —

*regenerate from the original frame, never from the previous diagram* — holds

automatically, because every diagram is drawn from a fresh render of the same geometry.

The measured caveat still governs. The staging reference tracked the map's

orientation 6/12 — chance (staging-reference.md). A more accurate source geometry

does not change what the video model does with the map. Offer this as a sharper shared

*authoring* artifact; when a position must hold, back it with the prose blocking locks the

template points to.

A third, smaller possibility — sam_3_3d_body turns a photo of a person into body shape,

pose and 3D keypoints — could supply a pose from a reference photo. Its GLB cannot enter

3D Jutsu either; unmeasured.

---

Provenance and what is not known

• Catalog: ../../specs/models_explore_snapshot_3d_2026-09-26.json

[OFFICIAL — platform, 2026-09-26] (17 models, has_more: false). The snapshot ages out

of the 30-day trust window on 2026-10-26 — after that, verify live (HARD RULE 3):

models_explore(type:'3d') or higgsfield model get <id>.

• Tool contracts: generate_3d, animation_actions, scene_builder_3d_*

[OFFICIAL — Higgsfield MCP tool schema, 2026-09-26] — read from the connector's tool

definitions; no tool was called.

• Prompt requirements and CEL rules: `[OFFICIAL — platform CLI 1.1.23, higgsfield model

get <id> --json, 2026-09-26]` — free schema reads, no job created.

• Not known: output quality, speed, price, how any 3D model handles faces, how a

mesh-derived reference behaves in a video model, the Tripo view order, whether the

duplicate Meshy ids share a backend. Nothing here was fired.

Related skills

• ../higgsfield-stack/SKILL.md — execution surfaces, preflight, and Higgsfield's own character-sheet workflow
• ../higgsfield-gpt-image-2/SKILL.md — reference sheets and image edits (the "edit the image first" step)
• ../higgsfield-soul/SKILL.md — face identity (the route a mesh does not replace)
• ../higgsfield-cinema/SKILL.md — Cinema Studio 2.5 3D Mode (Gaussian splats — a different "3D")
• ../../templates/seedance/staging-reference.md · ../../templates/seedance/top-down-map.md — the staging doctrine Film use 2 plugs into