Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions .changeset/rename-3d-activities.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
---
'@tanstack/ai': minor
'@tanstack/ai-client': minor
'@tanstack/ai-event-client': minor
'@tanstack/ai-fal': minor
'@tanstack/ai-meshy': minor
'@tanstack/ai-uthana': minor
'@tanstack/ai-react': minor
'@tanstack/ai-solid': minor
'@tanstack/ai-vue': minor
'@tanstack/ai-svelte': minor
'@tanstack/ai-angular': minor
'@tanstack/ai-remix': minor
'@tanstack/ai-octane': minor
---

Rename the experimental 3D model and motion APIs. Every name now writes `3d` in lower case, and the motion functions have a `3d` prefix. The options and results do not change. Update your imports and calls.

- `generate3DModel()` is now `generate3dModel()`. `get3DModelJobStatus()` and `create3DModelOptions()` change the same way. In an agent, `ctx.generate3DModel` is now `ctx.generate3dModel`.
- `generateMotion()` is now `generate3dMotion()`. `getMotionJobStatus()`, `cancelMotionJob()` and `createMotionOptions()` are now `get3dMotionJobStatus()`, `cancel3dMotionJob()` and `create3dMotionOptions()`.
- The types `Model3D*` are now `Model3d*`, for example `Model3dResult` and `Model3dAdapter`. `Model3DGenerateInput` in `@tanstack/ai-client` is now `Model3dGenerateInput`.
- The adapters `fal3DModel()`, `meshy3DModel()`, `falMotion()`, `meshyMotion()` and `uthanaMotion()` are now `fal3dModel()`, `meshy3dModel()`, `fal3dMotion()`, `meshy3dMotion()` and `uthana3dMotion()`.
- The hooks `useGenerate3DModel`, `createGenerate3DModel` and `injectGenerate3DModel` are now `useGenerate3dModel`, `createGenerate3dModel` and `injectGenerate3dModel`.
- A custom adapter renames its methods: `create3DModelJob`, `get3DModelStatus`, `get3DModel` and `cancel3DModelJob` take `3d`, and `createMotionJob`, `getMotionStatus`, `getMotion` and `cancelMotionJob` become `create3dMotionJob`, `get3dMotionStatus`, `get3dMotion` and `cancel3dMotionJob`.
- The motion types `Motion*` are now `Motion3d*`, for example `Motion3dAdapter`, `BaseMotion3dAdapter`, `Motion3dGenerationResult` and `FalMotion3dAdapter`.
- The motion adapter `kind` is now `'motion3d'`. Pass `'motion3d'` to `generationParamsFromRequest()`.
- The motion events are now `motion3d:*`, for example `motion3d:status` and `motion3d:request:started`. `MOTION_EVENTS` is now `MOTION3D_EVENTS`.
30 changes: 15 additions & 15 deletions docs/adapters/fal.md
Original file line number Diff line number Diff line change
Expand Up @@ -189,14 +189,14 @@ The `duration` values of each model are in [Video durations](#video-durations).

## 3D models

`fal3DModel()` turns an image, a text prompt, or an existing mesh into a 3D model file. Like video, it runs as a job. With `wait: true`, `generate3DModel()` returns the finished model:
`fal3dModel()` turns an image, a text prompt, or an existing mesh into a 3D model file. Like video, it runs as a job. With `wait: true`, `generate3dModel()` returns the finished model:

```typescript
import { generate3DModel } from "@tanstack/ai";
import { fal3DModel } from "@tanstack/ai-fal";
import { generate3dModel } from "@tanstack/ai";
import { fal3dModel } from "@tanstack/ai-fal";

const model = await generate3DModel({
adapter: fal3DModel("fal-ai/hunyuan-3d/v3.1/pro/image-to-3d"),
const model = await generate3dModel({
adapter: fal3dModel("fal-ai/hunyuan-3d/v3.1/pro/image-to-3d"),
prompt: [
{
type: "image",
Expand Down Expand Up @@ -226,15 +226,15 @@ console.log(model.url, model.format); // "https://...glb", "glb"

## Motion

`falMotion` makes a skeletal animation clip (FBX) from a prompt. It runs as a job. `generateMotion()` submits it, and `getMotionJobStatus()` reads its status:
`fal3dMotion` makes a skeletal animation clip (FBX) from a prompt. It runs as a job. `generate3dMotion()` submits it, and `get3dMotionJobStatus()` reads its status:

```typescript
import { generateMotion, getMotionJobStatus } from "@tanstack/ai";
import { falMotion } from "@tanstack/ai-fal";
import { generate3dMotion, get3dMotionJobStatus } from "@tanstack/ai";
import { fal3dMotion } from "@tanstack/ai-fal";

const adapter = falMotion("fal-ai/hunyuan-motion");
const adapter = fal3dMotion("fal-ai/hunyuan-motion");

const { jobId } = await generateMotion({
const { jobId } = await generate3dMotion({
adapter,
prompt: "A heavy two-handed overhead axe swing with a slow wind-up",
threadId: "orc-attacks",
Expand All @@ -245,7 +245,7 @@ const { jobId } = await generateMotion({
},
});

const status = await getMotionJobStatus({ adapter, jobId });
const status = await get3dMotionJobStatus({ adapter, jobId });

console.log(status.status); // "pending" | "processing" | "completed" | "failed"
console.log(status.motion?.assets[0]?.url); // The FBX, when the job is complete
Expand All @@ -270,7 +270,7 @@ What you get back:
- fal takes no character or skeleton input.
- File URLs expire after the media expiry time in your fal account. Download the files and store them.

`cancelMotionJob()` uses the fal queue cancel. fal removes a queued job. A running job can still finish. fal refuses a cancel for a completed job.
`cancel3dMotionJob()` uses the fal queue cancel. fal removes a queued job. A running job can still finish. fal refuses a cancel for a completed job.

See [Motion Generation](../media/motion-generation) for streaming, agent tools, and engine import.

Expand Down Expand Up @@ -415,7 +415,7 @@ fal has hundreds of models. These are popular picks. Any fal model id works.

### 3D model endpoints

`fal3DModel()` knows these families. Write the id as a string literal, and TypeScript completes `modelOptions` and narrows the prompt parts. Any other fal 3D id also works, with no types.
`fal3dModel()` knows these families. Write the id as a string literal, and TypeScript completes `modelOptions` and narrows the prompt parts. Any other fal 3D id also works, with no types.

| Family | Ids | Input |
|--------|-----|-------|
Expand Down Expand Up @@ -454,7 +454,7 @@ For a low-poly mesh with quad faces, set `topology: 'quad'` and `target_polycoun
| `fal-ai/hunyuan-motion` | Hunyuan Motion 1B. About $0.08 per generation. |
| `fal-ai/hunyuan-motion/fast` | Hunyuan Motion 0.46B, faster. About $0.06 per generation. |

Both take the same options and return FBX. Use them with `falMotion()` and `generateMotion()`. Prices are from the fal model pages and can change.
Both take the same options and return FBX. Use them with `fal3dMotion()` and `generate3dMotion()`. Prices are from the fal model pages and can change.

### Text-to-speech models

Expand Down Expand Up @@ -586,7 +586,7 @@ Each factory takes `model` first and an optional `config` (`apiKey`, `proxyUrl`,
| `falSpeech(model, config?)` | `FalSpeechAdapter` | `generateSpeech()`. The audio comes back as base64 in `result.audio`. |
| `falTranscription(model, config?)` | `FalTranscriptionAdapter` | `generateTranscription()` |
| `falAudio(model, config?)` | `FalAudioAdapter` | `generateAudio()`. The result has a URL at `result.audio.url`. |
| `fal3DModel(model, config?)` | `Fal3DModelAdapter` | `generate3DModel()`, `get3DModelJobStatus()`. Experimental. |
| `fal3dModel(model, config?)` | `Fal3dModelAdapter` | `generate3dModel()`, `get3dModelJobStatus()`. Experimental. |
| `falFiles(config?)` | `FalFilesAdapter` | The [Files API](../advanced/files-api) |

Helpers:
Expand Down
82 changes: 41 additions & 41 deletions docs/adapters/meshy-advanced.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,23 +9,23 @@ keywords:
- 3mf
- remesh
- printability
- generate3DModel
- get3DModelJobStatus
- generate3dModel
- get3dModelJobStatus
- adapter
---

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](./meshy).
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](./meshy).

## Change a model

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:

```ts
import { generate3DModel } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'
import { generate3dModel } from '@tanstack/ai'
import { meshy3dModel } from '@tanstack/ai-meshy'

const remeshed = await generate3DModel({
adapter: meshy3DModel('remesh'),
const remeshed = await generate3dModel({
adapter: meshy3dModel('remesh'),
prompt: [
{
type: 'model3d',
Expand Down Expand Up @@ -108,13 +108,13 @@ This script makes a dragon figure from a concept image. Then it repairs the figu

```ts
import { writeFile } from 'node:fs/promises'
import { generate3DModel } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'
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'),
const figure = await generate3dModel({
adapter: meshy3dModel('image-to-3d', 'meshy-7.1'),
prompt: [
{
type: 'image',
Expand All @@ -130,16 +130,16 @@ const meshyFigure = {
source: { type: 'file', value: figure.jobId, provider: 'meshy' },
} as const

const repaired = await generate3DModel({
adapter: meshy3DModel('print-repair'),
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'),
const colored = await generate3dModel({
adapter: meshy3dModel('print-multi-color'),
prompt: [meshyFigure],
threadId,
wait: true,
Expand All @@ -150,8 +150,8 @@ 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'),
const parts = await generate3dModel({
adapter: meshy3dModel('print-split'),
prompt: [meshyFigure, { type: 'text', content: 'head, wings, body, tail' }],
threadId,
wait: true,
Expand All @@ -178,11 +178,11 @@ Meshy keeps generated files for 3 days, on all plans except Enterprise. Copy eac
`relief` carves a photo into a plaque. It takes one image part:

```ts
import { generate3DModel } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'
import { generate3dModel } from '@tanstack/ai'
import { meshy3dModel } from '@tanstack/ai-meshy'

const plaque = await generate3DModel({
adapter: meshy3DModel('relief'),
const plaque = await generate3dModel({
adapter: meshy3dModel('relief'),
prompt: [
{
type: 'image',
Expand Down Expand Up @@ -229,19 +229,19 @@ for (const action of swings) {
}
```

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

## Check a job from another request

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

```ts
import { generate3DModel, get3DModelJobStatus } from '@tanstack/ai'
import { meshy3DModel } from '@tanstack/ai-meshy'
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'),
const { jobId } = await generate3dModel({
adapter: meshy3dModel('rigging'),
prompt: [
{
type: 'model3d',
Expand All @@ -252,8 +252,8 @@ const { jobId } = await generate3DModel({
})

// Request 2: read the job with an adapter for the same endpoint
const status = await get3DModelJobStatus({
adapter: meshy3DModel('rigging'),
const status = await get3dModelJobStatus({
adapter: meshy3dModel('rigging'),
jobId,
})

Expand All @@ -266,19 +266,19 @@ if (status.status === 'completed' && status.result) {
}
```

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.
The endpoint sets the Meshy URL of the task, so use the same endpoint in both requests. For a motion job, call `get3dMotionJobStatus()` with `meshy3dMotion()` in the same way.

## Cancel a job

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.

```ts
import { meshy3DModel } from '@tanstack/ai-meshy'
import { meshy3dModel } from '@tanstack/ai-meshy'

const adapter = meshy3DModel('image-to-3d', 'meshy-7.1')
const adapter = meshy3dModel('image-to-3d', 'meshy-7.1')

try {
await adapter.cancel3DModelJob('your-task-id')
await adapter.cancel3dModelJob('your-task-id')
} catch (error) {
if (error instanceof Error) console.error(error.message)
}
Expand All @@ -289,7 +289,7 @@ What to know:
- For a running task, the cancel throws `Meshy task <id> is already running and cannot be canceled`. The task finishes, and Meshy charges for it.
- For a finished task, the cancel does nothing. The model and its files stay.
- A task can finish between the read and the cancel request. Then Meshy deletes the finished model. This window is one request long, so it is rare.
- `cancelMotionJob()` from `@tanstack/ai` works in the same way for `meshyMotion()` jobs.
- `cancel3dMotionJob()` from `@tanstack/ai` works in the same way for `meshy3dMotion()` jobs.
- With `stream` or `wait`, an abort or a `timeout` also asks Meshy to cancel. If the task already runs, the failed cancel goes to the error log.

## Errors
Expand All @@ -301,12 +301,12 @@ 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.

```ts
import { generate3DModel } from '@tanstack/ai'
import { MeshyApiError, meshy3DModel } from '@tanstack/ai-meshy'
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'),
const model = await generate3dModel({
adapter: meshy3dModel('text-to-3d-preview', 'meshy-7.1'),
prompt: 'A wooden barrel, game asset',
threadId: 'barrel',
wait: true,
Expand All @@ -323,14 +323,14 @@ try {

## Bring your own key

`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](../advanced/byok).
`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 `meshy3dMotion()`. See [Bring Your Own Key](../advanced/byok).

## API reference

| 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'`. |
| `meshy3dModel(endpoint, aiModel?, config?)` | Creates a 3D model adapter for `generate3dModel()` |
| `meshy3dMotion(mode, config?)` | Creates a motion adapter for `generate3dMotion()`. `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 |
Expand Down
Loading
Loading