Asset Worker is Atlas' containerized glTF post-processing service for generated 3D assets. It takes a raw GLB as an upload or a MinIO object reference. It applies the shared Atlas normalization contract, runs glTF-Transform optimization, and writes the GLB to a content-addressed location.

This service exists so image-to-3D providers, Blender and external pipelines, and future creative routes do not duplicate mesh cleanup logic. It is disabled by default until a workflow explicitly needs a common post-processing API.

Every route except GET /health and GET /metrics requires Authorization: Bearer ${ASSET_WORKER_API_TOKEN}. Atlas generates the token on first startup; requests fail closed with 503 if authentication is not configured.

Enable from the CLI with:

./start.sh --asset-worker-source container

The default ASSET_WORKER_SOURCE=disabled keeps the worker out of normal starts until a creative or 3D workflow needs it.

Inputs (uploaded or MinIO-referenced) must be self-contained binary glTF 2.0 files. These inputs are rejected with 400:

• a .gltf JSON file, whatever its name;
• a GLB whose JSON chunk does not parse;
• a buffers[].uri or images[].uri that is not a data: URI.

These checks run before any converter. A converter would resolve such a URI against the container filesystem or network and embed what it reads. Asset Baker applies the same rules.

Malformed geometry arrays or object entries reach glTF-Transform's checks and return 422 when those checks reject them.

POST /gltf/postprocess accepts multipart/form-data:

curl -H "Authorization: Bearer ${ASSET_WORKER_API_TOKEN}" \
  -F [email protected] \
  "http://localhost:${ASSET_WORKER_PORT}/gltf/postprocess"

POST /gltf/postprocess/ref accepts JSON:

{
  "input": {"bucket": "raw-assets", "key": "incoming/mesh.glb"},
  "params": {"target_height_m": 1.8, "draco": true}
}

The request bucket must be listed in ASSET_WORKER_ALLOWED_INPUT_BUCKETS; other buckets return 403 before MinIO is contacted. Populate the default raw-assets bucket with the generated MINIO_ASSET_INGEST_ACCESS_KEY and MINIO_ASSET_INGEST_SECRET_KEY; that identity can write inputs without receiving MinIO root or processor-output access.

Both endpoints return a normalized artifact envelope:

{
  "status": "succeeded",
  "sha256": "<optimized-glb-sha256>",
  "artifact": {
    "storage": "minio",
    "bucket": "asset-worker",
    "key": "gltf/<sha256>.glb",
    "uri": "s3://asset-worker/gltf/<sha256>.glb",
    "content_type": "model/gltf-binary"
  },
  "download_url": null,
  "normalization": {
    "method": "keep",
    "up_axis": "keep",
    "base_y": 0,
    "normalize_axis": "height",
    "target_height_m": 1.8
  },
  "optimization": {
    "simplify_ratio": 0.5,
    "draco": true,
    "meshopt": true,
    "ktx2": false,
    "collider_decimation": 0.25
  }
}

When ASSET_WORKER_MINIO_ENABLED=false, the worker stores the optimized GLB under ASSET_WORKER_ARTIFACT_DIR/gltf/<sha256>.glb and returns download_url=/gltf/artifacts/<sha256>.glb.

This service performs mechanical glTF conditioning: scale-to-target, center-XZ, ground-at-y=0, and mesh/texture optimization. Orientation policy is the consumer's. glTF is +Y-up by spec, so the default (up_axis=keep) trusts the incoming orientation. Reorientation (auto or an explicit axis) is opt-in per request. Product-specific asset rules (which assets to reorient, semantic up-ness, placement conventions) belong in the consuming pipeline, not here.

The worker performs three operations in order. Uploads are copied in chunks to bounded temporary files. The blocking pipeline runs in a worker thread, so health and other API requests stay responsive. A process-wide semaphore admits mutation requests before request-body parsing or object-store fetch; requests beyond ASSET_WORKER_CONCURRENCY receive 429 without consuming transformation, upload-spooling, or MinIO-fetch capacity.

1. Normalize geometry from the float32 GLB POSITION accessors. Apply base-at-y=0, center X/Z on the origin, and scale to the target height or width. Reorientation is opt-in through up_axis (§4.1).
2. Run gltf-transform inspect, gltf-transform validate, and gltf-transform optimize with the requested simplification and compression settings.
3. Hash the optimized GLB with SHA-256 and write it to MinIO or the local artifact cache under gltf/<sha256>.glb.

The service is intentionally separate from the media gateway. Image-to-3D provider adapters should send raw provider outputs to this worker rather than embed mesh normalization.

Support tier: experimental — Capability contract declared; no cited cold-start, workflow, or upgrade qualification run yet (evidence at v0.1.0).

• 400 Input must be a GLB file: use a .glb filename and binary GLB payload.
• gltf-transform validate failure: inspect the raw provider output; invalid GLB input is rejected before storage.
• 401 Invalid Asset Worker bearer token: pass Authorization: Bearer ${ASSET_WORKER_API_TOKEN}.
• 403 Input bucket is not allowed: add the intended bucket to ASSET_WORKER_ALLOWED_INPUT_BUCKETS; do not broaden the list to unrelated or private buckets.
• Dependency check fails with "Asset Worker requires MinIO": the container waits on minio and minio-init, and the gen-ai-creative track leaves MinIO off. Add --minio-source container (for example ./start.sh --track gen-ai-creative --asset-worker-source container --minio-source container), declare MINIO_SOURCE: container in a consumer manifest, or disable Asset Worker.
• MinIO upload failure: confirm MINIO_SOURCE=container, ASSET_WORKER_MINIO_BUCKET, and the generated MINIO_ASSET_WORKER_* credentials.
• Kong alias missing: confirm ASSET_WORKER_SOURCE=container, run ./start.sh --setup-hosts, and regenerate routes through the normal startup flow.

Open the full-size diagram for a full-screen view.

• Backend media operations should call Asset Worker after hosted image-to-3D providers return raw GLB outputs.
• Blender and external pipelines should use the API for the same upright/normalize/optimize contract instead of carrying local duplicate scripts.

No high-confidence opportunities identified.

• A request can set both draco and meshopt; §4.1 gives the precedence. The response optimization block records both requested values, not only the applied one (§4.3).