Forge — 3D Models

Forge builds 3D models — one of the kinds of Saved Content, beside pictures, lines, sound effects and music. You describe an asset — "twin-engine attack submarine, angular hull, forward laser cannons, missile pods under the wings" — and an AI agent builds it in Blender: clean hard-surface geometry, named bones and sockets your gameplay code can attach to, real UVs with a baked PBR texture set, optional animation clips, and the parametric build script that made it.

That last part is the difference from diffusion mesh generators. Because the script is kept with the asset, refining a model ("make the wings 20% longer") edits the build rather than starting over, and every result lands as a new version of the same item.

Every version of a model is a set of files under one folder in storage, each downloadable from the detail page or the API:

The style decides how the asset looks: what geometry gets built, which materials are used, and how much texture detail is baked. It defaults to stylized, and a project or organization can set a house style that every job in it inherits (a job's own style still wins).

Wear is separate and runs 0–1: how much grime, edge chipping and scratching is baked into the maps. It defaults to 0 — factory-new — so ask for it explicitly (a battered warship around 0.6, a scuffed crate 0.3) and leave it at zero for anything new or pristine.

The preset is a rig contract: which bones must exist, how they are parented, which of them double as sockets, and which animation clips can be requested. The agent must satisfy it — a model whose rig is missing a contract bone never passes validation.

A contract exists to match something outside Tonetta: the gameplay code that calls DoesSocketExist, the animations that have to retarget onto it, the skeleton a mesh will be reimported over. That is almost always one specific game, so contracts are yours to define. They live in three layers — built-in, organization, project — and resolve by name, most specific first. Resolving means replacing: a project contract named vehicle is used instead of the built-in, never merged with it. Half of one skeleton spliced onto half of another is not a skeleton.

Signed in, that is your table — the built-ins with your organization's own definitions over them, which is what a job with no project resolves against. A project's contracts replace these again, so the table a given job sees is the one on Forge ▸ Rig presets, where you create, edit and delete your own. Over the API the same list is GET /api/v1/models/presets?projectId=, and every catalog response carries it with a source on each entry.

The quick tier is for blocking out and iterating; the detailed tier gives the agent a larger budget, more geometry, bigger textures, and clips. Both tiers can run on any model in the catalog.

The agent that writes the build runs on an OpenRouter model you pick per job. Models that can see look at their own render previews as they work; text-only models iterate on scene statistics and the validation gates instead, which is cheaper but blinder.

GET /api/v1/models/catalog returns the live list with indicative prices, plus the rig presets and styles the build agent chooses between — the dashboard form and the Unreal plugin read it rather than hard-coding the model list.

Forge is the dashboard section for 3D models: /dashboard/forge lists every model as a card with its thumbnail, preset, tier and model badges and version count, shows the jobs that are running, and has the New model form. A model's page is where you view it in 3D, read its metadata, download files, switch the active version, refine it into a new version, edit its name, tags and character, or delete it. Models also stay listed under Saved Content's Models tab, which links into Forge.

A job is fire-and-forget: you write the brief, submit, and come back to a finished model. It is the right choice when you know what you want and the prompt says it.

A conversation is the other way. Your first message is the brief, and from then on each message is one step: the agent builds, renders or researches, shows you the result, and asks where to go next. You steer — "the nose is too blunt", "give it a second turret", "show me it from below" — instead of rewriting a prompt and starting over. Start one from Forge → New conversation, or open one on a model you already have to work from its active version.

• •Nothing is saved until you export. Turns build and render freely; asking the agent to export (or pressing Export) writes a version onto the model, and earlier versions stay.
• •Paid steps are proposed, not taken. When the agent wants a vendor call — a seed mesh, retopology, a paint pass, reference pictures — it tells you what it costs and waits for a yes, unless your message already asked for it.
• •One turn at a time. A message sent while the previous turn is still running is refused rather than queued; wait for the turn to finish.
• •Billed to what it actually cost, like every other Forge operation — a turn that only looks at the model costs little.

By API: POST /api/v1/models/sessions to start, /messages to say something, GET the session to read the reply, and /export to save a version. The MCP tools are start_model_session, send_model_message, get_model_session and export_model_session; scope models:write.

1. 1Open Forge in the dashboard and choose New model.
2. 2Write the prompt: the silhouette, the parts, the materials and the finish. The prompt is the whole specification — the build agent reads it and decides the asset's name, its rig, how stylized or realistic the surface is, how weathered, which clips to author and which maps to bake. Optionally attach reference images, pick a project, and choose which language model builds it.
3. 3Submit. The reservation is taken and the job is queued; you land on the job page, which shows the stage, the round, and every preview render as it arrives — the model taking shape.
4. 4When the job succeeds the model appears in Forge (and in Saved Content's Models tab) with its thumbnail; its page has the interactive viewer, the file list, the rig/metadata table, versions, and the Refine and Edit details controls.

Three editable layers sit in front of every asset prompt, so you describe your world once instead of repeating it in each prompt — and the agent stops defaulting to its own generic look. Later layers override earlier ones; the asset prompt wins over all of them.

Each layer is one block of free text — say it the way you would say it to an artist. Shape language, era and mood; the materials and finishes; the colours, by name and hex; real-world sizes; and what to avoid. There are no fields to fill in and nothing to encode: "Retro-futurist 1960s submarine tech: rounded hulls with riveted band seams, brass trim, bulbous portholes. Brushed steel #8a9199, copper trim #b87333, cyan weapon glow #3fd6ff. Player sub 6 m; enemies 4–12 m. No organic shapes, no readable text." Up to 8,000 characters per layer.

When a job is submitted, every layer is snapshotted onto the job: the system guidance goes into the agent's system prompt, and the organization and project text are written in as two consecutive "art direction" blocks right after your asset prompt, verbatim — organization first, project second, your prompt winning on any conflict. Refine jobs take the layers as they are at that moment, and a one-off exception needs nothing more than saying so in the prompt (or switching a layer off for that job). The job page and the model's detail page show which art direction a version was built against.

Art direction says what your world looks like, not how one asset should be built: an asset's own prompt decides its style, its weathering and its detail, and wins over every layer. A project whose text describes a flat mock-up look still builds whatever the prompt in front of it asks for.

The list of language models the generate form, the API catalog, MCP and the Unreal plugin offer is maintained by the Tonetta operator under Admin ▸ 3D Modeling ▸ Models available for 3D modeling: models can be enabled or disabled, one is marked as the default used when a request omits model, and new ones can be added by searching OpenRouter (the model must support tool calling; whether it can see render previews and its context size are read from OpenRouter). Read GET /api/v1/models/catalog or call get_model_catalog for the current keys rather than assuming them; a key that is not offered is refused with validation_error, and jobs already queued keep the model they were submitted with.

The Refine box on a model's detail page takes plain instructions and starts a job from the active version's build.py and .blend. The result is appended as the next version and becomes active; older versions stay downloadable and can be pinned back, exactly like audio versions. One job per model at a time — Refine is unavailable while a job is running.

Model generation is asynchronous — the only Tonetta operation that is. Submitting returns a job id immediately; poll it (or long-poll with ?wait=) until the status is terminal.

• •Reserved, then settled. Submitting holds a reservation — at least the tier's base (25 quick / 90 detailed), more for premium models — and on completion the job settles to the actual LLM + compute cost times the usual surcharge; the difference is returned. Every model in the catalog and on the generate form carries ≈ credits per tier: what a job on it typically settles to, in Tonetta credits (never the provider's own prices). See Credits & Pricing.
• •Limits. Two active jobs per organization by default (409 too_many_active_jobs, no credits held) — your organization page shows the allowance in force and we can raise it; one active job per model; a job that stops reporting is failed and refunded automatically.
• •Cancel from the job page, the dashboard's active-jobs strip, or the API. A queued job is refunded in full; a running job stops after its current step.

Models are scoped with models:read / models:write. Content routes treat a model like any other item; the generation routes are below. Full details in the REST API reference.

# 1. submit
curl -s https://<host>/api/v1/models/generate \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "prompt": "twin-engine attack submarine, angular riveted hull, forward laser cannons, missile pods under the stub wings, salt-worn navy paint over bare steel" }'
# -> { "success": true, "result": { "jobId": "…", "contentId": "…", "status": "queued", "creditsReserved": 25 } }

# 2. long-poll until done
curl -s "https://<host>/api/v1/models/jobs/<jobId>?wait=240" -H "Authorization: Bearer $API_KEY"

# 3. the finished item lists every file with a URL
curl -s https://<host>/api/v1/content/<contentId> -H "Authorization: Bearer $API_KEY"