Pass a model that you already have to a Meshy endpoint, for example meshy3DModel('print-repair'). You get back a changed model: a new topology, new formats, or a file that is ready for your printer. To make a first model, start at Meshy.
A mesh is a model3d part. Use a Meshy task id to change the result of an earlier job. Use a URL to change a file of your own:
import { generate3DModel } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'
const remeshed = await generate3DModel({
adapter: meshy3DModel('remesh'),
prompt: [
{
type: 'model3d',
source: { type: 'url', value: 'https://example.com/models/statue.glb' },
},
],
threadId: 'statue',
wait: true,
modelOptions: {
topology: 'quad',
target_polycount: 5_000,
target_formats: ['glb', 'fbx'],
},
})
console.log(remeshed.url) // The GLB with 5,000 quad facesThe four endpoints that change a model:
| Endpoint | What it changes | Main modelOptions |
|---|---|---|
| remesh | The topology and the polygon count | topology, target_polycount, target_formats |
| convert | Only the file formats | target_formats (required) |
| resize | The real-world size, in meters | resize_height, resize_longest_side, auto_size, origin_at |
| uv-unwrap | The UV layout | None |
target_formats takes 'glb', 'obj', 'fbx', 'stl', 'usdz', '3mf', and 'blend'. A .blend file is in files with no format. Ask for 'blend' together with a mesh format. With 'blend' alone, remesh and convert throw before the request, because the result has no mesh file.
These endpoints take no text and no images. TypeScript stops an image part. A text part type-checks, but the adapter throws before it starts the job.
Start from a model that Meshy made, for example an image-to-3d job. Then:
What each print step takes:
analyzeMeshyPrintability() starts a Meshy analysis, waits for it, and returns the report. The analysis costs no credits:
import { analyzeMeshyPrintability } from '@tanstack/ai-meshy'
const report = await analyzeMeshyPrintability({
model: { type: 'url', value: 'https://example.com/models/dragon.glb' },
printerType: 'fdm',
intendedPrintHeightMm: 120,
abortSignal: AbortSignal.timeout(120_000),
})
console.log(report.status) // 'healthy', 'warning', 'error', or 'unknown'
console.log(report.metrics?.is_watertight, report.metrics?.holes)
console.log(report.thin_walls?.has_thin_walls)What to know:
This script makes a dragon figure from a concept image. Then it repairs the figure, makes a 4-color 3MF file, and cuts the figure into parts. Each print step reads the Meshy figure, so the three steps are independent:
import { writeFile } from 'node:fs/promises'
import { generate3DModel } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'
const threadId = 'dragon-figure'
const figure = await generate3DModel({
adapter: meshy3DModel('image-to-3d', 'meshy-7.1'),
prompt: [
{
type: 'image',
source: { type: 'url', value: 'https://example.com/concepts/dragon.png' },
},
],
threadId,
wait: true,
timeout: 30 * 60_000,
})
const meshyFigure = {
type: 'model3d',
source: { type: 'file', value: figure.jobId, provider: 'meshy' },
} as const
const repaired = await generate3DModel({
adapter: meshy3DModel('print-repair'),
prompt: [meshyFigure],
threadId,
wait: true,
modelOptions: { printer_type: 'fdm', intended_print_height_mm: 120 },
})
const colored = await generate3DModel({
adapter: meshy3DModel('print-multi-color'),
prompt: [meshyFigure],
threadId,
wait: true,
modelOptions: { max_colors: 4, printer_brand: 'bambu' },
})
const response = await fetch(colored.url)
if (!response.ok) throw new Error(`Download failed: ${colored.url}`)
await writeFile('dragon.3mf', Buffer.from(await response.arrayBuffer()))
const parts = await generate3DModel({
adapter: meshy3DModel('print-split'),
prompt: [meshyFigure, { type: 'text', content: 'head, wings, body, tail' }],
threadId,
wait: true,
modelOptions: { mode: 'by_parts', layout: 'on_plate', connectors: true },
})
console.log(repaired.url)
console.log(parts.files?.map((file) => file.url))Run the script. You now have dragon.3mf on disk, with a slicer preset for a Bambu printer. Open it in your slicer.
What each step does:
Meshy keeps generated files for 3 days, on all plans except Enterprise. Copy each file that you want to keep.
relief carves a photo into a plaque. It takes one image part:
import { generate3DModel } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'
const plaque = await generate3DModel({
adapter: meshy3DModel('relief'),
prompt: [
{
type: 'image',
source: { type: 'url', value: 'https://example.com/photos/dog.jpg' },
},
],
threadId: 'dog-plaque',
wait: true,
modelOptions: { size_mm: 120, carving_mode: 'emboss', base_thickness_mm: 3 },
})
const stl = plaque.files?.find((file) => file.format === 'stl')
console.log(stl?.url) // The STL for your slicerBy default, Meshy makes a GLB and an STL. size_mm is the longer side of the photo, from 20 to 250 millimeters. Set carving_mode: 'engrave' to cut the near parts in.
getMeshyBalance() returns the credits of the account that owns the API key:
import { getMeshyBalance } from '@tanstack/ai-meshy'
const { balance, monthlyCredits, permanentCredits, monthlyResetsAt } =
await getMeshyBalance()
console.log(balance, monthlyCredits, permanentCredits, monthlyResetsAt)monthlyCredits expire at monthlyResetsAt. permanentCredits do not expire. monthlyResetsAt is not set when the account has no monthly refresh.
listMeshyAnimations() lists the actions in the Meshy animation library. It costs no credits:
import { listMeshyAnimations } from '@tanstack/ai-meshy'
const swings = await listMeshyAnimations({ search: 'sword' })
for (const action of swings) {
console.log(action.actionId, action.name, action.rigType, action.previewUrl)
}The filters are search, category, subCategory, and actionIds. Every filter that you set must match. Pass actionId as modelOptions.action_id to meshy3DModel('animation'). A biped rig takes only biped actions.
Without wait or stream, generate3DModel() only submits the job and returns { jobId, model }. Save the id, then read the job in another request with get3DModelJobStatus():
import { generate3DModel, get3DModelJobStatus } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'
// Request 1: submit the job, and save the id
const { jobId } = await generate3DModel({
adapter: meshy3DModel('rigging'),
prompt: [
{
type: 'model3d',
source: { type: 'url', value: 'https://example.com/models/knight.glb' },
},
],
threadId: 'knight',
})
// Request 2: read the job with an adapter for the same endpoint
const status = await get3DModelJobStatus({
adapter: meshy3DModel('rigging'),
jobId,
})
if (status.status === 'completed' && status.result) {
console.log('Ready:', status.result.url)
} else if (status.status === 'failed') {
console.error(status.error)
} else {
console.log(status.status, status.progress) // for example 'processing', 40
}The endpoint sets the Meshy URL of the task, so use the same endpoint in both requests. For a motion job, call getMotionJobStatus() with meshyMotion() in the same way.
Meshy cancels only a task that waits in the queue ('pending'). Then Meshy gives back the credits. The adapter reads the task first and cancels only a 'pending' task.
import { meshy3DModel } from '@tanstack/ai-meshy'
const adapter = meshy3DModel('image-to-3d', 'meshy-7.1')
try {
await adapter.cancel3DModelJob('your-task-id')
} catch (error) {
if (error instanceof Error) console.error(error.message)
}What to know:
The adapter repeats a status request on 408, 409, 429, and 5xx. It never repeats a create request, so one call cannot charge twice.
import { generate3DModel } from '@tanstack/ai'
import { MeshyApiError, meshy3DModel } from '@tanstack/ai-meshy'
try {
const model = await generate3DModel({
adapter: meshy3DModel('text-to-3d-preview', 'meshy-7.1'),
prompt: 'A wooden barrel, game asset',
threadId: 'barrel',
wait: true,
})
console.log(model.url)
} catch (error) {
if (error instanceof MeshyApiError) {
console.error('Meshy answered', error.status, error.message)
} else if (error instanceof Error) {
console.error(error.message)
}
}meshyByok from @tanstack/ai-meshy/byok declares Meshy for the BYOK store, with MESHY_API_KEY as its env var. On the server, pass the key that you read as apiKey in the last argument of meshy3DModel() or meshyMotion(). See Bring Your Own Key.
| Export | What it does |
|---|---|
| meshy3DModel(endpoint, aiModel?, config?) | Creates a 3D model adapter for generate3DModel() |
| meshyMotion(mode, config?) | Creates a motion adapter for generateMotion(). mode is 'prime' or 'swift'. |
| analyzeMeshyPrintability(options) | Checks if a model can be printed, and returns the report |
| getMeshyBalance(options?) | Returns the credit balance |
| listMeshyAnimations(options?) | Lists the actions in the animation library |
| MeshyApiError | The error for a Meshy response that is not 2xx |
The config fields, also accepted by the helpers: