--- name: upload-and-validate-3d-models description: >- Upload 3D models to benchy.world and understand the file-check pipeline: ingest grants, single or multipart transfer, initial preflight, server-enforced marketplace policy, explicit check coverage, print-readiness assessment, and recovery. Use when uploading model files, publishing versions, debugging checks, or explaining publishing and paid-sale eligibility. title: Upload and Check 3D Models date: 2026-09-30 author: Benchy tags: [benchy, 3d-models, validation, mesh, mcp, skill] license: MIT metadata: version: "2.3.0" schemaVersion: 2 surface: "world_* MCP tools · benchy.world" --- # Upload and check 3D models on Benchy **Last verified:** 2026-10-22 for the upload steps, formats and print files; 2026-10-07 for the check limits by file size; 2026-09-30 for creator access; 2026-09-26 for presentation labels; 2026-08-20 for the remaining workflow. Discover current MCP schemas before using the workflows below. Uploading, publishing and selling on World are open to approved creators. For anyone else, requesting a model upload, creating or updating a listing, pricing an offer, seller onboarding and membership plans refuse with the error code `creator_not_approved`. Say that selling is open to approved creators and point to [Selling on World](https://benchy.world/docs/selling); do not retry. Buying, downloads, memberships, makes and comments never need approval. Uploading, checking, and publishing are separate states. A completed upload means the bytes were stored. It does not mean the file passed a publishing or commerce policy. ## Pipeline at a glance ```text world_request_model_upload → upload session + scoped grant → transfer bytes exactly as the response instructs → world_finalize_upload → finalized model key + byte evidence → world_create_model → hosted file checks → model state updated with the current policy result ``` ## 1. Uploading Supported upload declarations are `glb`, `gltf`, `stl`, `obj`, `usdz`, `3mf`, and `step` (`.step` or `.stp`), up to 250 MiB per model file. Public publishing checks currently support GLB, glTF, STL, OBJ, and 3MF. A STEP file is checked as CAD and gets a display copy for viewing; it can be published or sold only when the listing has no `additive` workflow. USDZ can remain Private or Unlisted, but cannot be published publicly or sold. STL and OBJ require an explicit coordinate-unit assumption: `um | mm | cm | m | in | ft`. 1. **Request** — `world_request_model_upload { format, units?, expectedBytes, originalFilename? }` returns an upload session and exact transfer instructions. `units` is required for STL and OBJ and must be one of `um | mm | cm | m | in | ft`. 2. **Transfer** — follow the response exactly, including its URL, grant, and single or multipart method. Do not derive a URL or storage key. 3. **Finalize** — `world_finalize_upload { uploadSessionId, uploadedBytes }` verifies the completed session and returns the `modelKey`, exact size, and file evidence. `uploadedBytes` is the size you sent, and must equal `expectedBytes`. 4. **Create** — `world_create_model` with the returned `modelKey`. The client never chooses a storage key. A stored upload remains available to its owner even when later checks deny or cannot establish eligibility. A Public create requires `primaryLens`, `license`, and `provenance: "human" | "ai_assisted" | "ai_generated"`; STL and OBJ must reuse the coordinate unit selected before transfer. ### Print files A sliced `.gcode` or `.bgcode` (up to 128 MiB, not compressed) joins an existing listing's package: `world_request_print_file_upload { filename, expectedBytes }`, transfer, `world_finalize_upload`, then `world_attach_print_file { modelId, modelKey, path, sizeBytes }` with the same filename as `path`. Attaching publishes a patch release; on a paid model it pauses the offer until the offer is saved again. Then `world_add_print_profile` with the returned `artifactId` as `printFileArtifactId` says how it was sliced. ## 2. Initial preflight and server policy The two runs have different contracts: - **Initial preflight** uses `validationProfile: structural` and `executionMode: client_advisory`. It provides quick content-based format and framing feedback. It cannot grant paid-sale eligibility and cannot overwrite a completed server decision. - **Marketplace policy** is the hosted, server-enforced result over the stored bytes. This is the only v2 context that can grant paid-sale eligibility. Read the server's publishing and commerce eligibility fields. The server checks the current policy, completed marketplace/server-enforced evidence, required coverage, and the binding to the model's bytes, format, and units. It distinguishes blocking findings from advisory geometry notes according to the listing's workflows. An engine name or raw `allow`/`deny` verdict alone is not an eligibility decision. Older results do not grant current eligibility. Read the current validation state and follow its recovery action. ### Current validation availability by size | Stored file size | Current server-enforced validation | | ---------------------- | ------------------------------------------------------------------------------------------- | | ≤ 4 MiB | Checked in place; a file that reaches a processing limit there is re-checked with more room | | > 4 MiB, up to 250 MiB | Checked with the larger limits: 3,000,000 triangles, 9,000,000 vertices, 4,096 meshes | File size alone does not establish eligibility: geometry, processing limits and a supported format all have to pass as well. Read the returned decision and coverage before reporting publishing or purchase availability. An upload can remain stored and owner-accessible when checks cannot complete. See [Models and uploads](https://benchy.world/docs/models-and-uploads) for the current product limits. A creator-declared unit may be used as a policy assumption for formats that do not declare units; the report then marks `unitBasis: assumed` and emits `UNITS_ASSUMED`. ## 3. Reading schema v2 The current report uses `schemaVersion: 2` and the policy version reported by the service: - `identification`: `detectedFormat`, confidence, inferred media type, and evidence. Detection is not structural validation. - `decision`: `verdict` (`allow | deny | inconclusive`) and stable `reasonCodes`. - `checks[]`: stable check id, `status` (`passed | failed | not_run | unsupported`), `coverage` (`full | sampled | header_only | metadata_only | none`), and evidence or issue codes. - `issues[]`: stable code, severity, check id, message key, display message, and optional typed parameters. Automations branch on codes and parameters, never on English messages. - `printReadiness`: `assessment` (`ready | needs_attention | not_ready | not_assessed`), prerequisite checks, notes, and limitations. The labels are **Print geometry checked**, **Print geometry has notes**, **Review print geometry**, and **Print suitability not assessed**. These describe print geometry separately from publishing eligibility. - `metadata`: observations such as counts, bounds, unit basis, coverage, and topology. Closed-surface and edge-manifold conclusions appear only when explicit topology evidence supports them. - `engines`: implementation provenance. Use the v2 decision, check, issue, identification, and readiness fields. ## 4. Product-state mapping | Contract state | User-facing language | | ---------------------------------------------- | ------------------------------------------------------------------------------------------- | | Upload stored; checks not started | **Uploaded** | | Pending or running | **Checking file** | | Server confirms current publishing eligibility | **File checks passed**, or **File checks passed with notes** for advisory geometry findings | | Blocking file-check finding | **Needs attention**, or the specific unsupported/private-only format label | | Retryable server execution failure | **Checks incomplete** — no publishing decision; select **Retry checks** or replace the file | | Completed server marketplace `inconclusive` | **Can't be listed yet** — follow the file's recovery guidance | | Unsupported format issue | **Unsupported file type** | Do not say “safe,” “verified,” “printable,” “watertight,” or “manifold” unless the exact named property was checked with sufficient coverage. Do not infer a policy decision from the engine name. ## 5. Publishing and paid-sale gates - Public is an intent while checks run: the model stays unlisted until current checks grant eligibility. Choosing Unlisted or Private cancels that intent. - Prepare a paid offer from the model's existing release and protected files. Read the current offer, package inspection, file-check, and seller payout state before reporting purchase availability. Discover the hosted server's current marketplace tools and schemas; use [Selling on World](https://benchy.world/docs/selling) for the product workflow. - Pending, client, structural, standalone, inconclusive, v1, stale-byte, and stale-unit results do not qualify. - Correct a denied file or its declared units, then submit it for checks. Use the returned retry action for a transient processing failure. ## 6. Troubleshooting - PUT returns 401/403 — the grant expired or does not match the key. Request a new upload session; do not reuse grants. - PUT returns 413 — the payload exceeds the grant or must use multipart. - Model creation cannot find the object — finalize the upload before create. - UI remains on **Checking file** — re-read later. If the owner view offers **Retry checks**, use it; otherwise contact Benchy support rather than diagnosing internal services. - **Needs attention** — inspect stable issue and reason codes, repair the file, and publish a new version. - **Checks incomplete** — no publishing decision was made. If the owner UI offers **Retry checks**, select it; otherwise use a supported self-contained format, replace the file, or contact [Benchy support](mailto:help@benchy.studio).