TanStack
Adapters

Meshy

meshy3DModel() with generate3DModel() turns a text prompt or a concept image into a textured GLB. The jobId of one job is the input of the next job, so you can rig and animate a character with no upload. meshyMotion() makes text-to-motion clips. The adapter has no chat.

Warning

3D model generation and motion generation are experimental. The API can change. Meshy charges credits when it creates a task, and gives them back when the task fails.

1. Install

shell
npm i @tanstack/ai @tanstack/ai-meshy

2. Set the API key

Create an API key in your Meshy account settings. Put it in the environment of your server:

shell
MESHY_API_KEY=your-meshy-key

meshy3DModel and meshyMotion read MESHY_API_KEY. To pass the key in code, set apiKey in the last argument:

ts
import { meshy3DModel, meshyMotion } from '@tanstack/ai-meshy'

const apiKey = process.env.MESHY_API_KEY

const imageTo3D = meshy3DModel('image-to-3d', 'meshy-7.1', { apiKey })
const rigging = meshy3DModel('rigging', { apiKey })
const motion = meshyMotion('prime', { apiKey })

The first argument of meshy3DModel is the Meshy endpoint. The second argument is the Meshy ai_model. Only five endpoints take an ai_model. The others take the config as the second argument. See Endpoints.

3. Make your first model

Text to 3D is two jobs:

  1. text-to-3d-preview makes the mesh, with no texture.
  2. text-to-3d-refine paints the textures on that mesh.

This script makes a treasure chest and saves the GLB next to the script:

ts
import { writeFile } from 'node:fs/promises'
import { generate3DModel } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'

const preview = await generate3DModel({
  adapter: meshy3DModel('text-to-3d-preview', 'meshy-7.1'),
  prompt: 'A wooden treasure chest with iron bands, game asset',
  threadId: 'treasure-chest',
  wait: true,
  modelOptions: { topology: 'quad', target_polycount: 10_000 },
})

const chest = await generate3DModel({
  adapter: meshy3DModel('text-to-3d-refine', 'meshy-7'),
  prompt: [
    {
      type: 'model3d',
      source: { type: 'file', value: preview.jobId, provider: 'meshy' },
    },
    { type: 'text', content: 'Old oak planks, rusty iron bands' },
  ],
  threadId: 'treasure-chest',
  wait: true,
  modelOptions: { enable_pbr: true },
})

const response = await fetch(chest.url)
if (!response.ok) throw new Error(`Download failed: ${chest.url}`)
await writeFile('treasure-chest.glb', Buffer.from(await response.arrayBuffer()))
console.log('Saved treasure-chest.glb')

Run the script. You now have a textured, low-poly chest on disk. Drop the GLB into your engine.

What to know:

  • jobId is the Meshy task id. The refine job reads the preview mesh from it, so the script uploads nothing.
  • The text part of the refine job describes the textures.
  • Meshy keeps generated files for 3 days, on all plans except Enterprise. Copy each file that you want to keep.

4. Stream the job to the browser

Pass stream: true. The server submits the job, checks it, and streams each status to the browser. Meshy reports a progress number from 0 to 100.

This route takes one concept image. image-to-3d makes a textured model in one job.

Server route at /api/generate/3d-model:

ts
import {
  generate3DModel,
  generationParamsFromRequest,
  toServerSentEventsResponse,
} from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'

export async function POST(request: Request) {
  const { input, threadId } = await generationParamsFromRequest(
    '3dModel',
    request,
  )
  const images = Array.isArray(input.prompt)
    ? input.prompt.filter((part) => part.type === 'image')
    : []
  if (images.length !== 1) {
    return new Response('Send one image.', { status: 400 })
  }

  const stream = generate3DModel({
    adapter: meshy3DModel('image-to-3d', 'meshy-7.1'),
    prompt: images,
    threadId,
    stream: true,
    abortSignal: request.signal,
    modelOptions: {
      topology: 'quad',
      target_polycount: 10_000,
      enable_pbr: true,
    },
  })
  return toServerSentEventsResponse(stream)
}

React component:

tsx
import { useState } from 'react'
import { fetchServerSentEvents, useGenerate3DModel } from '@tanstack/ai-react'

const conceptUrl = 'https://example.com/concept/treasure-chest.png'

export function MeshyModel() {
  const [progress, setProgress] = useState(0)
  const { generate, result, isLoading, error } = useGenerate3DModel({
    connection: fetchServerSentEvents('/api/generate/3d-model'),
    threadId: 'treasure-chest',
    onProgress: (value) => setProgress(value),
  })

  return (
    <div>
      <button
        onClick={() =>
          generate({
            prompt: [
              { type: 'image', source: { type: 'url', value: conceptUrl } },
            ],
          })
        }
        disabled={isLoading}
      >
        Generate model
      </button>
      {isLoading ? <p>Progress: {progress}%</p> : null}
      {error ? <p role="alert">{error.message}</p> : null}
      {result ? <a href={result.url}>Download the .{result.format} file</a> : null}
    </div>
  )
}

Click Generate model. The progress goes up to 100%, then the download link shows. To show the model in the page, use the three.js viewer from 3D Model Generation.

If the browser closes the request, generate3DModel() asks Meshy to cancel the task. Meshy cancels only a task that waits in the queue. A running task finishes, and Meshy charges for it. The adapter reads the task before it cancels, so it almost never deletes a finished model. A task that finishes between that read and the cancel request can still be deleted.

A Meshy job can take longer than the default timeout of 10 minutes when Meshy is busy. Meshy says to wait up to 60 minutes. For long jobs, set a larger timeout, for example timeout: 30 * 60_000. A timeout does not stop a running task, so Meshy still charges for it.

Rig and animate a character

Chain three jobs. Each job reads the result of the job before it from its task id:

  1. image-to-3d makes the character mesh.
  2. rigging adds a skeleton.
  3. animation puts an action from the Meshy animation library on the rig.
ts
import { generate3DModel } from '@tanstack/ai'
import { listMeshyAnimations, meshy3DModel } from '@tanstack/ai-meshy'

const threadId = 'knight'

const mesh = await generate3DModel({
  adapter: meshy3DModel('image-to-3d', 'meshy-7.1'),
  prompt: [
    {
      type: 'image',
      source: { type: 'url', value: 'https://example.com/concept/knight.png' },
    },
  ],
  threadId,
  wait: true,
  modelOptions: { pose_mode: 't-pose', topology: 'quad', target_polycount: 20_000 },
})

const rig = await generate3DModel({
  adapter: meshy3DModel('rigging'),
  prompt: [
    {
      type: 'model3d',
      source: { type: 'file', value: mesh.jobId, provider: 'meshy' },
    },
  ],
  threadId,
  wait: true,
  modelOptions: { animation_type: 'biped', height_meters: 1.8 },
})

const actions = await listMeshyAnimations({ category: 'WalkAndRun' })
const action = actions.find((item) => item.rigType === 'biped')
if (!action) throw new Error('No biped action in this category.')

const clip = await generate3DModel({
  adapter: meshy3DModel('animation'),
  prompt: [
    {
      type: 'model3d',
      source: { type: 'file', value: rig.jobId, provider: 'meshy' },
    },
  ],
  threadId,
  wait: true,
  modelOptions: { action_id: action.actionId },
})

console.log(rig.url) // The rigged GLB
console.log(clip.url) // The animated GLB

You now have a rigged knight and an animated knight, from one concept image.

What each result holds:

  • rig.url is the rigged GLB. rig.files also has the rigged FBX, and basic walk and run clips with the role 'animation'.
  • clip.url is the animated GLB. clip.files also has the animated FBX.
  • animation takes the rig only as a Meshy task id. A URL source throws before the job starts.

More options:

  • Set skeleton_template on rigging to get a known skeleton, for example 'mixamo' or 'ue5_mannequin'.
  • Set action_ids on animation to get up to 10 clips in one job.
  • listMeshyAnimations() costs no credits. Each action has a previewUrl, an animated GIF of the action.

Make a motion clip

meshyMotion() with generateMotion() turns a prompt into a skeletal animation clip. The clip is not on a character. duration is required: 2 to 10 seconds, in steps of 0.5.

ts
import { writeFile } from 'node:fs/promises'
import { generateMotion, getMotionJobStatus } from '@tanstack/ai'
import { meshyMotion } from '@tanstack/ai-meshy'

const adapter = meshyMotion('prime')

const { jobId } = await generateMotion({
  adapter,
  threadId: 'knight-attacks',
  prompt: 'A knight raises a sword overhead with both hands and slams it down',
  duration: 4,
})

let status = await getMotionJobStatus({ adapter, jobId })
while (status.status === 'pending' || status.status === 'processing') {
  await new Promise((resolve) => setTimeout(resolve, 5000))
  status = await getMotionJobStatus({ adapter, jobId })
}

if (!status.motion) {
  throw new Error(status.error ?? 'Motion generation failed')
}

for (const asset of status.motion.assets) {
  const response = await fetch(asset.url)
  if (!response.ok) throw new Error(`Download failed: ${asset.url}`)
  const fileName = asset.fileName ?? `knight-attack.${asset.format}`
  await writeFile(fileName, Buffer.from(await response.arrayBuffer()))
  console.log(`Saved ${fileName}`)
}

console.log('Motion task id:', jobId)

The two modes:

ModeFileUse it for
'prime'FBXA higher quality clip
'swift'BVHA faster and cheaper clip

To stream the job to a browser, use the same route and component as the other motion providers. See Show the job in a browser.

Put the clip on your rig

Pass the motion jobId as modelOptions.motion_task_id to meshy3DModel('animation'). The rig is the rigging job from Rig and animate a character:

ts
import { generate3DModel } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'

// The ids from the rigging job and the motion job.
const rigJobId = 'your-rigging-task-id'
const motionJobId = 'your-motion-task-id'

const attack = await generate3DModel({
  adapter: meshy3DModel('animation'),
  prompt: [
    {
      type: 'model3d',
      source: { type: 'file', value: rigJobId, provider: 'meshy' },
    },
  ],
  threadId: 'knight-attacks',
  wait: true,
  modelOptions: { motion_task_id: motionJobId },
})

console.log(attack.url) // The knight, with the sword attack

Your knight now plays the attack from your prompt. The motion task must be complete, and the rig must be a biped.

Endpoints

The first argument of meshy3DModel() picks the endpoint. TypeScript types the prompt parts and modelOptions for each endpoint.

EndpointPromptai_model
text-to-3d-previewText'meshy-7.1', 'meshy-6', 'meshy-6-lite', 'meshy-t2', 'meshy-t2.5', 'latest'
text-to-3d-refineThe preview task, plus optional text or one image for the textures'meshy-7', 'meshy-6', 'meshy-6-lite', 'meshy-n1', 'latest'
image-to-3dOne image, plus optional text for the texturesThe same as text-to-3d-preview
multi-image-to-3d1 to 4 images of one object, plus optional text'meshy-7.1', 'meshy-6', 'meshy-6-lite', 'latest'
retextureA mesh, plus text, or 1 style image, or 2 to 4 viewsThe same as text-to-3d-refine

Some models have extra rules:

  • 'meshy-t2' and 'meshy-t2.5' are Smart Topology models. The adapter sends model_type: 'smart-topology' for them.
  • retexture with 2 to 4 views needs 'meshy-7' or 'meshy-n1', and takes no text. The adapter throws before the request otherwise.

These endpoints change a model that you already have. They take no ai_model:

A mesh is a model3d part. Its source can be:

  • { type: 'file', value: jobId, provider: 'meshy' }: the result of an earlier Meshy job. Use this to chain jobs.
  • A url or data source: a mesh file of your own. text-to-3d-refine, animation, and print-split take only a task id.

For checks from another request, cancel, the 3D print helpers, and bring your own key, see Meshy: Advanced.