> For the complete documentation index, see [llms.txt](https://docs.m-xr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.m-xr.com/marso-studio/reference/nodes-reference.md).

# Nodes reference

Marso Studio is built around **nodes**. Each node is one step — generate a scene, break it into objects, generate or load an asset, generate or edit an image, apply materials. Connect a node's output to the next node's input to build a pipeline.

When you create a project you choose how to start, and the starting nodes are placed for you:

| Option           | You start with                                                                                                                                                   |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Scene**        | **Generate Image** (Scene tab) → **Detect Objects** → **Generate Reference Images (Group)** → **Generate 3D Models (Group)** → **Generate PBR Textures (Group)** |
| **Single asset** | **Load 3D Model** → **Generate PBR Textures**                                                                                                                    |
| **Blank**        | An empty canvas                                                                                                                                                  |

Nodes are grouped into **Image**, **3D**, **PBR** and **Utility**, the same as the add-node menu, which **Add** on the canvas toolbar opens. The **(Group)** nodes run the same step across every object in a scene, and are charged per object.

## Image

### Load Image

Upload an image to use as a starting point in your pipeline. The node has two buttons: **Upload** takes a file from your computer, and **From library** opens your library so you can pick an image that's already there with **Use in Load Image**. The node keeps its place and its links either way. You can also add a library image from **Library** on the canvas toolbar: see [Library & collections](https://docs.m-xr.com/marso-studio/reference/library-and-collections.md).

* **Input:** image file: PNG, JPG or WebP, up to 20 MB
* **Output:** image
* **Cost:** no credits

### Generate Image

Generate an image from a text prompt. The node has two tabs:

* **Object** — a single object, for the single-asset route into **Generate 3D Model**.
* **Scene** — a whole environment rather than a single object. This is the first node in a Scene project, and it feeds **Detect Objects**.

A Scene-tab image connects to **Detect Objects** or **Edit Image**, not straight to 3D generation.

On the **Object** tab you can also connect images for it to work from. With one image connected, the node works from it. With more than one, name each in your prompt: type **@** and pick the image from the list, and it shows as a chip with its thumbnail.

* **Input:** text prompt, and on the Object tab, optionally images to work from
* **Output:** image
* **Cost:** 10 credits

**Earlier runs are kept.** The node keeps a strip of every result it has produced, newest first. Click one to make it the node's output again.

**You can run it again before a run ends.** The new run starts at once, and you can have up to five image runs going at a time. The node counts the runs in progress, such as *Generating 3 images*, and each one shows in the strip: click it to watch that run.

### Generate Multiview

Generate a multi-view set of an object from a single image — useful for a stronger 3D reconstruction.

* **Input:** image
* **Output:** multiple views of the object
* **Cost:** 12 credits: 2 per view, for six views. Regenerating a single view costs 2.
* **Plan:** any paid plan, or the trial

Only **Hunyuan 3D 3.1 Pro** accepts multi-view input, so this node feeds a Hunyuan generation. See [Choosing a generator](#choosing-a-generator).

### Edit Image

Edit or refine an existing image with a prompt. Connect the image you're editing to the main input: it sets the base, the aspect ratio and the resolution of the result. You can also connect reference images to the second input. Name each one in your prompt with **@**, the same as on Generate Image.

* **Input:** an image and a prompt, plus optional reference images
* **Output:** edited image
* **Cost:** 10 credits
* **Plan:** any paid plan, or the trial

**Earlier runs are kept.** The node keeps a strip of every result it has produced, newest first. Click one to make it the node's output again.

**You can run it again before a run ends.** The new run starts at once, and you can have up to five image runs going at a time. The node counts the runs in progress, such as *Editing 3 images*, and each one shows in the strip: click it to watch that run.

### Generate Reference Images (Group)

Generate a clean reference image for each object you selected in **Detect Objects**, ready for 3D reconstruction.

* **Input:** the confirmed object selection
* **Output:** one reference image per object
* **Cost:** 10 credits per object
* **Plan:** any paid plan, or the trial

How many objects it can take from one detection depends on your plan. See [Plans](https://docs.m-xr.com/marso-studio/reference/credits-and-billing.md#plans).

> Each object needs to fill most of its reference image for 3D generation to succeed. Objects that were small or heavily occluded in the scene are the usual failures.

## 3D

### Load 3D Model

Upload your own 3D asset (`.glb`, `.usdz` or `.fbx`). See [3D file support](https://docs.m-xr.com/marso-studio/preparing-your-assets/3d-file-support.md). This is the starting node in a Single asset project. To reuse a 3D model that's already in your library, click **From library** on the node and pick it with **Use in Load 3D Model**, or add it from **Library** on the canvas toolbar: see [Library & collections](https://docs.m-xr.com/marso-studio/reference/library-and-collections.md).

* **Input:** 3D file
* **Output:** 3D model
* **Cost:** no credits

### Generate 3D Model

Turn an image into a 3D mesh. The object should fill most of the image — sparse or distant subjects often fail.

* **Input:** an image, or a multi-view set
* **Output:** 3D model
* **Cost:** 30–120 credits, depending on which generator you pick. On Hunyuan 3D 3.1 Pro, a custom face count makes it 55 and multi-view input 60. An **8K** or **Detailed** texture adds 10, except on Tripo P2: see [Texture](#texture).

#### Choosing a generator

Reconstruction is the one stage where no single model wins on every subject, so **Generate 3D Model** lets you pick which one runs. **They are not all priced the same:**

| Generator                          | Single image | Custom face count     | Multi-view input |
| ---------------------------------- | ------------ | --------------------- | ---------------- |
| **Tripo H3.1**                     | **30**       | 30 — no extra charge  | Not supported    |
| **Hunyuan 3D 3.1 Pro** *(default)* | **40**       | 55 *(+15)*            | **60**           |
| **Meshy 6**                        | **45**       | 45 — no extra charge  | Not supported    |
| **Meshy 7**                        | **45**       | 45 — no extra charge  | Not supported    |
| **Meshy 7.1**                      | **45**       | 45 — no extra charge  | Not supported    |
| **Tripo P2**                       | **120**      | 120 — no extra charge | Not supported    |

Four things worth taking from that table:

* **Tripo H3.1 is the cheapest option** — and cheaper than the default.
* **The three Meshy models cost the same**, 45 credits, with a custom face count included. On one asset the spread between generators is small; across a twenty-object scene it's 1,430 credits on Tripo H3.1 against 1,730 on Meshy, so **check which generator is selected before you run anything at scale**. See [Credits & billing](https://docs.m-xr.com/marso-studio/reference/credits-and-billing.md).
* **Tripo P2 is the low-poly option, and the most expensive.** Its face counts run from 500 to 50,000, where the other generators start at 30,000 or more. At 120 credits it costs four times Tripo H3.1, so a twenty-object scene is 3,230 credits on P2.
* **Only Hunyuan 3D 3.1 Pro takes multi-view input.** The **Generate Multiview** node feeds Hunyuan generations.

Hard-surface props, organic shapes and busy reference images all favour different models, and the differences are hard to predict from the image alone. **If a mesh comes back wrong, re-running the same reference image through a different generator is usually a better move than changing the image** — just check what the switch costs first if you're working at scene scale. Switching generator re-runs the generation, charged at that generator's rate.

Whichever you pick, the mesh feeds the same **Generate PBR Textures** stage afterwards. The generator decides your geometry and base colour; I2M decides your materials.

**Custom face count** — you can set a target polycount instead of taking the default. It's offered on every generator, but only **Hunyuan 3D 3.1 Pro charges for it**: +15 credits, so 55 in total, and on Hunyuan it's single-image only, not multi-view. On Tripo H3.1, Tripo P2 and the Meshy models a custom face count is included in the base price. A custom face count, and multi-view input, need a paid plan or the trial.

#### Texture

On the Meshy models and the two Tripo models, the node also has a **Texture** setting. Hunyuan 3D 3.1 Pro has none.

| Generator                               | Texture                                  | Credits    |
| --------------------------------------- | ---------------------------------------- | ---------- |
| **Meshy 6**, **Meshy 7**, **Meshy 7.1** | **2K** or **4K** *(default)*             | **45**     |
|                                         | **8K**                                   | 55 *(+10)* |
| **Tripo H3.1**                          | **Standard** *(default)*                 | **30**     |
|                                         | **Detailed**                             | 40 *(+10)* |
| **Tripo P2**                            | **Standard** *(default)* or **Detailed** | **120**    |

A custom face count still costs nothing extra on these generators, whatever the texture setting.

### 3D Retexture

Change the texture of a 3D model with a prompt, and optionally a reference image. The mesh, the UVs and the size of the model stay the same, and it changes the base colour only.

* **Input:** a GLB or USDZ model of up to 550 MB (a model you uploaded, a mesh from **Generate 3D Model**, or a model from your library), a prompt of 3 to 3,000 characters, and optionally one reference image
* **Output:** 3D model, in the same format as the model you gave it, ready for **Generate PBR Textures**
* **Cost:** 30 credits, or 120 with **One view at a time**
* **Plan:** any paid plan, or the trial

Two tabs on top of the prompt box set what the node starts from:

* **Edit texture** *(default)* keeps the current texture and its detail, and changes only what your prompt asks for.
* **New texture** starts from a plain surface and ignores the current texture. Use it to paint a new look from your prompt.

To match a colour, a pattern or a material, connect an image to the **Reference image** input and name it in your prompt with **@**, the same as on Generate Image.

**Advanced settings**, at the foot of the node, holds **One view at a time**. Normally the node paints four views of your model together. With this switch on, it paints them one at a time. A run takes longer and costs 120 credits, and the node shows the price under the switch. It's marked **Experimental**, so results can vary.

Click **Retexture** to run it. To capture an image of the result, drag from its output and choose **Capture Image**.

### Generate 3D Models (Group)

Run **Generate 3D Model** for every image in a Reference Images group — one mesh per object. The generator you pick applies to every object.

* **Input:** a Reference Images group
* **Output:** one 3D model per object
* **Cost:** the generator's price, per object
* **Plan:** any paid plan, or the trial

You can set a polygon count for every object at once on the group, or give one object its own on its card. **Adaptive** keeps the generator's default. A custom count is charged as a [custom face count](#choosing-a-generator) for each object that has one, so on Hunyuan 3D 3.1 Pro it adds 15 credits per object.

The [texture](#texture) works the same way: set it on the group, or give one object its own on its card. **Inherit group** takes the group's setting.

## PBR

### Generate PBR Textures

Run I2M to predict a PBR material stack for a textured 3D model or an image. On a 3D model it's **albedo, metallic, roughness, IOR and normal**. On an image it's **albedo, metallic, roughness, IOR and normal**, plus **displacement** if you choose it.

* **Input:** a textured 3D model, or an image of at most 2048 pixels on each side. With a 3D model, optionally a conditioning image
* **Output:** from a 3D model, the textured 3D model and its PBR maps; from an image, the PBR maps
* **Cost:** 30 credits on a 3D model. On an image, 35 up to 1 megapixel and 40 above, plus 10 for **Make tileable** and 10 for **Displacement**

With an image connected, the node also has **Tiling** and **Displacement**:

* **Tiling** is **Not tiled**, **Already tiled** (the image already repeats, so the maps tile without a seam too) or **Make tileable** (the image is made to repeat first, which can change its size and shape).
* **Displacement** adds a height map. It shows as a grey layer in the viewer and never moves the preview geometry.

A bigger image than 2048 pixels on a side is refused, not shrunk. See [Make a material from an image](https://docs.m-xr.com/marso-studio/reference/make-a-material-from-an-image.md#choosing-a-tiling-mode).

**Conditioning image.** With a 3D model connected, the node takes a second input, **Conditioning image**: an image that guides the look of the predicted materials. Connect one image to it, from any image node. Leave it empty and Studio chooses an image for the model, where one applies. It costs nothing extra. With an image on the main input, the node says *Connect a 3D model to use a conditioning image.* In the API, it's `conditioning_image_asset_id` on `POST /pbr/execute/mesh`: see [PBR](https://docs.m-xr.com/marso-studio-api/api/pbr) in the API reference.

**Material ball.** On a material made from an image, the node's preview shows the material on a rendered ball. **Material ball** and **Albedo**, under the preview, switch between the ball and the plain albedo map.

Generated meshes are compressed automatically before texturing. Compression is free and needs no node.

A finished node keeps its result. On a 3D model, connect, change or remove the conditioning image to run it again, for another 30 credits: until then, hovering **View 3D** says *PBR complete. Change the conditioning image to run again.* On an image, it says *PBR complete. Create a new PBR node for fresh textures.*

### Generate PBR Textures (Group)

Run **Generate PBR Textures** for every model in a 3D Models group, or make a material from every image in a Reference Images group.

* **Input:** a 3D Models group, or a Reference Images group
* **Output:** from a 3D Models group, one textured model, with its PBR maps, per object; from a Reference Images group, the PBR maps for each image: albedo, metallic, roughness and IOR
* **Cost:** 30 credits per object or image
* **Plan:** any paid plan, or the trial

## Utility

### Detect Objects

Break a scene image into its individual objects. Returns a list of detected objects with a preview, which you then review and confirm before any generation runs. Everything is selected by default.

* **Input:** an image of a scene, and at least one category to look for: Environment, Set Dressing, Props or Furniture
* **Output:** a set of detected objects
* **Cost:** 20 credits per run
* **Plan:** any paid plan, or the trial

You can run it again with different categories if the decomposition isn't right: each run costs the same 20 credits. See [Choosing what to keep](https://docs.m-xr.com/marso-studio/reference/scene-generation.md#choosing-what-to-keep).

## Credit costs at a glance

| Node                                                     | Credits                                        |
| -------------------------------------------------------- | ---------------------------------------------- |
| Load Image                                               | —                                              |
| Generate Image                                           | 10                                             |
| Generate Multiview                                       | 12 (2 per view)                                |
| Edit Image                                               | 10                                             |
| Generate Reference Images (Group)                        | 10 per object                                  |
| Load 3D Model                                            | —                                              |
| Generate 3D Model (single image)                         | 30–120, by generator                           |
| Generate 3D Model (multi-view — Hunyuan 3D 3.1 Pro only) | 60                                             |
| Generate 3D Model — custom face count                    | +15 on Hunyuan 3D 3.1 Pro · free on the others |
| Generate 3D Model — **8K** or **Detailed** texture       | +10 · free on Tripo P2                         |
| 3D Retexture                                             | 30, or 120 with **One view at a time**         |
| Generate 3D Models (Group)                               | the generator's price, per object              |
| Generate PBR Textures, on a 3D model                     | 30                                             |
| Generate PBR Textures, on an image                       | 35 up to 1 MP, 40 above                        |
| Generate PBR Textures, Make tileable or Displacement     | +10 each                                       |
| Generate PBR Textures (Group)                            | 30 per object                                  |
| Detect Objects                                           | 20 per run                                     |

On a scene, how many objects you keep moves the cost most, and your 3D generator sets what each one costs. See [Choosing a generator](#choosing-a-generator) above, and [Credits & billing](https://docs.m-xr.com/marso-studio/reference/credits-and-billing.md) for how credits work and how to budget a scene.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.m-xr.com/marso-studio/reference/nodes-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
