@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.
Files changed (62) hide show
  1. package/dist/esm/adapters/audio.js +2 -3
  2. package/dist/esm/adapters/audio.js.map +1 -1
  3. package/dist/esm/adapters/files.js +1 -2
  4. package/dist/esm/adapters/image.js +2 -3
  5. package/dist/esm/adapters/image.js.map +1 -1
  6. package/dist/esm/adapters/live.js +1 -2
  7. package/dist/esm/adapters/model3d.d.ts +98 -0
  8. package/dist/esm/adapters/model3d.js +170 -0
  9. package/dist/esm/adapters/model3d.js.map +1 -0
  10. package/dist/esm/adapters/motion.d.ts +58 -0
  11. package/dist/esm/adapters/motion.js +150 -0
  12. package/dist/esm/adapters/motion.js.map +1 -0
  13. package/dist/esm/adapters/speech.js +2 -3
  14. package/dist/esm/adapters/speech.js.map +1 -1
  15. package/dist/esm/adapters/transcription.js +2 -3
  16. package/dist/esm/adapters/transcription.js.map +1 -1
  17. package/dist/esm/adapters/video.js +6 -11
  18. package/dist/esm/adapters/video.js.map +1 -1
  19. package/dist/esm/byok.js +1 -2
  20. package/dist/esm/client/index.js +1 -2
  21. package/dist/esm/image/generated/image-field-overrides.d.ts +459 -294
  22. package/dist/esm/image/generated/image-field-overrides.js +312 -190
  23. package/dist/esm/image/generated/image-field-overrides.js.map +1 -1
  24. package/dist/esm/image/image-inputs.js +7 -4
  25. package/dist/esm/image/image-inputs.js.map +1 -1
  26. package/dist/esm/image/image-provider-options.js +1 -2
  27. package/dist/esm/image/legacy-image-field-overrides.d.ts +13 -0
  28. package/dist/esm/image/legacy-image-field-overrides.js +91 -0
  29. package/dist/esm/image/legacy-image-field-overrides.js.map +1 -0
  30. package/dist/esm/index.d.ts +4 -1
  31. package/dist/esm/index.js +4 -2
  32. package/dist/esm/model-meta.d.ts +49 -0
  33. package/dist/esm/model3d/generated/mesh-field-overrides.d.ts +20 -0
  34. package/dist/esm/model3d/generated/mesh-field-overrides.js +20 -0
  35. package/dist/esm/model3d/generated/mesh-field-overrides.js.map +1 -0
  36. package/dist/esm/model3d/model3d-inputs.d.ts +39 -0
  37. package/dist/esm/model3d/model3d-inputs.js +206 -0
  38. package/dist/esm/model3d/model3d-inputs.js.map +1 -0
  39. package/dist/esm/model3d/model3d-output.d.ts +25 -0
  40. package/dist/esm/model3d/model3d-output.js +181 -0
  41. package/dist/esm/model3d/model3d-output.js.map +1 -0
  42. package/dist/esm/utils/billing.js +1 -2
  43. package/dist/esm/utils/client.d.ts +6 -0
  44. package/dist/esm/utils/client.js +19 -3
  45. package/dist/esm/utils/client.js.map +1 -1
  46. package/dist/esm/utils/configure.js +1 -2
  47. package/dist/esm/video/video-provider-options.js +20 -31
  48. package/dist/esm/video/video-provider-options.js.map +1 -1
  49. package/package.json +6 -6
  50. package/src/adapters/model3d.ts +219 -0
  51. package/src/adapters/motion.ts +237 -0
  52. package/src/adapters/video.ts +5 -8
  53. package/src/image/generated/image-field-overrides.ts +159 -110
  54. package/src/image/image-inputs.ts +9 -4
  55. package/src/image/legacy-image-field-overrides.ts +94 -0
  56. package/src/index.ts +19 -0
  57. package/src/model-meta.ts +106 -0
  58. package/src/model3d/generated/mesh-field-overrides.ts +46 -0
  59. package/src/model3d/model3d-inputs.ts +232 -0
  60. package/src/model3d/model3d-output.ts +216 -0
  61. package/src/utils/client.ts +25 -0
  62. 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
+ }
@@ -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 err = error as { body?: { detail?: unknown }; message?: string }
265
- const detail = err.body?.detail
266
- if (Array.isArray(detail)) {
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
  )