Run each step of an asset pipeline on the server with wait: true. Pass the URL of one step to the next step as a prompt part. Start with 3D Model Generation for the quick setup. To run the same steps from a page, with a check after each step, follow the Game Asset Pipeline tutorial.
Warning
3D model generation is experimental. The API can change in a minor release. Each step of a pipeline is a separate fal job, and fal bills each job.
wait: true runs the full job and returns the finished Model3DResult. No browser needs to wait for a stream. Use it in a script, a queue worker, or a pipeline:
import { generate3DModel } from '@tanstack/ai'
import { fal3DModel } from '@tanstack/ai-fal'
const model = await generate3DModel({
adapter: fal3DModel('fal-ai/hunyuan-3d/v3.1/pro/text-to-3d'),
prompt: 'A stone well with a wooden roof, game asset',
threadId: 'well',
wait: true,
})
console.log(model.url, model.format) // 'https://...glb', 'glb'wait and stream cannot both be true. A failed job rejects with the message from fal.
This function makes a low-poly treasure chest from one line of text, and then a second skin for the same mesh. It runs four fal jobs, one after the other:
import { generate3DModel, generateImage } from '@tanstack/ai'
import { fal3DModel, falImage } from '@tanstack/ai-fal'
import type { ImageGenerationResult } from '@tanstack/ai'
function firstImageUrl(result: ImageGenerationResult) {
const url = result.images[0]?.url
if (!url) throw new Error('The image step returned no URL.')
return url
}
export async function buildTreasureChest(threadId: string) {
// 1. Concept art
const concept = await generateImage({
adapter: falImage('fal-ai/flux-2'),
prompt:
'A wooden treasure chest with iron bands, game asset, three-quarter view, plain white background',
threadId,
})
const conceptUrl = firstImageUrl(concept)
// 2. A low-poly mesh with quad faces and PBR textures
const mesh = await generate3DModel({
adapter: fal3DModel('meshy/v7.1/image-to-3d'),
prompt: [{ type: 'image', source: { type: 'url', value: conceptUrl } }],
threadId,
wait: true,
modelOptions: { topology: 'quad', target_polycount: 10_000, enable_pbr: true },
})
// 3. The same chest with a new look
const skin = await generateImage({
adapter: falImage('fal-ai/flux-2/edit'),
prompt: [
{
type: 'text',
content: 'Made of gold, with red gems. Keep the same object and view.',
},
{ type: 'image', source: { type: 'url', value: conceptUrl } },
],
threadId,
})
// 4. Paint the same mesh with the new skin
const golden = await generate3DModel({
adapter: fal3DModel('meshy/v7/retexture'),
prompt: [
{ type: 'model3d', source: { type: 'url', value: mesh.url } },
{ type: 'image', source: { type: 'url', value: firstImageUrl(skin) } },
],
threadId,
wait: true,
modelOptions: { enable_pbr: true, texture_resolution: '2k' },
})
return { wooden: mesh, golden }
}Call buildTreasureChest('chest-1'). After about 10 minutes, it returns two Model3DResult values. Each url is a GLB of the same low-poly mesh with a different skin.
How the parts reach fal:
Some changes to try:
Meshy 7.1 can rig a humanoid character and add animations in the same job:
import { generate3DModel } from '@tanstack/ai'
import { fal3DModel } from '@tanstack/ai-fal'
const characterUrl = 'https://example.com/concept/knight.png'
const knight = await generate3DModel({
adapter: fal3DModel('meshy/v7.1/image-to-3d'),
prompt: [{ type: 'image', source: { type: 'url', value: characterUrl } }],
threadId: 'knight',
wait: true,
modelOptions: {
topology: 'quad',
target_polycount: 20_000,
pose_mode: 't-pose',
enable_rigging: true,
enable_animation: true,
},
})
const rigged = knight.files?.find((file) => file.role === 'rigged')
const animations =
knight.files?.filter((file) => file.role === 'animation') ?? []
console.log(rigged?.url)
console.log(animations.map((file) => file.url))What to know:
The roles that a file can have:
| Role | What the file holds |
|---|---|
| 'base' | The mesh as the provider made it |
| 'pbr' | The mesh with PBR materials |
| 'rigged' | The mesh with a skeleton |
| 'animation' | An animated version of the mesh |
| 'part' | One part of a mesh that the provider split into parts |
meshy3DModel() from @tanstack/ai-meshy runs the mesh, the rig, and each animation as separate jobs. Each job reads the result of the job before it from its Meshy task id, so you upload nothing:
import { generate3DModel } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'
// The jobId of an earlier meshy3DModel('image-to-3d') job
const meshJobId = 'your-mesh-task-id'
const rig = await generate3DModel({
adapter: meshy3DModel('rigging'),
prompt: [
{
type: 'model3d',
source: { type: 'file', value: meshJobId, provider: 'meshy' },
},
],
threadId: 'knight',
wait: true,
modelOptions: { skeleton_template: 'ue5_mannequin' },
})
console.log(rig.url) // The rigged GLBWith this path, you can also:
The full chain is in Meshy: rig and animate a character.
Without stream or wait, generate3DModel() only submits the job and returns { jobId, model }. Save the job id, then read the job later with get3DModelJobStatus(). Use this for your own queue, or for a cron job that checks many jobs:
import { generate3DModel, get3DModelJobStatus } from '@tanstack/ai'
import { fal3DModel } from '@tanstack/ai-fal'
const adapter = fal3DModel('fal-ai/hunyuan-3d/v3.1/pro/text-to-3d')
// 1. Submit the job, and save the id (for example in your database)
const { jobId } = await generate3DModel({
adapter,
prompt: 'A stone well with a wooden roof',
threadId: 'well',
})
// 2. Later, in a queue worker
const status = await get3DModelJobStatus({ adapter, jobId })
if (status.status === 'completed' && status.result) {
console.log('Model ready:', status.result.url)
} else if (status.status === 'failed') {
console.error('Job failed:', status.error)
}get3DModelJobStatus() returns { jobId, status, progress?, error?, result? }:
Some more facts about this mode:
With stream or wait, two options stop the run:
When the run stops after fal accepted the job, generate3DModel() asks fal to cancel the job. The cancel is best effort. A failed cancel goes to the error log.
In a pipeline, each step has its own timeout. To stop all the steps at once, give every step the same signal:
import { generate3DModel } from '@tanstack/ai'
import { fal3DModel } from '@tanstack/ai-fal'
// Stop the full pipeline after 30 minutes
const signal = AbortSignal.timeout(30 * 60_000)
const mesh = await generate3DModel({
adapter: fal3DModel('fal-ai/hunyuan3d-v3/text-to-3d'),
prompt: 'A wooden barrel, game asset',
threadId: 'barrel',
wait: true,
abortSignal: signal,
})
const snowy = await generate3DModel({
adapter: fal3DModel('fal-ai/trellis-2/retexture'),
prompt: [
{ type: 'model3d', source: { type: 'url', value: mesh.url } },
{
type: 'image',
source: { type: 'url', value: 'https://example.com/barrel-snow.png' },
},
],
threadId: 'barrel',
wait: true,
abortSignal: signal,
})
console.log(snowy.url)TypeScript narrows the prompt parts for each model. For example, a model3d part on an image-to-3D model is a compile error. Text parts always type-check, so a wrong text part fails at runtime.
If the model cannot use a part, the fal adapter throws before it submits the job. This happens for:
A job can also fail on fal:
import { generate3DModel } from '@tanstack/ai'
import { fal3DModel } from '@tanstack/ai-fal'
try {
const model = await generate3DModel({
adapter: fal3DModel('fal-ai/hunyuan-3d/v3.1/pro/text-to-3d'),
prompt: 'A wooden barrel',
threadId: 'barrel',
wait: true,
})
console.log(model.url)
} catch (error) {
if (error instanceof Error) console.error(error.message)
}A generated GLB is a good start, but most engines need more work on it. TanStack AI does not do these steps:
Your treasure chest now has clean topology and game-style textures, and is ready for these last steps.