# glTF/GLB & FBX to USD, USDZ, FBX converter + rig verification (`ernestx/gltf-to-usd-validated`) Actor Convert glTF/GLB and FBX to USD, USDC, USDA, USDZ, GLB or FBX with headless Blender. Textures ship with the file, every animation clip survives, rigs verified by re-import: bones, per-vertex skin weights, animated poses. Readiness report for Unreal, Unity, three.js, AR, 3D printing. - **URL**: https://apify.com/ernestx/gltf-to-usd-validated.md - **Developed by:** [Jean-Baptiste Couche](https://apify.com/ernestx) (community) - **Categories:** Automation, Developer tools, AI - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $50.00 / 1,000 conversion completeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## glTF, GLB or FBX in — USD, USDZ, GLB or FBX out, with proof Give it a URL to a `.glb`, `.gltf` or `.fbx`, pick any of six output formats, and get back a complete asset — textures included, every animation clip intact — plus a report on what shape the file is really in and whether the rig actually survived the trip. Headless Blender 4.5 LTS underneath. No UI, no login, built to sit inside a pipeline, callable by agents over MCP. The source format is detected from the file's bytes, not its extension. A URL can be called anything; the file cannot lie about its own header. ### The thing most converters get wrong "Did it convert?" is the easy question. Every converter answers it. The question that actually costs you an afternoon is different: *the file came out, so why does it break in my slicer / look wrong in Unreal / arrive at 100× scale / show up untextured?* That depends less on the conversion than on what you're about to do with the asset. So instead of a pass/fail badge, each run tells you what the asset is ready *for*: ```` ``` Box.glb DamagedHelmet.glb ``` realtimeEngine READY READY texturing NOT READY READY csgBoolean READY NOT READY threeDPrinting READY NOT READY ```` `DamagedHelmet` is great in an engine and hopeless in a slicer — an open shell with a few non-manifold edges. `Box` is a clean watertight cube you could print tomorrow, shipped with no UVs at all. Both facts are useful. Neither shows up in an exit code. ### Rigs are verified, not assumed For anything skinned or animated, the Actor exports the file and then **imports it back** and compares the result against the source. Not "an armature exists" — the actual numbers: - every bone name and its parent - bone head positions, compared strictly - **skin weights, per vertex, per influence** - the rig evaluated **in motion**, sampled per animation clip across each clip's own frame range On the Khronos `Fox.glb`: 24/24 bones, identical hierarchy, 1 728 vertices with **zero weight mismatches**. On a Mixamo character (`Samba Dancing.fbx`, 67 bones, two skinned meshes, 97 vertex groups): everything intact through an FBX round-trip. And the verification is honest about its own limits, which matters more than it sounds. Formats rename animations, keep only one clip, or resample curves — so the pose check reports one of four explicit statuses instead of a fake boolean: `identical`, `within-resampling-tolerance`, `unalignable` (nothing to compare across this format boundary — structure and weights were still fully verified), or `deviation-found`. Only the last one counts against the verdict. A checker that cries wolf on a perfect rig is worse than no checker, and the first version of this one did exactly that until it was tested against reality. Two genuine catches from that testing, left here because they are exactly what you'd want this tool to tell you: - routing that same Mixamo character **through USD** loses skin-weight fidelity — the report flags `skinWeightsIdentical: false` instead of letting you find out in the engine; - a glTF→glTF round-trip resamples animation beyond codec tolerance on some rigs, and gets flagged as `deviation-found`. One Blender-specific note the report also makes for you: bone *tails* are a Blender display concept, rebuilt on every import — glTF, FBX and USD store joints as transforms. Tail differences are listed as information, never as damage. Bone heads are what's compared strictly. ### FBX is written for studios, not for previews Blender's FBX exporter defaults quietly lose data, and every one of them is overridden here: | Setting | Blender default | This Actor | Why it matters | |---|---|---|---| | `mesh_smooth_type` | OFF | **FACE** | no smoothing groups is the #1 Blender-FBX complaint in Maya/Max | | `use_tspace` | off | **on** | no tangents → normal maps light wrongly | | `use_custom_props` | off | **on** | the importer reads them; the exporter was throwing them away | | `add_leaf_bones` | on | **off** | stops Blender inventing bones your rig never had | | `bake_anim_simplify_factor` | 1.0 | **0.0** | lossless animation curves | | `embed_textures` | off | **on** | one self-contained deliverable | Every animation take ships inside the one FBX (`bake_anim_use_all_actions`). On import, the same care applies in reverse: no automatic bone reorientation, no baked-in transforms, Maya pre/post rotations preserved. The report lists these choices under `exportSettings`, so you can see what was decided rather than trusting that something was. ### Every animation clip survives — per format, the right way USD binds one `SkelAnimation` per skeleton, and Blender's exporter only writes the active action — so a glTF carrying three clips would silently lose two. For USD outputs, each clip is therefore exported as its own file alongside the base asset (`CLIP_Survey`, `CLIP_Walk`, `CLIP_Run` for the Fox). FBX and GLB carry every take natively in the single file, so no side files are emitted there — that would just ship duplicate data. Either way, `completeness.allAnimationClipsDelivered` tells you explicitly that what went in came out. ### Textures come with the file Blender writes referenced textures into a sibling directory rather than embedding them. Ship only the model file and every material points at something that doesn't exist. So when a conversion produces more than one file you get a ZIP preserving the relative layout, and everything resolves. `DamagedHelmet` delivers 3.16 MB — USD plus its four textures — instead of 1.13 MB of dangling references. Shortcuts: `usdz` bundles textures inside the file itself (the same helmet comes back as one self-contained 3.98 MB `.usdz`, ready for Quick Look), and `fbx` embeds media too. ### Two details that trip naive validators **Split vertices aren't damage.** glTF gives a vertex its own copy whenever it needs a second normal or UV, so a plain cube arrives as 24 vertices in six disconnected quads — and a naive topology check reports a perfect cube as 24 non-manifold edges. This Actor welds coincident vertices before classifying topology, then separates genuine non-manifold edges from ordinary open boundaries. **Scale and axis bite everyone eventually.** glTF says Y-up, metres. Blender rotates to Z-up on import. USD carries its own `upAxis` and `metersPerUnit`. Every report spells out the conversion chain, the asset's real dimensions, and whether that size looks sane for something a human would build. ### Input | Field | Type | Required | Default | | |---|---|---|---|---| | `glbUrl` | string | yes | — | Public URL to a `.glb`, `.gltf` (embedded buffers) or `.fbx` (embedded media), up to 200 MB | | `outputFormat` | string | no | `usdc` | `usdc`, `usda`, `usd`, `usdz`, `glb`, `fbx` | | `verifyRoundTrip` | string | no | `auto` | Re-import and compare. `auto` runs whenever the asset is rigged or animated | | `exportAllClips` | boolean | no | `true` | One USD per clip (USD outputs only; FBX/GLB don't need it) | | `strictValidation` | boolean | no | `false` | Bail out with no conversion charge when the file is genuinely broken | ### What comes back The deliverable is under `OUTPUT` in the run's key-value store — a ZIP when there's more than one file, the bare file otherwise, with `outputKind` telling you which. The dataset record carries `status`, a `manifest` of every file shipped, `clipOutputs`, and the full `report`: readiness verdicts, per-check severities with plain-language meanings, scene stats, the axis/unit block, clip completeness, and — for rigged assets — the round-trip rig comparison with its `verificationCompleteness` breakdown. The unabridged report lives under `REPORT_FULL`. ### Billing One `conversion-completed` event per run that hands you a file. Failed download, Blender crash, strict-mode rejection: no conversion event charged. If the billing call itself ever fails, your conversion still completes — losing a good result over an accounting hiccup would be absurd. ### Verified against Every cell of this matrix executed end-to-end on Apify, not assumed: | Source | → usdc | → fbx | → glb | |---|---|---|---| | `Fox.glb` (rigged, 3 clips) | rig intact | rig intact | pose deviation flagged | | `Samba Dancing.fbx` (Mixamo, 67 bones) | weight loss **flagged** | rig intact | — | | `BrainStem.glb` (rigged) | rig intact | rig intact | — | | `DamagedHelmet.glb` (5 textures) | ✓ + textures | ✓ 2.07 MB | — | | `Box.glb`, `ABeautifulGame.glb` (1.5 M tris) | ✓ | — | — | The Docker build refuses to finish unless Blender starts headless and every importer/exporter this Actor depends on actually exists — an operator rename in a future Blender breaks the build here, not a run on your side. ### Where it's still thin Multi-file sources (a `.gltf` with external `.bin`, an `.fbx` referencing loose textures) won't find their siblings — only self-contained files work. Material fidelity is not verified: the round-trip compares structure and deformation, not shader graphs. Pose verification across format boundaries is sometimes `unalignable` (formats rename or merge clips) — structure and weights are still checked, and the report says exactly which parts were verifiable rather than pretending. No production character with UDIM tiles and facial blendshapes has been through it yet; the reference set is Khronos plus Mixamo. # Actor input Schema ## `glbUrl` (type: `string`): Publicly reachable URL to a .glb, .gltf with embedded buffers, or .fbx, up to 200 MB. The format is detected from the file header, not the extension. An FBX referencing external texture files will not resolve them - use embedded media. ## `outputFormat` (type: `string`): Any source format converts to any target. FBX is written with studio-fidelity settings rather than Blender's defaults: smoothing groups on, tangents exported, custom properties kept, no invented leaf bones, animation curves unsimplified, and every animation take in the one file. ## `verifyRoundTrip` (type: `string`): Re-imports the USD that was just written and compares vertex, triangle, bone, skinning and animation counts against the source. The only reliable way to know a rig survived export. 'auto' runs it whenever the asset is skinned or animated. ## `exportAllClips` (type: `boolean`): USD binds one animation per skeleton, and Blender exports only the active action, so a source with several clips would silently lose all but one. With this on, each clip is written as its own USD file under a CLIP_ key. Turn off only if you want the active clip alone. ## `strictValidation` (type: `boolean`): If enabled, no output is delivered and no conversion event is charged when the file is genuinely unusable (no geometry, or the glTF failed to import). Defects such as non-manifold edges or missing UVs are reported as warnings and the file is still delivered - see the readiness block in the report to decide per use case. ## Actor input object example ```json { "glbUrl": "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/Box/glTF-Binary/Box.glb", "outputFormat": "usdc", "verifyRoundTrip": "auto", "exportAllClips": true, "strictValidation": false } ```` # Actor output Schema ## `convertedAsset` (type: `string`): The converted file, stored under the key OUTPUT. When the conversion produced more than one file (textures written alongside the USD, or one file per animation clip) this is a ZIP preserving the relative layout, so material and clip references resolve. Otherwise it is the bare USD. Check outputKind and outputContentType in the dataset record to know which. ## `validationReport` (type: `string`): One dataset item per run, containing readiness verdicts, per-check severities, scene statistics, axis and unit conventions, animation-clip completeness, and — for rigged assets — the round-trip rig comparison. ## `runInConsole` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "glbUrl": "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/Box/glTF-Binary/Box.glb" }; // Run the Actor and wait for it to finish const run = await client.actor("ernestx/gltf-to-usd-validated").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "glbUrl": "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/Box/glTF-Binary/Box.glb" } # Run the Actor and wait for it to finish run = client.actor("ernestx/gltf-to-usd-validated").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "glbUrl": "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/Box/glTF-Binary/Box.glb" }' | apify call ernestx/gltf-to-usd-validated --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ernestx/gltf-to-usd-validated", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "glTF/GLB & FBX to USD, USDZ, FBX converter + rig verification", "description": "Convert glTF/GLB and FBX to USD, USDC, USDA, USDZ, GLB or FBX with headless Blender. Textures ship with the file, every animation clip survives, rigs verified by re-import: bones, per-vertex skin weights, animated poses. Readiness report for Unreal, Unity, three.js, AR, 3D printing.", "version": "0.1", "x-build-id": "o5GFDpuNcgASh3t9Y" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ernestx~gltf-to-usd-validated/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ernestx-gltf-to-usd-validated", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/ernestx~gltf-to-usd-validated/runs": { "post": { "operationId": "runs-sync-ernestx-gltf-to-usd-validated", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/ernestx~gltf-to-usd-validated/run-sync": { "post": { "operationId": "run-sync-ernestx-gltf-to-usd-validated", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "glbUrl" ], "properties": { "glbUrl": { "title": "Source model URL (glTF/GLB or FBX)", "type": "string", "description": "Publicly reachable URL to a .glb, .gltf with embedded buffers, or .fbx, up to 200 MB. The format is detected from the file header, not the extension. An FBX referencing external texture files will not resolve them - use embedded media." }, "outputFormat": { "title": "Output USD format", "enum": [ "usdc", "usda", "usd", "usdz", "glb", "fbx" ], "type": "string", "description": "Any source format converts to any target. FBX is written with studio-fidelity settings rather than Blender's defaults: smoothing groups on, tangents exported, custom properties kept, no invented leaf bones, animation curves unsimplified, and every animation take in the one file.", "default": "usdc" }, "verifyRoundTrip": { "title": "Verify by re-importing the result", "enum": [ "auto", "always", "never" ], "type": "string", "description": "Re-imports the USD that was just written and compares vertex, triangle, bone, skinning and animation counts against the source. The only reliable way to know a rig survived export. 'auto' runs it whenever the asset is skinned or animated.", "default": "auto" }, "exportAllClips": { "title": "Export every animation clip", "type": "boolean", "description": "USD binds one animation per skeleton, and Blender exports only the active action, so a source with several clips would silently lose all but one. With this on, each clip is written as its own USD file under a CLIP_ key. Turn off only if you want the active clip alone.", "default": true }, "strictValidation": { "title": "Reject on validation errors", "type": "boolean", "description": "If enabled, no output is delivered and no conversion event is charged when the file is genuinely unusable (no geometry, or the glTF failed to import). Defects such as non-manifold edges or missing UVs are reported as warnings and the file is still delivered - see the readiness block in the report to decide per use case.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```