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.
npm i @tanstack/ai @tanstack/ai-meshypnpm add @tanstack/ai @tanstack/ai-meshyyarn add @tanstack/ai @tanstack/ai-meshybun add @tanstack/ai @tanstack/ai-meshyCreate an API key in your Meshy account settings. Put it in the environment of your server:
MESHY_API_KEY=your-meshy-keymeshy3DModel and meshyMotion read MESHY_API_KEY. To pass the key in code, set apiKey in the last argument:
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.
Text to 3D is two jobs:
This script makes a treasure chest and saves the GLB next to the script:
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:
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:
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:
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.
Chain three jobs. Each job reads the result of the job before it from its task id:
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 GLBYou now have a rigged knight and an animated knight, from one concept image.
What each result holds:
More options:
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.
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:
| Mode | File | Use it for |
|---|---|---|
| 'prime' | FBX | A higher quality clip |
| 'swift' | BVH | A 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.
Pass the motion jobId as modelOptions.motion_task_id to meshy3DModel('animation'). The rig is the rigging job from Rig and animate a character:
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 attackYour knight now plays the attack from your prompt. The motion task must be complete, and the rig must be a biped.
The first argument of meshy3DModel() picks the endpoint. TypeScript types the prompt parts and modelOptions for each endpoint.
| Endpoint | Prompt | ai_model |
|---|---|---|
| text-to-3d-preview | Text | 'meshy-7.1', 'meshy-6', 'meshy-6-lite', 'meshy-t2', 'meshy-t2.5', 'latest' |
| text-to-3d-refine | The preview task, plus optional text or one image for the textures | 'meshy-7', 'meshy-6', 'meshy-6-lite', 'meshy-n1', 'latest' |
| image-to-3d | One image, plus optional text for the textures | The same as text-to-3d-preview |
| multi-image-to-3d | 1 to 4 images of one object, plus optional text | 'meshy-7.1', 'meshy-6', 'meshy-6-lite', 'latest' |
| retexture | A mesh, plus text, or 1 style image, or 2 to 4 views | The same as text-to-3d-refine |
Some models have extra rules:
These endpoints change a model that you already have. They take no ai_model:
A mesh is a model3d part. Its source can be:
For checks from another request, cancel, the 3D print helpers, and bring your own key, see Meshy: Advanced.