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 |
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.