The Meshy API balance check read 3,105 credits. The tools/meshy.py script made the call: stdlib-only, seven tests, written two days after the studio environment was running. The real Cj avatar came back.
Nothing downstream changed.
Not the Godot skeleton driver. Not the shape-key bindings. Not the audio reactivity pipeline driving the stage off beat-clock amplitude bands. Not the procedural set. The studio had been running on a capsule humanoid for three days, and the real mesh dropped in as if the pipeline had been designed around it. It had been. That was the point of writing blender/cj/proxy_rig.py on day two: not to have something to look at, but to commit exactly what the real mesh would need to satisfy.
Improving on the coverage in the earlier piece on why the real avatar was left until last: that article named the order. This one explains the mechanism.
The proxy committed a contract
blender/cj/proxy_rig.py generated a Mixamo-named humanoid stand-in: 22 core mixamorig: bones at human proportions, skinned capsule parts, five VRM-named face shape keys. None of that was for visual fidelity. The capsule proportions were close enough to stage the scene, but the naming was the actual deliverable.
Every bone name, every shape key name, every skinning weight commitment was a binding decision about what downstream code would be allowed to assume. Godot’s skeleton driver references bones by the mixamorig: namespace. The audio reactivity system maps beat-clock amplitude bands to shape key names from the VRM spec. Neither cares what the mesh looks like. Both require the names to exist, to be consistent, and to match what they were written against.
The proxy committed those names on day two. The real mesh had to honour them on day three.
What the downstream systems were binding to
By day two, three pipeline stages were complete. P1 had built the environment: a procedural set from blender/tools/kit.py (11 licence-free assets generated deterministically from bmesh primitives), instanced by build_set.py from sets/studio/spec.json. P2 had wired the audio. tools/manifest_from_remotion.py converted the Remotion manifest into data/stream-manifest.json; NAPA masters were joined by track number; beat-clock amplitude bands drove stage reactivity. P0 had done the earlier work: Godot 4 skeleton, toolchain, set-pipeline scaffold.
All of this was written to a contract the proxy defined. The environment had no opinion about the mesh. The audio pipeline animated shape keys by name, indifferent to the geometry those keys deformed. The Godot scene graph expected a humanoid skeleton in the mixamorig: namespace, which the proxy had been for three days, and which the real mesh had to be when it arrived.
When Meshy delivered the real avatar, the pipeline saw what it had always been expecting. There was nothing to reconcile.
What Meshy had to deliver
The Meshy API call was, implicitly, a conformance check. Two things had to hold. The output had to rig to the mixamorig: skeleton cleanly, and the shape-key targets had to map to the VRM naming the downstream code already used. Meshy’s API handled the rig. That part bears repeating, because rigging is where avatar pipelines typically fragment. The original plan included a Mixamo step (image-to-3D → Blender → Mixamo auto-rigger → FBX export). The proxy had already established the skeleton contract before that step was reached, and Meshy’s output satisfied it directly. Mixamo was optional from the moment proxy_rig.py ran.
tools/meshy.py kept the acquisition step as thin as possible: stdlib-only, seven tests covering the balance call, the generation request, and the polling loop. The complexity budget stayed in the contract definition, not the fetching plumbing.
Why the contract-first order matters
In software, contract-first design is routine. Define the API interface before either side implements it; both sides write against the contract; integration is a conformance check. 3D avatar pipelines rarely work this way. The typical order: model the character, rig it, then write engine code to match whatever the rig produced. The contract is implicit, reverse-engineered from the rig, and any change to the rig ripples downstream.
proxy_rig.py inverted that. The contract was explicit (22 named bones, five named shape keys, a specific skinning topology) before any Meshy credits were spent, before the real mesh existed. Downstream code was written against the contract. The real mesh was measured against the contract before being accepted into the pipeline.
The tradeoff: a day spent writing proxy_rig.py before touching Meshy. That day paid back immediately when the real avatar landed. It also pays back every subsequent iteration. Swap in a different mesh generation, adjust proportions, change topology: the contract stays fixed, the downstream code doesn’t follow every mesh change.
What the contract didn't cover
The proxy_rig.py contract covered skeleton naming and shape-key naming only. Mesh topology, UV layout, material slots: all free variables the downstream code had no opinion about. Meshy’s output arrived with its own UV islands and material assignments; the toon shader was applied post-import without needing to match any proxy convention.
Proportional accuracy was “close enough to stage.” The capsule parts were not a faithful stand-in for the real avatar’s silhouette. Camera framing and scene composition decisions were deferred until the real mesh existed. Out of scope for the proxy: anything visual. In scope: anything named.
The receipt
Day one: P0 bootstrap, P1 environment, P2 audio pipeline, placeholder skeleton. Everything running, humanoid naming undefined.
Day two: proxy_rig.py committed. 22 bones, 5 shape keys, contract in place. P4 complete: everything below the mesh was built and proven.
Day three: tools/meshy.py fired. Real avatar, 3,105 credits consumed. Nothing downstream changed.
The contract was written before the asset that had to satisfy it. That’s the order that made day three a swap rather than an integration.
