@tanstack/ai-fal 1.1.1 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/esm/adapters/audio.js +2 -3
- package/dist/esm/adapters/audio.js.map +1 -1
- package/dist/esm/adapters/files.js +1 -2
- package/dist/esm/adapters/image.js +2 -3
- package/dist/esm/adapters/image.js.map +1 -1
- package/dist/esm/adapters/live.js +1 -2
- package/dist/esm/adapters/model3d.d.ts +98 -0
- package/dist/esm/adapters/model3d.js +170 -0
- package/dist/esm/adapters/model3d.js.map +1 -0
- package/dist/esm/adapters/motion.d.ts +58 -0
- package/dist/esm/adapters/motion.js +150 -0
- package/dist/esm/adapters/motion.js.map +1 -0
- package/dist/esm/adapters/speech.js +2 -3
- package/dist/esm/adapters/speech.js.map +1 -1
- package/dist/esm/adapters/transcription.js +2 -3
- package/dist/esm/adapters/transcription.js.map +1 -1
- package/dist/esm/adapters/video.js +6 -11
- package/dist/esm/adapters/video.js.map +1 -1
- package/dist/esm/byok.js +1 -2
- package/dist/esm/client/index.js +1 -2
- package/dist/esm/image/generated/image-field-overrides.d.ts +459 -294
- package/dist/esm/image/generated/image-field-overrides.js +312 -190
- package/dist/esm/image/generated/image-field-overrides.js.map +1 -1
- package/dist/esm/image/image-inputs.js +7 -4
- package/dist/esm/image/image-inputs.js.map +1 -1
- package/dist/esm/image/image-provider-options.js +1 -2
- package/dist/esm/image/legacy-image-field-overrides.d.ts +13 -0
- package/dist/esm/image/legacy-image-field-overrides.js +91 -0
- package/dist/esm/image/legacy-image-field-overrides.js.map +1 -0
- package/dist/esm/index.d.ts +4 -1
- package/dist/esm/index.js +4 -2
- package/dist/esm/model-meta.d.ts +49 -0
- package/dist/esm/model3d/generated/mesh-field-overrides.d.ts +20 -0
- package/dist/esm/model3d/generated/mesh-field-overrides.js +20 -0
- package/dist/esm/model3d/generated/mesh-field-overrides.js.map +1 -0
- package/dist/esm/model3d/model3d-inputs.d.ts +39 -0
- package/dist/esm/model3d/model3d-inputs.js +206 -0
- package/dist/esm/model3d/model3d-inputs.js.map +1 -0
- package/dist/esm/model3d/model3d-output.d.ts +25 -0
- package/dist/esm/model3d/model3d-output.js +181 -0
- package/dist/esm/model3d/model3d-output.js.map +1 -0
- package/dist/esm/utils/billing.js +1 -2
- package/dist/esm/utils/client.d.ts +6 -0
- package/dist/esm/utils/client.js +19 -3
- package/dist/esm/utils/client.js.map +1 -1
- package/dist/esm/utils/configure.js +1 -2
- package/dist/esm/video/video-provider-options.js +20 -31
- package/dist/esm/video/video-provider-options.js.map +1 -1
- package/package.json +6 -6
- package/src/adapters/model3d.ts +219 -0
- package/src/adapters/motion.ts +237 -0
- package/src/adapters/video.ts +5 -8
- package/src/image/generated/image-field-overrides.ts +159 -110
- package/src/image/image-inputs.ts +9 -4
- package/src/image/legacy-image-field-overrides.ts +94 -0
- package/src/index.ts +19 -0
- package/src/model-meta.ts +106 -0
- package/src/model3d/generated/mesh-field-overrides.ts +46 -0
- package/src/model3d/model3d-inputs.ts +232 -0
- package/src/model3d/model3d-output.ts +216 -0
- package/src/utils/client.ts +25 -0
- package/src/video/video-provider-options.ts +9 -27
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
import { BaseMotionAdapter } from '@tanstack/ai/adapters'
|
|
2
|
+
import {
|
|
3
|
+
createAdapterFalClient,
|
|
4
|
+
extractUrlExtension,
|
|
5
|
+
falValidationMessage,
|
|
6
|
+
} from '../utils/client'
|
|
7
|
+
import { buildFalUsage, takeBillableUnits } from '../utils/billing'
|
|
8
|
+
import type {
|
|
9
|
+
MotionAsset,
|
|
10
|
+
MotionGenerationOptions,
|
|
11
|
+
MotionGenerationResult,
|
|
12
|
+
MotionJobResult,
|
|
13
|
+
MotionStatusResult,
|
|
14
|
+
} from '@tanstack/ai'
|
|
15
|
+
import type { FalModelInput } from '../model-meta'
|
|
16
|
+
import type { FalClientConfig } from '../utils/client'
|
|
17
|
+
import type { FalClient } from '../client/index'
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* fal motion models. Both Hunyuan Motion endpoints return an FBX file and
|
|
21
|
+
* take the same input. Any other fal endpoint id is accepted as a string.
|
|
22
|
+
*/
|
|
23
|
+
export type FalMotionModel =
|
|
24
|
+
| 'fal-ai/hunyuan-motion'
|
|
25
|
+
| 'fal-ai/hunyuan-motion/fast'
|
|
26
|
+
| (string & {})
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Hunyuan Motion options: `seed`, `guidance_scale` (1 to 10, default 5), and
|
|
30
|
+
* `output_format` (`'fbx'` default, or `'dict'` for raw JSON). `prompt` and
|
|
31
|
+
* `duration` are top-level `generateMotion()` options.
|
|
32
|
+
*/
|
|
33
|
+
export type FalHunyuanMotionProviderOptions = Omit<
|
|
34
|
+
FalModelInput<'fal-ai/hunyuan-motion'>,
|
|
35
|
+
'prompt' | 'duration'
|
|
36
|
+
>
|
|
37
|
+
|
|
38
|
+
/** Provider options for a fal motion model. */
|
|
39
|
+
export type FalMotionProviderOptions<TModel extends string> = TModel extends
|
|
40
|
+
| 'fal-ai/hunyuan-motion'
|
|
41
|
+
| 'fal-ai/hunyuan-motion/fast'
|
|
42
|
+
? FalHunyuanMotionProviderOptions
|
|
43
|
+
: Record<string, unknown>
|
|
44
|
+
|
|
45
|
+
interface FalQueueStatusResponse {
|
|
46
|
+
status: 'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED'
|
|
47
|
+
queue_position?: number
|
|
48
|
+
/** Set on a COMPLETED request that failed */
|
|
49
|
+
error?: string
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
interface FalFile {
|
|
53
|
+
url: string
|
|
54
|
+
content_type?: string
|
|
55
|
+
file_name?: string
|
|
56
|
+
file_size?: number
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function isFalFile(value: unknown): value is FalFile {
|
|
60
|
+
return (
|
|
61
|
+
typeof value === 'object' &&
|
|
62
|
+
value !== null &&
|
|
63
|
+
'url' in value &&
|
|
64
|
+
typeof value.url === 'string'
|
|
65
|
+
)
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Every file in a fal motion output becomes an asset. The format comes from
|
|
70
|
+
* the file name or URL extension, then from the field name
|
|
71
|
+
* (`fbx_file` → `fbx`, `motion_json` → `json`).
|
|
72
|
+
*/
|
|
73
|
+
function toMotionAssets(output: Record<string, unknown>): Array<MotionAsset> {
|
|
74
|
+
const assets: Array<MotionAsset> = []
|
|
75
|
+
for (const [field, value] of Object.entries(output)) {
|
|
76
|
+
if (!isFalFile(value)) continue
|
|
77
|
+
const extension = extractUrlExtension(value.file_name ?? value.url)
|
|
78
|
+
const format =
|
|
79
|
+
extension?.toLowerCase() ??
|
|
80
|
+
(field === 'motion_json' ? 'json' : field.replace(/_file$/, ''))
|
|
81
|
+
assets.push({
|
|
82
|
+
url: value.url,
|
|
83
|
+
format,
|
|
84
|
+
...(value.content_type ? { contentType: value.content_type } : {}),
|
|
85
|
+
...(value.file_name ? { fileName: value.file_name } : {}),
|
|
86
|
+
...(value.file_size !== undefined ? { fileSize: value.file_size } : {}),
|
|
87
|
+
})
|
|
88
|
+
}
|
|
89
|
+
return assets
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* fal motion adapter. Runs text-to-motion models on the fal queue and
|
|
94
|
+
* returns the skeletal animation files they produce.
|
|
95
|
+
*
|
|
96
|
+
* fal file URLs follow the account's media expiry setting, so copy files
|
|
97
|
+
* you want to keep.
|
|
98
|
+
*
|
|
99
|
+
* @experimental Motion generation is an experimental feature and may change.
|
|
100
|
+
*/
|
|
101
|
+
export class FalMotionAdapter<
|
|
102
|
+
TModel extends FalMotionModel,
|
|
103
|
+
> extends BaseMotionAdapter<TModel, FalMotionProviderOptions<TModel>> {
|
|
104
|
+
readonly name = 'fal' as const
|
|
105
|
+
private readonly client: FalClient
|
|
106
|
+
|
|
107
|
+
constructor(model: TModel, config?: FalClientConfig) {
|
|
108
|
+
super(model)
|
|
109
|
+
this.client = createAdapterFalClient(config)
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
async createMotionJob(
|
|
113
|
+
options: MotionGenerationOptions<FalMotionProviderOptions<TModel>>,
|
|
114
|
+
): Promise<MotionJobResult> {
|
|
115
|
+
const { logger } = options
|
|
116
|
+
logger.request(`activity=generateMotion provider=fal model=${this.model}`, {
|
|
117
|
+
provider: 'fal',
|
|
118
|
+
model: this.model,
|
|
119
|
+
})
|
|
120
|
+
try {
|
|
121
|
+
const { request_id } = await this.client.queue.submit(this.model, {
|
|
122
|
+
// The fal SDK keys input types by endpoint id; a generic TModel
|
|
123
|
+
// cannot narrow to one, so the built input is cast like falVideo does.
|
|
124
|
+
input: {
|
|
125
|
+
...options.modelOptions,
|
|
126
|
+
prompt: options.prompt,
|
|
127
|
+
...(options.duration !== undefined
|
|
128
|
+
? { duration: options.duration }
|
|
129
|
+
: {}),
|
|
130
|
+
} as FalModelInput<TModel>,
|
|
131
|
+
...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
|
|
132
|
+
})
|
|
133
|
+
return { jobId: request_id, model: this.model }
|
|
134
|
+
} catch (error) {
|
|
135
|
+
logger.errors('fal.createMotionJob fatal', {
|
|
136
|
+
error,
|
|
137
|
+
source: 'fal.createMotionJob',
|
|
138
|
+
})
|
|
139
|
+
throw error
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
async getMotionStatus(
|
|
144
|
+
jobId: string,
|
|
145
|
+
options?: { abortSignal?: AbortSignal },
|
|
146
|
+
): Promise<MotionStatusResult> {
|
|
147
|
+
const response = (await this.client.queue.status(this.model, {
|
|
148
|
+
requestId: jobId,
|
|
149
|
+
logs: false,
|
|
150
|
+
...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
|
|
151
|
+
})) as FalQueueStatusResponse
|
|
152
|
+
|
|
153
|
+
switch (response.status) {
|
|
154
|
+
case 'IN_QUEUE':
|
|
155
|
+
return {
|
|
156
|
+
jobId,
|
|
157
|
+
status: 'pending',
|
|
158
|
+
...(response.queue_position != null
|
|
159
|
+
? { queuePosition: response.queue_position }
|
|
160
|
+
: {}),
|
|
161
|
+
}
|
|
162
|
+
case 'IN_PROGRESS':
|
|
163
|
+
return { jobId, status: 'processing' }
|
|
164
|
+
case 'COMPLETED':
|
|
165
|
+
return response.error
|
|
166
|
+
? { jobId, status: 'failed', error: response.error }
|
|
167
|
+
: { jobId, status: 'completed' }
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
async getMotion(
|
|
172
|
+
jobId: string,
|
|
173
|
+
options?: { abortSignal?: AbortSignal },
|
|
174
|
+
): Promise<MotionGenerationResult> {
|
|
175
|
+
let result
|
|
176
|
+
try {
|
|
177
|
+
result = await this.client.queue.result(this.model, {
|
|
178
|
+
requestId: jobId,
|
|
179
|
+
...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
|
|
180
|
+
})
|
|
181
|
+
} catch (error) {
|
|
182
|
+
if (options?.abortSignal?.aborted) throw error
|
|
183
|
+
const validation = falValidationMessage(error)
|
|
184
|
+
if (validation) {
|
|
185
|
+
throw new Error(`Motion generation failed: ${validation}`)
|
|
186
|
+
}
|
|
187
|
+
throw error
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
const output = (result.data ?? {}) as Record<string, unknown>
|
|
191
|
+
const assets = toMotionAssets(output)
|
|
192
|
+
if (assets.length === 0) {
|
|
193
|
+
throw new Error(`fal returned no motion files for request ${jobId}`)
|
|
194
|
+
}
|
|
195
|
+
const usage = buildFalUsage(takeBillableUnits(result.requestId))
|
|
196
|
+
return {
|
|
197
|
+
jobId,
|
|
198
|
+
model: this.model,
|
|
199
|
+
assets,
|
|
200
|
+
...(typeof output.seed === 'number' ? { seed: output.seed } : {}),
|
|
201
|
+
...(usage ? { usage } : {}),
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/**
|
|
206
|
+
* Uses the fal queue cancel endpoint. fal removes a queued request. A
|
|
207
|
+
* request that already runs gets a cancel request and may still finish.
|
|
208
|
+
* fal rejects a cancel for a request that already completed.
|
|
209
|
+
*/
|
|
210
|
+
async cancelMotionJob(
|
|
211
|
+
jobId: string,
|
|
212
|
+
options?: { abortSignal?: AbortSignal },
|
|
213
|
+
): Promise<void> {
|
|
214
|
+
await this.client.queue.cancel(this.model, {
|
|
215
|
+
requestId: jobId,
|
|
216
|
+
...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
|
|
217
|
+
})
|
|
218
|
+
}
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/**
|
|
222
|
+
* Create a fal motion adapter. Reads `config.apiKey`, or `FAL_KEY` from the
|
|
223
|
+
* environment.
|
|
224
|
+
*
|
|
225
|
+
* @example
|
|
226
|
+
* ```ts
|
|
227
|
+
* const adapter = falMotion('fal-ai/hunyuan-motion')
|
|
228
|
+
* ```
|
|
229
|
+
*
|
|
230
|
+
* @experimental Motion generation is an experimental feature and may change.
|
|
231
|
+
*/
|
|
232
|
+
export function falMotion<TModel extends FalMotionModel>(
|
|
233
|
+
model: TModel,
|
|
234
|
+
config?: FalClientConfig,
|
|
235
|
+
): FalMotionAdapter<TModel> {
|
|
236
|
+
return new FalMotionAdapter(model, config)
|
|
237
|
+
}
|
package/src/adapters/video.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { resolveMediaPrompt } from '@tanstack/ai'
|
|
|
2
2
|
import { BaseVideoAdapter } from '@tanstack/ai/adapters'
|
|
3
3
|
import {
|
|
4
4
|
createAdapterFalClient,
|
|
5
|
+
falValidationMessage,
|
|
5
6
|
generateId as utilGenerateId,
|
|
6
7
|
} from '../utils/client'
|
|
7
8
|
import { buildFalUsage, takeBillableUnits } from '../utils/billing'
|
|
@@ -261,15 +262,11 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
|
|
|
261
262
|
if (options?.abortSignal?.aborted) throw error
|
|
262
263
|
// fal.ai may report COMPLETED status but throw on result fetch
|
|
263
264
|
// (e.g. 422 validation errors). Extract the detailed error info.
|
|
264
|
-
const
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
const messages = detail.map(
|
|
268
|
-
(d: { msg?: string; loc?: Array<string> }) =>
|
|
269
|
-
d.loc ? `${d.loc.join('.')}: ${d.msg}` : d.msg,
|
|
270
|
-
)
|
|
271
|
-
throw new Error(`Video generation failed: ${messages.join('; ')}`)
|
|
265
|
+
const validation = falValidationMessage(error)
|
|
266
|
+
if (validation) {
|
|
267
|
+
throw new Error(`Video generation failed: ${validation}`)
|
|
272
268
|
}
|
|
269
|
+
const err = error as { message?: string }
|
|
273
270
|
throw new Error(
|
|
274
271
|
`Failed to retrieve video result: ${err.message || String(error)}`,
|
|
275
272
|
)
|