# 3D Model Generation: Advanced

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](./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](../tutorials/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 for the model on the server

`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:

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

## Build a game asset pipeline

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:

1. **Concept art.** `fal-ai/flux-2` draws the chest.
2. **Mesh.** Meshy 7.1 makes a low-poly mesh with quad faces and PBR textures.
3. **Skin.** `fal-ai/flux-2/edit` draws the same chest in gold.
4. **Retexture.** Meshy 7 Retexture paints the mesh from step 2 with the gold skin.

```typescript
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:

- An image part goes to the image field of the model, for example `image_url` on Meshy 7.1.
- A `model3d` part goes to the mesh field of the model. The fal adapter lists the field for each model in [Mesh input models](../adapters/fal#mesh-input-models).
- On Meshy 7 Retexture, the image part goes to `image_style_url`, the style of the new textures. A text part goes to `text_style_prompt`. With both, Meshy uses the image.

Some changes to try:

- Set `target_polycount` higher for a hero asset that the camera sees close up.
- Set `texture_resolution` to `'4k'` or `'8k'` on step 4 for sharper textures.
- Set `enable_rigging: true` on step 2 for a character. See [Rig and animate a character](#rig-and-animate-a-character).
- Repeat steps 3 and 4 with other text to make more skins for one mesh.

## Rig and animate a character

Meshy 7.1 can rig a humanoid character and add animations in the same job:

```typescript
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:

- `url` is the textured mesh with no skeleton. Load the file with the role `'rigged'` in your engine.
- Each animation is a separate file with the role `'animation'`. Rigging includes basic walk and run animations.
- `enable_animation` needs `enable_rigging`. Set `animation_action_id` to pick a preset from the [Meshy animation library](https://docs.meshy.ai/en/api/animation-library).
- Rigging works best on a humanoid character with clear arms and legs. A T-pose or an A-pose in the concept art helps.

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 |

## Poll the job yourself

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:

```typescript
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? }`:

- `status` is `'pending'`, `'processing'`, `'completed'`, or `'failed'`.
- `result` is the `Model3DResult`. It is set only when `status` is `'completed'`.
- Use an adapter with the same model id as the submit call.

Some more facts about this mode:

- `get3DModelJobStatus()` runs no middleware. For one middleware run over the full job, use `wait` or `stream`.
- In submit mode, `timeout` covers only the submit request, and has no default.
- To cancel a submitted job, call `adapter.cancel3DModelJob(jobId)`. fal can refuse to cancel a job that already runs.

## Stop a job

With `stream` or `wait`, two options stop the run:

- `timeout`: milliseconds for the full job. The default is 10 minutes.
- `abortSignal`: your own signal. The first of the two to fire stops 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:

```typescript
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)
```

## Errors

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:

- Text on a model that takes no text, for example an image-to-3D model or TRELLIS-2 retexture.
- Image parts on a model that takes none, for example a text-to-3D model. Multi-view models take their views in `modelOptions`.
- A `model3d` part on a model with no mesh field, or more than one `model3d` part.
- A video or audio part. No fal 3D model takes them.

A job can also fail on fal:

- With `wait`, the call rejects with the message from fal.
- With `stream`, the stream ends with `RUN_ERROR`, and the hook sets `error`.
- If the finished job has no mesh file, the adapter throws. The message lists the output fields that fal returned.

```typescript
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)
}
```

## Finish the asset for your engine

A generated GLB is a good start, but most engines need more work on it. TanStack AI does not do these steps:

- **Levels of detail (LODs).** Make them with the `simplify` function of [glTF-Transform](https://gltf-transform.dev).
- **Compression.** Draco or meshopt compression makes the file smaller. glTF-Transform does both.
- **Scale and pivot.** Generated models have no real-world scale. Set the scale and the pivot in [Blender](https://www.blender.org) or in your engine.
- **Collision meshes.** Make a simple collision shape in Blender or in your engine.
- **Other formats.** To get FBX for an engine that needs it, import the GLB in Blender and export it again.

Your treasure chest now has clean topology and game-style textures, and is ready for these last steps.
