Skip to content
Agentic

@agentic/meshy

@agentic/meshy

Section titled “@agentic/meshy”

Declarative 3D asset pipelines powered by Meshy AI — define pipelines in JSON, run from CLI or API, preview instantly.

TypeScript

Stop writing bespoke scripts for every 3D asset. @agentic/meshy wraps Meshy’s text-to-image, text-to-3D, rigging, and animation endpoints in a declarative pipeline system. Define your pipeline as JSON, point it at an asset manifest, and get reproducible results every time.

Why @agentic/meshy?

Section titled “Why @agentic/meshy?”
ProblemSolution
Meshy integration requires custom scripts per assetDeclarative JSON pipelines — no code
Pipeline state lives in memory, lost on failureManifest-based state — resume from any step
No way to replay exact pipeline in CIVCR recording for Meshy calls, fully deterministic
Preview requires external toolsBuilt-in 3D preview with @google/model-viewer

Installation

Section titled “Installation”
Terminal window
pnpm add @jbcom/agentic-meshy
# or
npm install @jbcom/agentic-meshy

Quick Start

Section titled “Quick Start”

CLI

Section titled “CLI”
Terminal window
# List built-in pipelines and tasks
content-gen list \
  --pipelines ./pipelines/definitions \
  --tasks ./tasks/definitions


# Validate an asset manifest
content-gen validate ./assets/characters/hero \
  --pipelines ./pipelines/definitions \
  --tasks ./tasks/definitions


# Run a pipeline
content-gen run character ./assets/characters/hero \
  --pipelines ./pipelines/definitions \
  --tasks ./tasks/definitions

Programmatic API

Section titled “Programmatic API”
import {
  PipelineRunner,
  loadJsonDefinitions
} from '@jbcom/agentic-meshy';


const definitions = await loadJsonDefinitions({
  pipelinesDir: './pipelines/definitions',
  tasksDir: './tasks/definitions',
});


const runner = new PipelineRunner({
  definitions,
  apiKey: process.env.MESHY_API_KEY!,
});


await runner.run({
  pipelineName: 'character',
  assetDir: './assets/characters/hero',
});

Core Concepts

Section titled “Core Concepts”

Pipeline Definitions

Section titled “Pipeline Definitions”

pipelines/definitions/*.pipeline.json describe orchestration. Each step references a task and can override inputs:

{
  "name": "character",
  "steps": [
    {
      "task": "text-to-image",
      "inputs": { "prompt": "{{manifest.description}}" }
    },
    {
      "task": "image-to-3d",
      "inputs": { "image": "{{steps.0.output}}" }
    },
    {
      "task": "auto-rig",
      "inputs": { "model": "{{steps.1.output}}" }
    }
  ]
}

Task Definitions

Section titled “Task Definitions”

tasks/definitions/*.json describe Meshy API calls. Inputs resolve from manifests, previous steps, literals, environment variables, or lookup tables:

{
  "name": "text-to-image",
  "endpoint": "/text-to-image",
  "method": "POST",
  "inputs": {
    "prompt": { "source": "manifest", "key": "description" },
    "style": { "source": "literal", "value": "realistic" }
  }
}

Asset Manifests

Section titled “Asset Manifests”

Each asset directory contains a manifest.json that supplies task inputs and stores pipeline state:

{
  "name": "Hero Character",
  "description": "A medieval knight with ornate armor",
  "style": "fantasy",
  "state": {
    "lastStep": 1,
    "outputs": { "0": "image_abc123.png" }
  }
}

API Server & Preview

Section titled “API Server & Preview”
Terminal window
pnpm dev
  • API reference: http://localhost:5177/api
  • OpenAPI spec: http://localhost:5177/openapi.json
  • 3D Preview: http://localhost:5177/preview?assetDir=./assets/characters/hero&file=model.glb

The preview uses @google/model-viewer from your local install (no CDN dependency).

Testing

Section titled “Testing”
Terminal window
# Unit tests
pnpm test:unit


# E2E tests
pnpm test:e2e


# Record Meshy calls for replay in CI
POLLY_MODE=record pnpm test:unit


# Replay recorded calls (default)
POLLY_MODE=replay pnpm test:unit

Environment Variables

Section titled “Environment Variables”
VariableRequiredDescription
MESHY_API_KEYYesMeshy API key
POLLY_MODENorecord or replay (default: replay)

Integration with Strata

Section titled “Integration with Strata”

@agentic/meshy powers the 3D asset pipeline for Strata, the AI-powered gaming platform:

  • Character models: Text description → 3D model → rigged → animated
  • Environment assets: Procedural generation of buildings, terrain features, props
  • Item generation: Weapons, armor, consumables from text descriptions
  • Batch processing: Generate entire game asset libraries from a manifest directory
Section titled “Related Packages”
Section titled “Links”