Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(trellis2): document the new default lane, the territory rule and the MODEL_TRELLIS2_URL env, with a changelog entry
nirholasa74cd22dd27a
diff --git a/.env.example b/.env.exampleindex 8aebeb4bb..fb54b32ab 100644--- a/.env.example+++ b/.env.example@@ -1453,6 +1453,9 @@ GCP_RECONSTRUCTION_URL=# (forge backend `trellis_selfhost`). Fuses up to 6 turnaround views of one# subject into a single textured GLB; unset ⇒ the lane drops out of routing.MODEL_TRELLIS_URL=+# TRELLIS.2 worker (workers/model-trellis2), the default image-to-3D lane (forge backend+# `trellis2`). Unset skips the lane; the chain behind it serves the request.+MODEL_TRELLIS2_URL=# workers/model-hunyuan3d → self-hosted Hunyuan3D-2 image→3D# (forge backend `hunyuan3d`, gcp provider mode `hunyuan`). NOT the same as# GCP_RECONSTRUCTION_URL, whose avatar face pipeline rejects non-face images.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 325663ce4..1aca28290 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Tutorial · Grok Bot recipes** (`/tutorials/grok-bot-recipes`): Six jobs to hand Grok Bot, each with the exact sentence, the tools it calls in order, and the real output of running that sequence against production: a daily 3D brief, a game jam asset pack, an avatar from a photo, an X post image as a 3D model, a weekly agent report and a $THREE market brief.- **A build plan for the next 27 platform upgrades**: We surveyed the strongest open-source crypto and agent projects, compared them with three.ws, and wrote the plan for closing every gap: agents that learn skills from experience, a payer command line, on-chain spending budgets, more trading venues, safer chat trading and more. `[docs]`- **A full setup guide for Grok Bot**: There is now one page that covers connecting Grok Bot to three.ws end to end: the exact connector settings, which sign-in to pick, how scheduled runs collect long renders and retry without generating twice, the rate limits, the rule that an agent can never spend, and a fix for every connection problem. (`/docs/grok-bot`) `[docs]`+- **A new default engine for photo to 3D, with regional safeguards**: Photo to 3D in the Forge now starts with TRELLIS.2, an open-source model that makes textured assets with full material detail and keeps transparency for glass and leaves. You can pick a detail level of 512, 1024 or 1536 when you generate. We also made sure that requests from the European Union, the United Kingdom and South Korea never use models whose license does not cover those regions, and that a request with no location signal takes the safe path too. The engine switches on as soon as its GPU worker is deployed, and until then the existing engines keep serving every request. (`/forge`) `[feature, improvement]`- **A paid call that fails after payment now tells you to retry, not to pay again**: If a paid x402 call fails after your payment has already settled, the response now says so: paid, retry safe, the settlement transaction, and how many retries are left. Repeat the exact same request with the same payment and the server re-runs the work without charging you again, instead of answering that the payment was already used. Paid POST routes also now tell apart two different request bodies sent under one payment identifier. The MCP docs gained a Use cases section that spells out every guided prompt as the ordered tool calls it makes, with the steps that spend money marked, and a test keeps it in step with the real tools. (`/docs/x402`) `[improvement, docs]`- **A skill file you can hand to Grok**: three.ws/grok-skill.md teaches Grok and Grok Bot what three.ws does and how to use it: the one sentence that adds the free 3D connector, copy-paste commands for calling it over plain HTTPS when no connector is set up, the links every result carries, the free limits, and the rule that nothing is ever paid for without your yes. (`/docs/grok`) `[feature]`- **Agent MCP: price an x402 payment with pay_quote before pay_and_call spends it**: The Agent MCP server now has a pay_quote tool. It asks a paid x402 endpoint what it charges without paying, and shows who gets paid, how much, in which token and on which chain, which wallet pays, the per-call limit, and anything that would stop the payment. pay_and_call needs the quote_id it returns plus an explicit confirm_payment, so an assistant always shows you the price before your agent wallet pays. One approval pays one call. Before this, turning pay_and_call on still left it refusing every call, because the quote step it requires did not exist. `[feature, fix]`diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 5b9fa5c9b..1d62d7a3e 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -157,7 +157,7 @@ bottom.| Agent-native 3D + embeddable distribution | MCP tool [api/_mcp/tools/agents.js](api/_mcp/tools/agents.js) (`attach_avatar_to_agent`); shared oEmbed provider [api/agent-oembed.js](api/agent-oembed.js) `→ /api/oembed` + builder [api/_lib/embed.js](api/_lib/embed.js) (`forgeEmbedTarget`, shared by `get_embed_code` in [api/_mcp/tools/embed.js](api/_mcp/tools/embed.js)); Forge share page oEmbed discovery [api/forge-share.js](api/forge-share.js) `→ /forge/share/:id`; distribution snippet builders [src/forge-embed-snippets.js](src/forge-embed-snippets.js) + panel [src/forge-embed-panel.js](src/forge-embed-panel.js); autonomous demo [examples/agent-native-3d/](examples/agent-native-3d) | In-repo | Closes the loop: create → own → discover/remix → **use everywhere**. `attach_avatar_to_agent` gives a registered agent identity a persistent body (chains into `register_agent` for on-chain identity + `anchor_provenance` for a signed authenticity credential). Any Forge creation now unfurls via real oEmbed (paste `/forge/share/:id` into Notion/Discord/Slack) with the same `type:rich` iframe payload `get_embed_code` returns via MCP. The Forge "Embed this model" panel hands out five real distribution flavours from one GLB — iframe, `<model-viewer>`, `<agent-3d>`, a `@three-ws/page-agent` talking guide, and a `@three-ws/walk` companion — all built from one shared, pure snippet module so every surface stays byte-identical. `examples/agent-native-3d/run.mjs` drives the full agent-native chain live against `/api/mcp-studio` (mesh_forge → rig_mesh → create_agent_persona → persona_say → get_agent_persona → every distribution snippet) with zero mocks and a documented, logged fallback if the shared free-tier generation lane is rate-limited at run time. Spec: [specs/EMBED_SPEC.md](specs/EMBED_SPEC.md#share-routes-on-chain-agents). Docs: [docs/mcp.md#attach_avatar_to_agent](docs/mcp.md#attach_avatar_to_agent). Roadmap prompt 10 (closes the roadmap campaign). || Animation pipeline | [public/animations/](public/animations) + [scripts/build-animations.mjs](scripts/build-animations.mjs) | In-repo | Mixamo source FBX + GLB retargeting pipeline · see [docs/3d-asset-pipeline.md](docs/3d-asset-pipeline.md) || Procedural animation (runtime IK layers) | [src/procedural/](src/procedural) — analytic two-bone IK [two-bone-ik.js](src/procedural/two-bone-ik.js), gaze [look-at.js](src/procedural/look-at.js), terrain foot planting [foot-plant.js](src/procedural/foot-plant.js), drift-free re-application [pose-baseline.js](src/procedural/pose-baseline.js) | Live | Post-mixer layers that do what no baked clip can: the chest/neck/head chain turns toward a world point, and each foot lands on its own patch of uneven ground. Rig-agnostic via `canonicalNodeMapFromObject`; an unsupported rig reports `enabled === false` and no-ops. Wired into the corner companion ([walk-sdk/src/companion.js](walk-sdk/src/companion.js) `_updateGaze`), the walkaround world ([src/walk.js](src/walk.js) `rebuildFootPlant`), and agent avatars ([src/agent-avatar.js](src/agent-avatar.js) `_applyLookTarget` — which is what finally makes `setLookTarget()` and the `LOOK_AT` action move the rig). Ambient idle motion (breathing/blink/saccade/weight-shift) stays in [src/idle-animation.js](src/idle-animation.js). Docs: [docs/procedural-animation.md](docs/procedural-animation.md). Tests: [tests/procedural-anim.test.js](tests/procedural-anim.test.js), [tests/agent-avatar-look-target.test.js](tests/agent-avatar-look-target.test.js) |-| Self-hosted 3D GPU fleet (the engines behind the Forge) | [workers/model-trellis/](workers/model-trellis), [workers/model-hunyuan3d/](workers/model-hunyuan3d) (2.0 + 2.1 PBR + 2.1 RTX), [workers/model-triposg/](workers/model-triposg), [workers/model-triposr/](workers/model-triposr), [workers/model-text2motion/](workers/model-text2motion), [workers/rig/](workers/rig) (auto-rigging, deployed as `model-rig`), [workers/avatar-reconstruction/](workers/avatar-reconstruction), CPU stages [workers/rembg/](workers/rembg) · [workers/remesh/](workers/remesh) · [workers/segment/](workers/segment) · [workers/stylize/](workers/stylize), talking-avatar video [workers/longcat/](workers/longcat) (LongCat-Video-Avatar-1.5, gates the `/create/video` lane via `LONGCAT_WORKER_URL`; the one fleet member that is not a Cloud Run service, because its ~45 GB resident weight set needs an 80 GB GPU, so it is built and tested but undeployed), streaming video→3D [workers/model-video2scene/](workers/model-video2scene), selfie-pipeline CPU orchestrator [workers/avatar-pipeline-controller/](workers/avatar-pipeline-controller) | Live · Cloud Run GPU (us-central1, plus us-east4 where trellis/hunyuan/triposr hold standbys and `model-text2motion` runs as its production lane) | Every generation engine the Forge dispatches to, each with its own `cloudbuild.yaml`. The L4 quota is **per region** and both us-central1 and us-east4 are granted 3, so a warm pin in one region only starves lanes in that same region (increase to 16 filed 2026-07-16, still reconciling); the Hunyuan3D-2.1 PBR realism lane also ships an RTX PRO 6000 build (`model-hunyuan3d-21-rtx`, quota granted 1000) as the warm primary. `model-text2motion` (MDM, MIT) is the text→motion lane behind `GCP_TEXT2MOTION_URL`, the `text_to_animation` MCP tool, and `POST /api/forge-motion`: prompt in, a retargetable three.js `AnimationClip` out, applied with the same engine (`src/animation-retarget.js`) as the curated animation library. It is the one GPU service whose production URL points at us-east4, and its `cloudbuild.yaml` deploys both regions from one image so the standby never lags. Ops map: [docs/ops/gcp-credits-plan.md](docs/ops/gcp-credits-plan.md) |+| Self-hosted 3D GPU fleet (the engines behind the Forge) | [workers/model-trellis2/](workers/model-trellis2) (TRELLIS.2, MIT, the default image-to-3D lane `trellis2`: PBR GLB with alpha, `resolution` 512/1024/1536; built and tested, deploy owner-gated), territory router [api/_lib/forge-territory.js](api/_lib/forge-territory.js) (EU, UK and KR never reach a Tencent-model lane; unknown country fails closed), [workers/model-trellis/](workers/model-trellis), [workers/model-hunyuan3d/](workers/model-hunyuan3d) (2.0 + 2.1 PBR + 2.1 RTX), [workers/model-triposg/](workers/model-triposg), [workers/model-triposr/](workers/model-triposr), [workers/model-text2motion/](workers/model-text2motion), [workers/rig/](workers/rig) (auto-rigging, deployed as `model-rig`), [workers/avatar-reconstruction/](workers/avatar-reconstruction), CPU stages [workers/rembg/](workers/rembg) · [workers/remesh/](workers/remesh) · [workers/segment/](workers/segment) · [workers/stylize/](workers/stylize), talking-avatar video [workers/longcat/](workers/longcat) (LongCat-Video-Avatar-1.5, gates the `/create/video` lane via `LONGCAT_WORKER_URL`; the one fleet member that is not a Cloud Run service, because its ~45 GB resident weight set needs an 80 GB GPU, so it is built and tested but undeployed), streaming video→3D [workers/model-video2scene/](workers/model-video2scene), selfie-pipeline CPU orchestrator [workers/avatar-pipeline-controller/](workers/avatar-pipeline-controller) | Live · Cloud Run GPU (us-central1, plus us-east4 where trellis/hunyuan/triposr hold standbys and `model-text2motion` runs as its production lane) | Every generation engine the Forge dispatches to, each with its own `cloudbuild.yaml`. The L4 quota is **per region** and both us-central1 and us-east4 are granted 3, so a warm pin in one region only starves lanes in that same region (increase to 16 filed 2026-07-16, still reconciling); the Hunyuan3D-2.1 PBR realism lane also ships an RTX PRO 6000 build (`model-hunyuan3d-21-rtx`, quota granted 1000) as the warm primary. `model-text2motion` (MDM, MIT) is the text→motion lane behind `GCP_TEXT2MOTION_URL`, the `text_to_animation` MCP tool, and `POST /api/forge-motion`: prompt in, a retargetable three.js `AnimationClip` out, applied with the same engine (`src/animation-retarget.js`) as the curated animation library. It is the one GPU service whose production URL points at us-east4, and its `cloudbuild.yaml` deploys both regions from one image so the standby never lags. Ops map: [docs/ops/gcp-credits-plan.md](docs/ops/gcp-credits-plan.md) || Self-hosted Granite Guardian (governance lane behind watsonx) | [workers/granite-guardian/](workers/granite-guardian/README.md) (Cloud Run `granite-guardian`, europe-west4, vLLM on one L4), client lane in [api/_lib/granite-guardian.js](api/_lib/granite-guardian.js) | Live · Cloud Run GPU (europe-west4) | IBM's open-weight `ibm-granite/granite-guardian-3.3-8b` served by the stock vLLM OpenAI image, so `/api/guardian/assess`, the identity integrity check, and the Granite Twin/Oracle/Attest/IRL screens return real Granite Guardian verdicts on a deployment with no IBM Cloud account. watsonx.ai stays the lead lane when configured; every verdict names the `model` and `provider` that produced it. Placed in europe-west4 because that region's L4 grant is otherwise unused, so its warm pin never starves the 3D lanes. Tests: [tests/api-guardian.test.js](tests/api-guardian.test.js), [tests/api/identity-integrity.test.js](tests/api/identity-integrity.test.js) || Reconstruct completion backstop (abandoned selfie jobs) | [api/cron/reconstruct-sweep.js](api/cron/reconstruct-sweep.js), every 5 min via `vercel.json` crons → Cloud Scheduler | Live 2026-07-25 | A reconstruct job used to be advanced **only by the user's browser**: `/create/selfie` polls `regenerate-status`, and each poll runs the finalize stages. Close the tab and the worker still finished the GLB and stored it durably, but nothing ever collected it — 26 jobs were stranded that way, oldest from 2026-05-31, invisible to `db-retention` (which prunes only terminal rows). This sweep is the server-side driver: it picks up reconstruct jobs quiet >3 min and runs **the same shared stages** in [reconstruct-finalize.js](api/_lib/reconstruct-finalize.js), so an abandoned job still lands in the user's library. 30-day rescue window (the worker's GCS blobs + Firestore job state are durable, so a weeks-old job is still deliverable); past that, or when a job's provider is no longer pollable from platform credentials, rows fail out with an honest reason so the open set can't grow unbounded. BYOK (meshy/tripo) jobs stay browser-driven — a cron has no user context to resolve their keys. Sibling of [auto-rig-sweep.js](api/cron/auto-rig-sweep.js), which plays the same role for the rerig lane. Docs: [docs/avatar-reconstruction.md](docs/avatar-reconstruction.md#who-finishes-the-job) || Avatar fidelity evaluation (selfie → avatar, scored) | [workers/avatar-reconstruction/eval/](workers/avatar-reconstruction/eval) | In-repo · gates every reconstruction change | **Identity Shape Error (ISE)** — does the reconstructed avatar have *this person's* face shape? Texture-blind, pose- and scale-invariant, dimensionless: MediaPipe's 468 landmarks and the avatar's corresponding head vertices are both Umeyama-aligned onto the neutral canonical face over a stable identity subset (no eyes/lips, so a smile is not scored as identity), then compared. A pipeline cannot score better by resizing or tilting the head — only by matching shape, a property pinned in [eval/test_identity_eval.py](workers/avatar-reconstruction/eval/test_identity_eval.py) alongside monotonicity. [`run_eval.py`](workers/avatar-reconstruction/eval/run_eval.py) scores a whole reference set against a live worker and diffs two revisions, surfacing per-face regressions a mean would hide; [`tune_morph.py`](workers/avatar-reconstruction/eval/tune_morph.py) sweeps the morph parameters against ISE offline; [`robustness.py`](workers/avatar-reconstruction/eval/robustness.py) measures the opposing axis (does a blurred / turned / occluded / dim / low-res photo of the same person still yield the same head?), and the shipped `max_displacement_frac` is the knee of those two curves. The 40-face reference set is **synthesised** by [`make_refs.py`](workers/avatar-reconstruction/eval/make_refs.py) over a deterministic grid of the platform's diversity matrix — no real biometrics, no licence terms, rebuildable by any agent — gitignored and mirrored to `gs://three-ws-avatar-reconstructions/eval-refs/`. Docs: [eval/README.md](workers/avatar-reconstruction/eval/README.md), program plan [docs/avatar-fidelity-program.md](docs/avatar-fidelity-program.md) |diff --git a/data/changelog.json b/data/changelog.jsonindex 436eb5b6d..a81d4f8a2 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -29335,6 +29335,13 @@"summary": "IBM Bob, IBM's AI development partner, is now a supported client. Open the IBM Bob tab on the connect page to copy a ready-made .bob/mcp.json entry, or run npx three-ws setup --clients bob to write it for you. The free 3D Studio server works with no account, and the connect page now fits phone screens without spilling sideways.","tags": ["feature", "improvement"],"link": "/connect?client=bob&server=three-ws-studio"+ },+ {+ "date": "2026-10-09",+ "title": "A new default engine for photo to 3D, with regional safeguards",+ "summary": "Photo to 3D in the Forge now starts with TRELLIS.2, an open-source model that makes textured assets with full material detail and keeps transparency for glass and leaves. You can pick a detail level of 512, 1024 or 1536 when you generate. We also made sure that requests from the European Union, the United Kingdom and South Korea never use models whose license does not cover those regions, and that a request with no location signal takes the safe path too. The engine switches on as soon as its GPU worker is deployed, and until then the existing engines keep serving every request.",+ "tags": ["feature", "improvement"],+ "link": "/forge"}]}diff --git a/docs/forge-pipeline.md b/docs/forge-pipeline.mdindex 98a984871..4d1d5a0b7 100644--- a/docs/forge-pipeline.md+++ b/docs/forge-pipeline.md@@ -95,6 +95,7 @@ Self-hosted TRELLIS additionally maps tiers to sampler and texture budgets via `| --- | --- | --- | --- | --- | --- || `nvidia` | Microsoft TRELLIS | NVIDIA NIM (hosted) | image (text only, rejects user photos) | free | `NVIDIA_API_KEY` || `huggingface` | Hunyuan3D 2.1 → Hunyuan3D 2 → TRELLIS → TripoSR (internal chain) | HF Spaces | image | free, blocking submit | `HF_TOKEN` |+| `trellis2` | Microsoft TRELLIS.2 (MIT, PBR with alpha) | Our Cloud Run L4 worker (`workers/model-trellis2/`) | image (native single-hop image to 3D) | free (our GPU) | `MODEL_TRELLIS2_URL` + `GCP_RECONSTRUCTION_KEY` || `trellis_selfhost` | Microsoft TRELLIS | Our Cloud Run L4 worker (`workers/model-trellis/`) | image (native single-hop image to 3D) | free (our GPU) | `MODEL_TRELLIS_URL` + `GCP_RECONSTRUCTION_KEY` || `hunyuan3d` | Tencent Hunyuan3D-2.1 | Our Cloud Run L4 worker (`workers/model-hunyuan3d/`) | image | free (our GPU) | `GCP_HUNYUAN3D_URL` + key || `triposg` | VAST AI TripoSG-scribble | Our Cloud Run L4 worker (`workers/model-triposg/`) | sketch only | free (our GPU) | `GCP_TRIPOSG_URL` + key |@@ -113,8 +114,8 @@ Routing answers one question: given `(path, tier, userImages, prompt)`, which co**Static preference order.** `freeLaneCandidates()` builds the ordered list both resolvers walk:-1. The tier's named free default (`FREE_DEFAULT_FOR_TIERS`): draft/standard image requests name `trellis_selfhost`; high names `hunyuan3d`. Both are our own GPU workers; NVIDIA NIM is no longer a named default (its text-only, no-reference-image conditioning is the realism hole this table closes) but stays explicitly selectable and remains the final fallthrough in the per-path chain.-2. The per-path free fallback chain (`FREE_FALLBACK_FOR_PATH`). For `image` that is `trellis_selfhost`, `hunyuan3d`, `huggingface`, `nvidia`: our own GPU workers first (zero vendor cost), then external free lanes, with the text-only NIM lane trailing as a safety net.+1. The tier's named free default (`FREE_DEFAULT_FOR_TIERS`): every image tier (draft, standard, high) names `trellis2`, the only default lane that serves every region. Hunyuan3D is no longer a named default; it is an explicit lane and a fallback outside the restricted territories (see Territory enforcement below). The unconfigured case matters: until `MODEL_TRELLIS2_URL` is set the lane is skipped and the chain behind it serves the request. The workers are our own GPUs; NVIDIA NIM is no longer a named default (its text-only, no-reference-image conditioning is the realism hole this table closes) but stays explicitly selectable and remains the final fallthrough in the per-path chain.+2. The per-path free fallback chain (`FREE_FALLBACK_FOR_PATH`). For `image` that is `trellis2`, `trellis_selfhost`, `hunyuan3d`, `huggingface`, `nvidia`: our own GPU workers first (zero vendor cost), then external free lanes, with the text-only NIM lane trailing as a safety net.3. The paid platform default (`DEFAULT_BACKEND_FOR_PATH`: image → `trellis` on Replicate, geometry → `meshy`, sketch → `triposg`) only when nothing free is configured and healthy.**Subject-aware reorder (high tier).** `classifyForgeSubject()` regex-classifies the prompt as hard-surface or organic. Hard-surface prompts (vehicles, machines, architecture) hoist `trellis_selfhost` above `hunyuan3d`; organic subjects (people, creatures) keep Hunyuan3D first. This exists because the two engines genuinely differ on those subject classes at high fidelity.@@ -151,7 +152,11 @@ Async jobs get an opaque HMAC-signed token (`f1.<payload>.<sig>`, `api/_lib/forgEvery non-terminal poll also carries honest timing: `elapsed_seconds` (the age of the *job*, from `created_at`, not of the tab watching it), `eta_seconds` (the lane's typical total) and `eta_remaining_seconds`. The remaining figure is floored at 5, because the estimate is a typical duration rather than a deadline and a countdown that goes negative reads as "stuck" on a job that is merely slower than average. A `queued` poll on a scale-to-zero self-host lane additionally carries `cold_start` and `cold_start_seconds` (that lane's spin-up budget). `laneColdStart()` is module-scope for exactly this reason: it used to be a closure inside the submit handler, so only the submit response could say a worker was booting, and a client that never saw it (a coalesced job, a page resumed after a reload, a failover successor) was told "queued" with no explanation for a wait that is a container boot rather than a stall. `forgeStageNarration()` and `coldStartState()` in [src/shared/forge-frames.js](../src/shared/forge-frames.js) turn those fields into the same copy on every surface, off the payload and never off a local clock, and the flag clears on the first real `running` poll rather than on a timer. The in-flight job id is also written to `localStorage`, so an interrupted browser session resumes polling for up to 30 minutes; background completion persists the result to the user's gallery either way (see [Background generation](./forge-background-generation.md)).-**Poll-time failover** (`api/_lib/forge-failover.js`) closes the nastier gap: a self-host worker can accept a task and fail it minutes later, in a poll handled by a different instance that no longer holds the request. On a failed poll the module recovers the original inputs (prompt plus reference image) from the creation row, resubmits to the next configured lane, and binds old handle to new handle in Redis (2 hour TTL). The client keeps polling the same job id and simply sees `status: running` with a new `backend`. Hops are capped by `MAX_FAILOVER_HOPS = 3` (one primary plus up to three backups). The redispatch order is `trellis_selfhost`, `hunyuan3d`, `trellis`, then `triposg` as the final rung. TripoSG runs its photo pipeline (gcp provider mode `triposg`) and returns untextured geometry, so it only serves a job once every textured lane has failed or is marked down; the client's lane note says the result will have no textures. It was added after the 2026-09-18 to 09-28 outage, when Hunyuan3D and TRELLIS self-host failed together, Replicate was unconfigured, and roughly 400 photo jobs a day ended in a hard failure while the TripoSG worker was healthy. TripoSG stays out of the `retry_backends` suggestions because its public lane is sketch-only. HuggingFace is excluded because its provider blocks through the whole generation (cannot be ridden from a poll), and NVIDIA is excluded because poll-time redispatch always reconstructs from a stored reference image, which NIM rejects. Both failover paths (this attended one and the unattended finalizer sweep) link the failed attempt to its successor row (`forge_creations.superseded_by`, migration `20260814200000_forge_failover_supersede.sql`), so the outcome ledger, the forge health sensor and `npm run forge:errors` count a recovered attempt as a recovery, not a loss.+**Territory enforcement** (`api/_lib/forge-territory.js`). The Hunyuan3D license excludes the European Union, the United Kingdom and South Korea for the model and its output. The Forge resolves the requester's country on the server from the edge geo header (`clientCountry`), never from the request body, and never routes a restricted request to a Tencent-model lane. Those lanes are `hunyuan3d` and `huggingface` (the Spaces chain runs Hunyuan3D-2 and 2.1). An unknown or malformed country is treated as restricted, so a request with no geo signal fails closed to the MIT and non-Tencent lanes. The filter sits in every place a lane is chosen: auto routing and its health-aware variant, the HuggingFace failure hop, poll-time redispatch, the `retry_backends` suggestions, and the prompt-to-avatar plan. An explicit `backend=hunyuan3d` or `backend=huggingface` from a restricted country answers `403 region_restricted` and lists the open lanes in `retry_backends`. The public catalog is CDN-cached and country-agnostic, so it advertises the fail-closed defaults.++**Resolution option.** `resolution` (512, 1024 or 1536) is a request option honoured by the `trellis2` lane and part of the dedup and cache key, so two resolutions of one prompt never share a result. It is rejected with a clear error when invalid, and a worker that cannot hold the requested size steps down and reports `resolution_served`.++**Poll-time failover** (`api/_lib/forge-failover.js`) closes the nastier gap: a self-host worker can accept a task and fail it minutes later, in a poll handled by a different instance that no longer holds the request. On a failed poll the module recovers the original inputs (prompt plus reference image) from the creation row, resubmits to the next configured lane, and binds old handle to new handle in Redis (2 hour TTL). The client keeps polling the same job id and simply sees `status: running` with a new `backend`. Hops are capped by `MAX_FAILOVER_HOPS = 3` (one primary plus up to three backups). The redispatch order is `trellis2`, `trellis_selfhost`, `hunyuan3d`, `trellis`, then `triposg` as the final rung (Tencent lanes are skipped for a restricted or unknown territory). TripoSG runs its photo pipeline (gcp provider mode `triposg`) and returns untextured geometry, so it only serves a job once every textured lane has failed or is marked down; the client's lane note says the result will have no textures. It was added after the 2026-09-18 to 09-28 outage, when Hunyuan3D and TRELLIS self-host failed together, Replicate was unconfigured, and roughly 400 photo jobs a day ended in a hard failure while the TripoSG worker was healthy. TripoSG stays out of the `retry_backends` suggestions because its public lane is sketch-only. HuggingFace is excluded because its provider blocks through the whole generation (cannot be ridden from a poll), and NVIDIA is excluded because poll-time redispatch always reconstructs from a stored reference image, which NIM rejects. Both failover paths (this attended one and the unattended finalizer sweep) link the failed attempt to its successor row (`forge_creations.superseded_by`, migration `20260814200000_forge_failover_supersede.sql`), so the outcome ledger, the forge health sensor and `npm run forge:errors` count a recovered attempt as a recovery, not a loss.**Designed terminal failure.** When no successor is possible, the failed response carries `retryable: true` plus `retry_backends: [...]`, the ordered configured lanes a client can one-click resubmit to. A failure is never a bare string. The whole module is fail-open: no Redis disables automatic redispatch but keeps suggestions; no DB disables recovery but never turns a clean failure into a hang.@@ -223,6 +228,7 @@ Workers are Python FastAPI services on Cloud Run (scale-to-zero L4 GPUs unless n| Worker | Role || --- | --- |+| `workers/model-trellis2/` | Self-hosted TRELLIS.2, the default `trellis2` lane. `resolution` 512, 1024 or 1536, PBR GLB with alpha, meshopt packed. || `workers/model-trellis/` | Self-hosted TRELLIS, the `trellis_selfhost` lane. Quality-tiered up to 4096px textures. || `workers/model-hunyuan3d/` | Hunyuan3D-2.1 single image to textured mesh, the `hunyuan3d` lane. || `workers/model-triposg/` | TripoSG 1.5B. `mode: image` for the avatar pool, `mode: scribble` for the sketch path. |@@ -260,7 +266,7 @@ The env vars that shape a deployment (production values live on the Cloud Run se| --- | --- || `NVIDIA_API_KEY` | Enables the free NIM TRELLIS text lane. || `HF_TOKEN` | Enables the HF Spaces lane. |-| `MODEL_TRELLIS_URL`, `GCP_HUNYUAN3D_URL`, `GCP_TRIPOSG_URL`, `GCP_UNIRIG_URL`, `GCP_RECONSTRUCTION_URL` | Self-host worker URLs (TRELLIS, Hunyuan3D, sketch, rig, avatar controller). |+| `MODEL_TRELLIS2_URL`, `MODEL_TRELLIS_URL`, `GCP_HUNYUAN3D_URL`, `GCP_TRIPOSG_URL`, `GCP_UNIRIG_URL`, `GCP_RECONSTRUCTION_URL` | Self-host worker URLs (TRELLIS, Hunyuan3D, sketch, rig, avatar controller). || `GCP_RECONSTRUCTION_KEY` | Shared bearer for all self-host workers. || `REPLICATE_API_TOKEN` | Enables the paid Replicate last resort. || `FORGE_PREFER_FREE` | Default on; prefer free reconstruction before paid Replicate. |diff --git a/docs/ops/gcp-model-workers.md b/docs/ops/gcp-model-workers.mdindex 199d80feb..0810bbd82 100644--- a/docs/ops/gcp-model-workers.md+++ b/docs/ops/gcp-model-workers.md@@ -21,6 +21,7 @@ result_* }` — and authenticate with one shared bearer secret.| Lane (`backend` id) | Worker dir | Cloud Run service | Path served | What it does ||---------------------|-----------------------|--------------------|-------------|--------------|+| `trellis2` | `workers/model-trellis2` | `model-trellis2` | `image` | Default image→3D lane. TRELLIS.2 (MIT): PBR GLB with alpha, `resolution` 512/1024/1536, meshopt packed. Weights staged by `workers/model-trellis2/stage_weights.sh`. || `trellis_selfhost` | `workers/model-trellis` | `model-trellis` | `image` | Native single-hop image→3D (Microsoft TRELLIS). Accepts user photos and the FLUX-synthesized view for text prompts. Textured GLB. || `hunyuan3d` | `workers/model-hunyuan3d`| `model-hunyuan3d`| `image` | High-poly image-conditioned reconstruction (Tencent Hunyuan3D). Poly-budget aware. || `triposg` | `workers/model-triposg` | `model-triposg` | `sketch` | Sketch→3D (TripoSG-scribble): a drawing + a prompt naming it → untextured geometry. |@@ -85,6 +86,7 @@ faked.| Env var | Used by | Notes ||-------------------------|------------------------|-------|+| `MODEL_TRELLIS2_URL` | `trellis2` | Cloud Run URL of `model-trellis2`. Unset means the lane is skipped. || `MODEL_TRELLIS_URL` | `trellis_selfhost` | Cloud Run URL of `model-trellis`. || `GCP_HUNYUAN3D_URL` | `hunyuan3d` | Cloud Run URL of `model-hunyuan3d`. **Not** `GCP_RECONSTRUCTION_URL` — that is the avatar face pipeline, which rejects non-face images. || `GCP_TRIPOSG_URL` | `triposg` (sketch) | Cloud Run URL of `model-triposg`. |diff --git a/public/changelog-recent.json b/public/changelog-recent.jsonindex c7581b28a..dba93ea8b 100644--- a/public/changelog-recent.json+++ b/public/changelog-recent.json@@ -1,11 +1,11 @@{- "generated_at": "2026-10-09T16:56:49.168Z",+ "generated_at": "2026-10-09T17:21:05.080Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws","url": "https://three.ws"},- "total": 3868,+ "total": 3869,"complete": false,"full_feed": "/changelog.json","entries": [@@ -89,6 +89,17 @@"docs"]},+ {+ "date": "2026-10-09",+ "type": "update",+ "title": "A new default engine for photo to 3D, with regional safeguards",+ "summary": "Photo to 3D in the Forge now starts with TRELLIS.2, an open-source model that makes textured assets with full material detail and keeps transparency for glass and leaves. You can pick a detail level of 512, 1024 or 1536 when you generate. We also made sure that requests from the European Union, the United Kingdom and South Korea never use models whose license does not cover those regions, and that a request with no location signal takes the safe path too. The engine switches on as soon as its GPU worker is deployed, and until then the existing engines keep serving every request.",+ "link": "/forge",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-10-09","type": "update",@@ -1538,16 +1549,6 @@"feature","sdk"]- },- {- "date": "2026-09-20",- "type": "update",- "title": "Queued posts can quote an earlier post",- "summary": "A post in the @trythreews content queue can now name an earlier post to quote, so a follow-up can add the detail the original left out instead of repeating it. The first use quotes the $THREE token MCP announcement with the numbers behind the MCP Tool Catalog: 321 tools across 42 servers, 293 of them free, and 215 whose read-only label is checked against the source on every build.",- "link": "/mcp-tools",- "tags": [- "improvement"- ]}]}diff --git a/public/changelog.json b/public/changelog.jsonindex 861c968f4..097ae95fa 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-10-09T16:56:49.147Z",+ "generated_at": "2026-10-09T17:21:05.047Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -86,6 +86,17 @@"docs"]},+ {+ "date": "2026-10-09",+ "type": "update",+ "title": "A new default engine for photo to 3D, with regional safeguards",+ "summary": "Photo to 3D in the Forge now starts with TRELLIS.2, an open-source model that makes textured assets with full material detail and keeps transparency for glass and leaves. You can pick a detail level of 512, 1024 or 1536 when you generate. We also made sure that requests from the European Union, the United Kingdom and South Korea never use models whose license does not cover those regions, and that a request with no location signal takes the safe path too. The engine switches on as soon as its GPU worker is deployed, and until then the existing engines keep serving every request.",+ "link": "/forge",+ "tags": [+ "feature",+ "improvement"+ ]+ },{"date": "2026-10-09","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex 9264f7808..2da247ee6 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -70,6 +70,14 @@<category>docs</category><description>There is now one page that covers connecting Grok Bot to three.ws end to end: the exact connector settings, which sign-in to pick, how scheduled runs collect long renders and retry without generating twice, the rate limits, the rule that an agent can never spend, and a fix for every connection problem.</description></item>+ <item>+ <title>A new default engine for photo to 3D, with regional safeguards</title>+ <link>https://three.ws/forge</link>+ <guid isPermaLink="false">2026-10-09:A new default engine for photo to 3D, with regional safeguards</guid>+ <pubDate>Fri, 09 Oct 2026 12:00:00 GMT</pubDate>+ <category>feature</category>+ <description>Photo to 3D in the Forge now starts with TRELLIS.2, an open-source model that makes textured assets with full material detail and keeps transparency for glass and leaves. You can pick a detail level of 512, 1024 or 1536 when you generate. We also made sure that requests from the European Union, the United Kingdom and South Korea never use models whose license does not cover those regions, and that a request with no location signal takes the safe path too. The engine switches on as soon as its GPU worker is deployed, and until then the existing engines keep serving every request.</description>+ </item><item><title>A paid call that fails after payment now tells you to retry, not to pay again</title><link>https://three.ws/docs/x402</link>