> 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/plugins/m-xr-plugins/blender-add-on.md). # Blender add-on The Marso add-on brings Marso Studio into Blender. It lives in the **Marso** tab of the 3D Viewport sidebar, in five panels: * **Library** — browse your Studio projects and import finished, textured assets into your scene * **Auto PBR** — give meshes already in your scene predicted PBR materials, wired into their materials * **Retexture** — give a mesh a new look from a prompt, with PBR materials on the mesh itself * **Create** — generate an image, or bring your own, and turn it into a textured 3D asset * **Studio** — build a studio scene around your assets, animate it, and render stills and videos The add-on marks Retexture, Create and Studio as **Experimental**. It can also let the AI agents you use with Marso MCP work in your Blender. That's off until you switch it on: see [Connecting your AI agents](#connecting-your-ai-agents). Auto PBR, Retexture and Create spend credits from the same balance as the web app, and the generation runs in Marso, not on your computer. Studio runs in Blender and spends nothing. ## What you'll need * **Blender 5.2 or newer.** The add-on will not install on earlier versions. * A Marso Studio account on a paid plan, or the trial. The add-on works through the Marso Studio API, which the Free plan doesn't include. See [Plans](/marso-studio/reference/credits-and-billing.md#plans). * Credits, for Auto PBR, Retexture and Create. See [Credits & billing](/marso-studio/reference/credits-and-billing.md). * An **API key** — the add-on authenticates with a key, not a login. ## 1. Download the add-on 1. Log in to [marso.app](https://marso.app/). 2. Open **Plugins** in the left sidebar. 3. Download the **Blender** add-on. It comes as a single `.zip`. Keep the `.zip` somewhere you can find it — you'll point Blender at it in the next step. **Don't unzip it.** Blender installs the add-on from the zip as it is. > **Check back here for updates.** The add-on tells you when a new version is published, and the **Update** button brings you back to this page. There's no auto-update. ## 2. Install it in Blender 1. Open Blender. 2. Drag the downloaded file into the Blender window. Blender will ask you to confirm the install. Accept, and the add-on is enabled straight away. If drag-and-drop doesn't work: 1. **Edit → Preferences → Add-ons**. 2. Open the **▾** menu at the top right and choose **Install from Disk…**. 3. Select the downloaded file and confirm. 4. Find **Marso** in the list and tick its checkbox. ### Turn on Online Access The add-on talks to the Marso API, and Blender blocks network access for add-ons by default. Go to **Edit → Preferences → System** and enable **Online Access**. Without it, generation and update checks fail with *"Enable Online Access in Preferences > System."* ## 3. Create an API key 1. Log in to [marso.app](https://marso.app/). 2. Open **API Keys** in the left sidebar. 3. Under **New Key**, give the key a name ("Blender" is a sensible one) and click **Create Key**. 4. **Copy the key immediately.** It's shown only once. Keys begin `mxr_live_`. See [API access](/marso-studio/api/api-access.md) for managing and revoking them. > **Treat the key like a password.** Don't share it, commit it, or paste it into a `.blend` file you're sending on. If it's ever exposed, revoke it in Studio and create a new one. ## 4. Set up the add-on preferences Open **Edit → Preferences → Add-ons**, find **Marso**, and expand it. Three things need filling in before anything will run. ### API Key Paste your key here. The field is masked. ### Cache Path A folder for thumbnails and the cached project listing. Lightweight, and rebuilt automatically if you delete it. ### Downloads Path A folder for the assets you import, the PBR maps you generate, Studio's lighting and your renders. **These are your files.** Deleting them breaks the link to the asset and forces a re-download next time. The add-on writes this structure: ``` Cache Path ├── thumbnails/ project and asset preview images └── projects.json cached project and asset listing Downloads Path ├── Projects// imported 3D assets and textures ├── AutoPBR_Output/ generated PBR texture maps ├── HDRIs/ Studio's lighting environments └── Renders/ stills and videos from Studio ``` Pick paths on a drive with room to spare, and somewhere your backups already cover. > **Leave the API Endpoint alone.** It's there for development targets and is already set correctly. If you've changed it by accident, the arrow beside it resets it to the default. The preferences also hold the **Agent Connection**. See [Connecting your AI agents](#connecting-your-ai-agents). ## 5. Open the panel The add-on lives in the **3D Viewport sidebar**, which is hidden by default. 1. Hover your mouse over the **3D Viewport**. 2. Press **N** — or use **View → Sidebar**. 3. Click the **Marso** tab. At the top, the **Marso** header shows the add-on's version, your credit balance and **Launch App**, which opens Marso Studio. The menu beside it has **Check for Updates**, **Refresh Credits**, **Preferences**, **Report a Bug** and **Marso Website**. Below the header, each panel opens and closes on its own. Until the add-on is set up, a **Get started** card at the top lists what's still missing: your API key, the Cache and Downloads paths, and Online Access. **Open Preferences** takes you there. Every panel that spends credits shows the cost and your balance above its button. If you're short, it says how many more credits you need and offers **Top Up**. > **No Marso tab?** The add-on isn't enabled. Go back to **Preferences → Add-ons**, search "Marso", and check the box is ticked. If the tab strip looks crowded, widen the sidebar. ## Library With **Library** open: 1. **Projects** — click the refresh icon to sync your Studio projects. Projects with no finished assets are hidden, and assets that aren't in a project are under **Ungrouped**. 2. Click a project to open it. 3. **Assets** — tick the assets you want. There are select-all and select-none buttons, **Grid** and **List** views, and zoom controls for the grid. An asset marked **(no USD)** has no USD file yet, so it can't be imported. 4. Click **Import Selected**. Assets are downloaded to your **Downloads Path** and linked into the scene. Already-downloaded assets are reused, so a second import is instant. Under **Import options**, tick **Force Re-download** to pull a fresh copy, or **Auto Place** to spread the imported assets out in a compact grid so they don't overlap. Your library is restored from cache when you reopen a `.blend`, so the panel isn't empty every time. ## Auto PBR With **Auto PBR** open: 1. Select the meshes you want in the viewport. 2. Click **Add Selected Objects** to put them in the queue. 3. Check the cost and your balance, shown above the button. 4. Click **Generate PBR**. The button shows how many meshes it will run. The queue accepts several meshes, and they're processed in turn. Use the **–** and **bin** icons to remove one job or clear the queue — only possible while nothing is running. Every mesh in the queue is charged, so trim it before you generate rather than after. Costs are the same as the equivalent node in the web app: see [Credits & billing](/marso-studio/reference/credits-and-billing.md). > **What you get back:** albedo, metallic, roughness, IOR and normal, predicted by I2M and wired into the mesh's material. The maps are written to `AutoPBR_Output/` in your Downloads Path. ### If a run is interrupted Closing the file or quitting Blender mid-run cancels it. When you come back, the panel flags any jobs left unfinished and offers a **Reset** button. Use it, then queue the meshes again. ## Retexture **Experimental.** Retexture gives the selected mesh a new look from a prompt, predicts PBR materials for it, and puts the maps on the mesh's own material. Nothing is imported, and the mesh keeps its UV layout. 1. Select the mesh. The panel names it next to **Mesh:**. 2. Describe the new look, for example "a red soda can with a white wave logo". 3. Check **Prompt Enhance**. It starts as "lots of detail realistic lighting and shading" and is added to the end of your prompt. Delete it to send the prompt exactly as you typed it. 4. Add a reference image if you want one (see below). 5. Check the cost, then click **Retexture**. The status line shows each step while it runs, and Blender stays usable. When it's done, the albedo, metallic, roughness, IOR and normal maps are on the mesh's material. If the edit flags a quality problem, the warning shows under the button. In Marso Studio, each run is a **Load 3D Model**, an **Edit 3D Model** and a **Generate PBR Textures** node, in a project called **Blender AddOn**. It's charged as one Edit 3D Model run and one Generate PBR Textures run: see [Credits & billing](/marso-studio/reference/credits-and-billing.md). **What the mesh needs:** * **A UV map.** A mesh with none shows **Auto UV Unwrap**, on by default, which unwraps it before upload. Untick it and the button stays off with *UV map required*. * **A colour texture.** A mesh with UVs but no base-colour texture gets a blank 4K one, filled with its material's base colour, so it can be sent. * **Textures up to 4096 px.** Anything larger is refused before anything is sent. **A reference image:** under **Reference (optional)**, pick an image, such as a fabric swatch. Give it a short label (`reference` by default) and write `@` and the label in your prompt where it applies: "change only the side panels to @tartan". **Insert @reference**, or your own label, adds it to the prompt for you, and a note says whether your prompt uses it. With no `@` label in the prompt, the image guides the look overall. Large, clearly bounded parts take a selective change best; small ones, such as a logo, tend to spill onto their neighbours. ## Create **Experimental.** Create makes a new textured 3D asset in two steps. What you make is saved in Marso Studio, in a project called **Blender AddOn**. **1 Image:** describe a single object and click **Generate Image**, or click **Import Image** to use a picture of your own. Importing is free. **2 3D Asset:** 1. Pick the 3D model: **Hunyuan 3D 3.1 Pro** (the default), **Meshy 6**, **Meshy 7**, **Meshy 7.1** or **Tripo H3.1**. 2. Pick the **Polygons**. A count other than the model's default costs more, and the panel says so. 3. For Meshy, pick a texture **Resolution** (2K, 4K or 8K). For Tripo, pick a texture **Quality** (Standard or Detailed). 4. Click **Create 3D Asset**. The cost card above the button prices your exact choice, the 3D model and its PBR together. **Wait for minted USD** decides when the asset arrives. Off, it's imported as soon as its PBR materials are done, but that USD has no real-world scale, description or physics yet. On, the add-on waits a few more minutes for Marso to finish the USD, and imports that. ## Studio **Experimental.** Studio builds a scene around your assets and renders it, all in Blender, so it spends no credits. Work through its tabs from left to right: * **Setup** — **Create Scene** builds a studio in one click: a ground, a camera, lighting and render settings. * **Camera** — pick the **Subject**, the zoom and the **Aspect**, and adjust the framing. * **Light** — choose the HDRI, its brightness and its rotation. A set of studio HDRIs downloads to `HDRIs/` in your Downloads Path the first time you open Studio. * **Animate** — **None**, **Turntable** to spin the subject through a full turn, or **Showcase** to arrange several objects on a grid, reveal them one by one and fly the camera past. * **Render** — set the quality, resolution and output, then **Render Image** or **Render Animation**. **Render Passes** also writes image sequences of a mask and the base colour, metallic, roughness and IOR. Renders go to `Renders/` in your Downloads Path unless you choose another folder. ## Connecting your AI agents Turn on **Connect to Marso Agents**, under **Agent Connection** in the add-on preferences, then add Marso MCP to your chat app. Agents signed in to the same Marso account can then put Marso assets into your scene, give its meshes PBR materials, light, animate and render it, and show you the results in the chat. The Marso header shows **Agents connected as** your email, with **Connect** and **Disconnect**. Blender connects out to Marso MCP with your API key, so nothing listens on your computer. Agents can't change the add-on's settings, its key or its folders, open files on your computer, run code, or use the Create and Retexture panels. To add Marso MCP to your chat app, see [Connect your agent](/marso-studio/mcp/connect-your-agent.md). For what agents can do here, see [Blender and Isaac Sim](/marso-studio/mcp/blender-and-isaac-sim.md). ## Keeping the add-on up to date The add-on checks for a new version shortly after Blender starts, and quietly does nothing if there isn't one. When there is, a banner at the top of the panel says **Update available**, with the version, and an **Update** button that opens the Plugins page in Marso Studio. You can also check by hand with **Check for Updates** in the header's menu. Both need your API key set and Online Access enabled. To update, download the new version and install it the same way — Blender replaces the existing one and your preferences are kept. ## Troubleshooting | What you see | What it means | | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No **Marso** tab in the sidebar | The add-on isn't enabled. **Preferences → Add-ons**, tick **Marso**. | | *Set your API key in addon preferences.* | The API Key field is empty. See step 3. | | *Set storage paths in addon preferences.* | One or both of Cache Path and Downloads Path is unset. Both are required. | | *Enable Online Access in Preferences > System.* | Blender is blocking the add-on's network access. See step 2. | | *Invalid API key. Update it in Preferences > Add-ons > Marso.* | The key is wrong or has been revoked. Create a new one (step 3) and paste it into **API Key**. | | *Your Marso plan does not include this. Check your plan at marso.app.* | Your account is on the Free plan, or its trial has ended. The add-on needs a paid plan or the trial: see [Plans](/marso-studio/reference/credits-and-billing.md#plans). | | *No projects cached. Click Refresh.* | Nothing synced yet. Click the refresh icon on the **Projects** panel. | | *No projects with assets yet.* | Your projects have no finished assets to import. Generate something in Studio first. | | *UV map required* | The mesh has no UV map. Tick **Auto UV Unwrap**, or unwrap it yourself. | | Won't install at all | Check your Blender version. 5.2 is the minimum. | | A generation fails or the balance is short | The panel shows how many more credits you need, with **Top Up**. | Anything else, or a result that looks wrong: [Contact Support](/marso-studio/help-and-support/contact-support.md). --- # 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/plugins/m-xr-plugins/blender-add-on.md?ask=&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.