@tanstack/ai-fal 1.1.0 → 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 (82) hide show
  1. package/dist/esm/adapters/audio.d.ts +1 -0
  2. package/dist/esm/adapters/audio.js +6 -7
  3. package/dist/esm/adapters/audio.js.map +1 -1
  4. package/dist/esm/adapters/files.d.ts +1 -0
  5. package/dist/esm/adapters/files.js +5 -6
  6. package/dist/esm/adapters/files.js.map +1 -1
  7. package/dist/esm/adapters/image.d.ts +1 -0
  8. package/dist/esm/adapters/image.js +6 -7
  9. package/dist/esm/adapters/image.js.map +1 -1
  10. package/dist/esm/adapters/live.js +1 -2
  11. package/dist/esm/adapters/model3d.d.ts +98 -0
  12. package/dist/esm/adapters/model3d.js +170 -0
  13. package/dist/esm/adapters/model3d.js.map +1 -0
  14. package/dist/esm/adapters/motion.d.ts +58 -0
  15. package/dist/esm/adapters/motion.js +150 -0
  16. package/dist/esm/adapters/motion.js.map +1 -0
  17. package/dist/esm/adapters/speech.d.ts +1 -0
  18. package/dist/esm/adapters/speech.js +6 -7
  19. package/dist/esm/adapters/speech.js.map +1 -1
  20. package/dist/esm/adapters/transcription.d.ts +1 -0
  21. package/dist/esm/adapters/transcription.js +6 -7
  22. package/dist/esm/adapters/transcription.js.map +1 -1
  23. package/dist/esm/adapters/video.d.ts +2 -1
  24. package/dist/esm/adapters/video.js +13 -18
  25. package/dist/esm/adapters/video.js.map +1 -1
  26. package/dist/esm/byok.js +1 -2
  27. package/dist/esm/client/index.d.ts +65 -0
  28. package/dist/esm/client/index.js +306 -0
  29. package/dist/esm/client/index.js.map +1 -0
  30. package/dist/esm/image/generated/image-field-overrides.d.ts +459 -294
  31. package/dist/esm/image/generated/image-field-overrides.js +312 -190
  32. package/dist/esm/image/generated/image-field-overrides.js.map +1 -1
  33. package/dist/esm/image/image-inputs.js +7 -4
  34. package/dist/esm/image/image-inputs.js.map +1 -1
  35. package/dist/esm/image/image-provider-options.js +1 -2
  36. package/dist/esm/image/legacy-image-field-overrides.d.ts +13 -0
  37. package/dist/esm/image/legacy-image-field-overrides.js +91 -0
  38. package/dist/esm/image/legacy-image-field-overrides.js.map +1 -0
  39. package/dist/esm/index.d.ts +6 -2
  40. package/dist/esm/index.js +5 -2
  41. package/dist/esm/model-meta.d.ts +49 -0
  42. package/dist/esm/model3d/generated/mesh-field-overrides.d.ts +20 -0
  43. package/dist/esm/model3d/generated/mesh-field-overrides.js +20 -0
  44. package/dist/esm/model3d/generated/mesh-field-overrides.js.map +1 -0
  45. package/dist/esm/model3d/model3d-inputs.d.ts +39 -0
  46. package/dist/esm/model3d/model3d-inputs.js +206 -0
  47. package/dist/esm/model3d/model3d-inputs.js.map +1 -0
  48. package/dist/esm/model3d/model3d-output.d.ts +25 -0
  49. package/dist/esm/model3d/model3d-output.js +181 -0
  50. package/dist/esm/model3d/model3d-output.js.map +1 -0
  51. package/dist/esm/utils/billing.js +1 -2
  52. package/dist/esm/utils/client.d.ts +16 -1
  53. package/dist/esm/utils/client.js +31 -9
  54. package/dist/esm/utils/client.js.map +1 -1
  55. package/dist/esm/utils/configure.d.ts +12 -0
  56. package/dist/esm/utils/configure.js +19 -0
  57. package/dist/esm/utils/configure.js.map +1 -0
  58. package/dist/esm/utils/index.d.ts +2 -1
  59. package/dist/esm/video/video-provider-options.js +20 -31
  60. package/dist/esm/video/video-provider-options.js.map +1 -1
  61. package/package.json +8 -7
  62. package/src/adapters/audio.ts +7 -6
  63. package/src/adapters/files.ts +5 -4
  64. package/src/adapters/image.ts +8 -7
  65. package/src/adapters/model3d.ts +219 -0
  66. package/src/adapters/motion.ts +237 -0
  67. package/src/adapters/speech.ts +7 -6
  68. package/src/adapters/transcription.ts +8 -7
  69. package/src/adapters/video.ts +16 -18
  70. package/src/client/index.ts +456 -0
  71. package/src/image/generated/image-field-overrides.ts +159 -110
  72. package/src/image/image-inputs.ts +9 -4
  73. package/src/image/legacy-image-field-overrides.ts +94 -0
  74. package/src/index.ts +20 -1
  75. package/src/model-meta.ts +106 -0
  76. package/src/model3d/generated/mesh-field-overrides.ts +46 -0
  77. package/src/model3d/model3d-inputs.ts +232 -0
  78. package/src/model3d/model3d-output.ts +216 -0
  79. package/src/utils/client.ts +37 -4
  80. package/src/utils/configure.ts +17 -0
  81. package/src/utils/index.ts +2 -1
  82. package/src/video/video-provider-options.ts +9 -27
@@ -0,0 +1,219 @@
1
+ import { BaseModel3DAdapter } from '@tanstack/ai/adapters'
2
+ import {
3
+ createAdapterFalClient,
4
+ generateId as utilGenerateId,
5
+ } from '../utils/client'
6
+ import { buildFalUsage, takeBillableUnits } from '../utils/billing'
7
+ import { ApiError, ValidationError } from '../client/index'
8
+ import { mapModel3DPromptToFalFields } from '../model3d/model3d-inputs'
9
+ import { mapFalModel3DOutput } from '../model3d/model3d-output'
10
+ import type { Model3DGenerationOptions } from '@tanstack/ai'
11
+ import type {
12
+ Fal3DModel,
13
+ Fal3DModelProviderOptions,
14
+ Fal3DPromptModalitiesFor,
15
+ } from '../model-meta'
16
+ import type { FalClientConfig } from '../utils/client'
17
+ import type { FalClient } from '../client/index'
18
+
19
+ /**
20
+ * Read the message of a failed fal request. fal puts the reason in
21
+ * `body.detail`: a string, or a list of field errors for a 422.
22
+ */
23
+ function falErrorMessage(error: unknown) {
24
+ if (error instanceof ApiError) {
25
+ const body: unknown = error.body
26
+ const detail =
27
+ typeof body === 'object' && body !== null && 'detail' in body
28
+ ? body.detail
29
+ : undefined
30
+ if (typeof detail === 'string') return detail
31
+ if (error instanceof ValidationError && error.fieldErrors.length > 0) {
32
+ return error.fieldErrors
33
+ .map(({ loc, msg }) =>
34
+ loc.length > 0 ? `${loc.join('.')}: ${msg}` : msg,
35
+ )
36
+ .join('; ')
37
+ }
38
+ }
39
+ return error instanceof Error ? error.message : String(error)
40
+ }
41
+
42
+ /**
43
+ * fal 3D model adapter. It runs any fal 3D endpoint (Hunyuan3D, TRELLIS,
44
+ * Rodin, Tripo, Meshy, SAM-3 3D, and others) as a queue job.
45
+ *
46
+ * The prompt text, image parts, and `model3d` parts go to the endpoint input
47
+ * fields. `modelOptions` is typed from the endpoint input, without those
48
+ * fields. The result has the best GLB in `url`, and every mesh file and
49
+ * texture file in `files`.
50
+ *
51
+ * @experimental 3D model generation is experimental and may change.
52
+ */
53
+ export class Fal3DModelAdapter<
54
+ TModel extends Fal3DModel,
55
+ > extends BaseModel3DAdapter<
56
+ TModel,
57
+ Fal3DModelProviderOptions<TModel>,
58
+ Record<TModel, Fal3DModelProviderOptions<TModel>>,
59
+ Record<TModel, Fal3DPromptModalitiesFor<TModel>>
60
+ > {
61
+ readonly name = 'fal' as const
62
+ // Consumes fal storage URLs uploaded via falFiles().
63
+ override readonly supportsFileSources = true
64
+ private readonly client: FalClient
65
+
66
+ constructor(model: TModel, config?: FalClientConfig) {
67
+ super({}, model)
68
+ this.client = createAdapterFalClient(config)
69
+ }
70
+
71
+ async create3DModelJob(
72
+ options: Model3DGenerationOptions<Fal3DModelProviderOptions<TModel>>,
73
+ ) {
74
+ const { modelOptions, logger } = options
75
+
76
+ logger.request(
77
+ `activity=generate3DModel provider=fal model=${this.model}`,
78
+ { provider: 'fal', model: this.model },
79
+ )
80
+
81
+ try {
82
+ // A plain string id, so the fal client takes any input object.
83
+ const endpoint: string = this.model
84
+ const promptFields = mapModel3DPromptToFalFields(
85
+ this.model,
86
+ options.prompt,
87
+ )
88
+ // Submit to the queue. Pass the abortSignal per request, not in the
89
+ // client config, so it cannot cancel other jobs.
90
+ const { request_id } = await this.client.queue.submit(endpoint, {
91
+ input: { ...modelOptions, ...promptFields },
92
+ ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
93
+ })
94
+ return { jobId: request_id, model: this.model }
95
+ } catch (error) {
96
+ logger.errors('fal.create3DModelJob fatal', {
97
+ error,
98
+ source: 'fal.create3DModelJob',
99
+ })
100
+ throw error
101
+ }
102
+ }
103
+
104
+ /**
105
+ * Reads the queue status. fal has no failed queue status: a failed job is
106
+ * `COMPLETED` with an `error` message, and this maps it to `failed`.
107
+ */
108
+ async get3DModelStatus(
109
+ jobId: string,
110
+ options?: { abortSignal?: AbortSignal },
111
+ ) {
112
+ const endpoint: string = this.model
113
+ const falStatus = await this.client.queue.status(endpoint, {
114
+ requestId: jobId,
115
+ ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
116
+ })
117
+ switch (falStatus.status) {
118
+ case 'IN_QUEUE':
119
+ return { jobId, status: 'pending' as const }
120
+ case 'IN_PROGRESS':
121
+ return { jobId, status: 'processing' as const }
122
+ case 'COMPLETED': {
123
+ const error =
124
+ 'error' in falStatus && typeof falStatus.error === 'string'
125
+ ? falStatus.error
126
+ : undefined
127
+ return error
128
+ ? { jobId, status: 'failed' as const, error }
129
+ : { jobId, status: 'completed' as const }
130
+ }
131
+ default: {
132
+ const unhandled: never = falStatus
133
+ throw new Error(
134
+ `fal: unknown queue status ${JSON.stringify(unhandled)}`,
135
+ )
136
+ }
137
+ }
138
+ }
139
+
140
+ /**
141
+ * Reads the finished job and maps it to one `Model3DResult`. A failed job
142
+ * throws an `Error` with the message from fal.
143
+ */
144
+ async get3DModel(jobId: string, options?: { abortSignal?: AbortSignal }) {
145
+ const endpoint: string = this.model
146
+ let result
147
+ try {
148
+ result = await this.client.queue.result(endpoint, {
149
+ requestId: jobId,
150
+ ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
151
+ })
152
+ } catch (error: unknown) {
153
+ // A cancelled call is not a provider failure: keep the abort error.
154
+ if (options?.abortSignal?.aborted) throw error
155
+ throw new Error(
156
+ `fal: 3D model job ${jobId} on ${this.model} failed: ${falErrorMessage(error)}`,
157
+ )
158
+ }
159
+
160
+ const usage = buildFalUsage(takeBillableUnits(result.requestId))
161
+ return {
162
+ ...mapFalModel3DOutput(jobId, result.data),
163
+ ...(usage ? { usage } : {}),
164
+ }
165
+ }
166
+
167
+ /**
168
+ * Cancels a queued job with the fal queue cancel endpoint. fal can refuse
169
+ * when the job already runs, and then this rejects.
170
+ */
171
+ async cancel3DModelJob(
172
+ jobId: string,
173
+ options?: { abortSignal?: AbortSignal },
174
+ ) {
175
+ const endpoint: string = this.model
176
+ await this.client.queue.cancel(endpoint, {
177
+ requestId: jobId,
178
+ ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
179
+ })
180
+ }
181
+
182
+ protected override generateId() {
183
+ return utilGenerateId(this.name)
184
+ }
185
+ }
186
+
187
+ /**
188
+ * Create a fal 3D model adapter. It reads the API key from `config.apiKey`,
189
+ * or from the `FAL_KEY` environment variable.
190
+ *
191
+ * @param model - A fal 3D endpoint id, for example
192
+ * `'fal-ai/hunyuan3d-v3/image-to-3d'`. Known ids autocomplete and type
193
+ * `modelOptions`. Other ids work untyped.
194
+ * @param config - Optional fal client config (API key, proxy URL, fetch).
195
+ *
196
+ * @example
197
+ * ```ts
198
+ * import { generate3DModel } from '@tanstack/ai'
199
+ * import { fal3DModel } from '@tanstack/ai-fal'
200
+ *
201
+ * const { url, format } = await generate3DModel({
202
+ * adapter: fal3DModel('fal-ai/hunyuan3d-v3/image-to-3d'),
203
+ * threadId: 'thread-1',
204
+ * prompt: [
205
+ * { type: 'image', source: { type: 'url', value: 'https://example.com/chair.png' } },
206
+ * ],
207
+ * modelOptions: { face_count: 50000 },
208
+ * wait: true,
209
+ * })
210
+ * ```
211
+ *
212
+ * @experimental 3D model generation is experimental and may change.
213
+ */
214
+ export function fal3DModel<TModel extends Fal3DModel>(
215
+ model: TModel,
216
+ config?: FalClientConfig,
217
+ ) {
218
+ return new Fal3DModelAdapter(model, config)
219
+ }
@@ -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
+ }
@@ -1,8 +1,7 @@
1
- import { fal } from '@fal-ai/client'
2
1
  import { BaseTTSAdapter } from '@tanstack/ai/adapters'
3
2
  import {
4
3
  arrayBufferToBase64,
5
- configureFalClient,
4
+ createAdapterFalClient,
6
5
  extractUrlExtension,
7
6
  generateId as utilGenerateId,
8
7
  } from '../utils/client'
@@ -10,6 +9,7 @@ import { buildFalUsage, takeBillableUnits } from '../utils/billing'
10
9
  import type { OutputType, Result } from '@fal-ai/client'
11
10
  import type { TTSOptions, TTSResult } from '@tanstack/ai'
12
11
  import type { FalClientConfig } from '../utils/client'
12
+ import type { FalClient } from '../client/index'
13
13
  import type { FalModel, FalModelInput } from '../model-meta'
14
14
 
15
15
  /**
@@ -40,10 +40,11 @@ export class FalSpeechAdapter<TModel extends FalModel> extends BaseTTSAdapter<
40
40
  FalSpeechProviderOptions<TModel>
41
41
  > {
42
42
  readonly name = 'fal' as const
43
+ private readonly client: FalClient
43
44
 
44
45
  constructor(model: TModel, config?: FalClientConfig) {
45
46
  super(model, {})
46
- configureFalClient(config)
47
+ this.client = createAdapterFalClient(config)
47
48
  }
48
49
 
49
50
  async generateSpeech(
@@ -57,8 +58,8 @@ export class FalSpeechAdapter<TModel extends FalModel> extends BaseTTSAdapter<
57
58
  let requestId: string | undefined
58
59
  try {
59
60
  const input = this.buildInput(options)
60
- // Request-specific abortSignal only — not fal.config() (global).
61
- const result = await fal.subscribe(this.model, {
61
+ // Pass the abortSignal per request, not in the client config.
62
+ const result = await this.client.subscribe(this.model, {
62
63
  input,
63
64
  ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
64
65
  onEnqueue: (id) => {
@@ -70,7 +71,7 @@ export class FalSpeechAdapter<TModel extends FalModel> extends BaseTTSAdapter<
70
71
  // The SDK stops waiting on abort but leaves the queued job running.
71
72
  // Cancel it so it stops billing.
72
73
  if (requestId && options.abortSignal?.aborted) {
73
- fal.queue.cancel(this.model, { requestId }).catch(() => {})
74
+ this.client.queue.cancel(this.model, { requestId }).catch(() => {})
74
75
  }
75
76
  logger.errors('fal.generateSpeech fatal', {
76
77
  error,
@@ -1,7 +1,6 @@
1
- import { fal } from '@fal-ai/client'
2
1
  import { BaseTranscriptionAdapter } from '@tanstack/ai/adapters'
3
2
  import {
4
- configureFalClient,
3
+ createAdapterFalClient,
5
4
  dataUrlToBlob,
6
5
  generateId as utilGenerateId,
7
6
  } from '../utils/client'
@@ -13,6 +12,7 @@ import type {
13
12
  TranscriptionSegment,
14
13
  } from '@tanstack/ai'
15
14
  import type { FalClientConfig } from '../utils/client'
15
+ import type { FalClient } from '../client/index'
16
16
  import type { FalModel, FalModelInput } from '../model-meta'
17
17
 
18
18
  /**
@@ -51,10 +51,11 @@ export class FalTranscriptionAdapter<
51
51
  FalTranscriptionProviderOptions<TModel>
52
52
  > {
53
53
  readonly name = 'fal' as const
54
+ private readonly client: FalClient
54
55
 
55
56
  constructor(model: TModel, config?: FalClientConfig) {
56
57
  super(model, {})
57
- configureFalClient(config)
58
+ this.client = createAdapterFalClient(config)
58
59
  }
59
60
 
60
61
  async transcribe(
@@ -71,8 +72,8 @@ export class FalTranscriptionAdapter<
71
72
  let requestId: string | undefined
72
73
  try {
73
74
  const input = this.buildInput(options)
74
- // Request-specific abortSignal only — not fal.config() (global).
75
- const result = await fal.subscribe(this.model, {
75
+ // Pass the abortSignal per request, not in the client config.
76
+ const result = await this.client.subscribe(this.model, {
76
77
  input,
77
78
  ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
78
79
  onEnqueue: (id) => {
@@ -84,7 +85,7 @@ export class FalTranscriptionAdapter<
84
85
  // The SDK stops waiting on abort but leaves the queued job running.
85
86
  // Cancel it so it stops billing.
86
87
  if (requestId && options.abortSignal?.aborted) {
87
- fal.queue.cancel(this.model, { requestId }).catch(() => {})
88
+ this.client.queue.cancel(this.model, { requestId }).catch(() => {})
88
89
  }
89
90
  logger.errors('fal.generateTranscription fatal', {
90
91
  error,
@@ -97,7 +98,7 @@ export class FalTranscriptionAdapter<
97
98
  private buildInput(
98
99
  options: TranscriptionOptions<FalTranscriptionProviderOptions<TModel>>,
99
100
  ): FalModelInput<TModel> {
100
- // fal-client auto-uploads Blob/File inputs via fal.storage.upload, but
101
+ // The fal client auto-uploads Blob/File inputs via storage.upload, but
101
102
  // passes strings through unchanged — so a `data:` URL would reach fal's
102
103
  // API and get rejected with a 422 "Unsupported data URL". Decode data
103
104
  // URLs to a Blob up front so the auto-upload path handles them.
@@ -1,8 +1,8 @@
1
- import { fal } from '@fal-ai/client'
2
1
  import { resolveMediaPrompt } from '@tanstack/ai'
3
2
  import { BaseVideoAdapter } from '@tanstack/ai/adapters'
4
3
  import {
5
- configureFalClient,
4
+ createAdapterFalClient,
5
+ falValidationMessage,
6
6
  generateId as utilGenerateId,
7
7
  } from '../utils/client'
8
8
  import { buildFalUsage, takeBillableUnits } from '../utils/billing'
@@ -33,6 +33,7 @@ import type {
33
33
  FalVideoProviderOptions,
34
34
  } from '../model-meta'
35
35
  import type { FalClientConfig } from '../utils/client'
36
+ import type { FalClient } from '../client/index'
36
37
 
37
38
  /**
38
39
  * Map video conditioning inputs onto fal field names.
@@ -138,12 +139,13 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
138
139
  > {
139
140
  override readonly kind = 'video' as const
140
141
  readonly name = 'fal' as const
142
+ private readonly client: FalClient
141
143
  // Consumes fal storage URLs uploaded via falFiles().
142
144
  override readonly supportsFileSources = true
143
145
 
144
146
  constructor(model: TModel, config?: FalClientConfig) {
145
147
  super({}, model)
146
- configureFalClient(config)
148
+ this.client = createAdapterFalClient(config)
147
149
  }
148
150
 
149
151
  async createVideoJob(
@@ -184,9 +186,9 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
184
186
  ...(duration !== undefined ? { duration } : {}),
185
187
  } as FalModelInput<TModel>
186
188
 
187
- // Submit to queue and get request ID. Request-specific abortSignal only —
188
- // never via fal.config() (global; would cancel concurrent jobs).
189
- const { request_id } = await fal.queue.submit(this.model, {
189
+ // Submit to the queue and get the request ID. Pass the abortSignal per
190
+ // request, not in the client config, so it cannot cancel other jobs.
191
+ const { request_id } = await this.client.queue.submit(this.model, {
190
192
  input,
191
193
  ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
192
194
  })
@@ -211,14 +213,14 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
211
213
  }
212
214
 
213
215
  /**
214
- * Cancels a queued request with `fal.queue.cancel`. fal can refuse when the
216
+ * Cancels a queued request with the fal queue cancel endpoint. fal can refuse when the
215
217
  * request already runs, and then this rejects.
216
218
  */
217
219
  async cancelVideoJob(
218
220
  jobId: string,
219
221
  options?: { abortSignal?: AbortSignal },
220
222
  ): Promise<void> {
221
- await fal.queue.cancel(this.model, {
223
+ await this.client.queue.cancel(this.model, {
222
224
  requestId: jobId,
223
225
  ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
224
226
  })
@@ -228,7 +230,7 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
228
230
  jobId: string,
229
231
  options?: { abortSignal?: AbortSignal },
230
232
  ): Promise<VideoStatusResult> {
231
- const statusResponse = (await fal.queue.status(this.model, {
233
+ const statusResponse = (await this.client.queue.status(this.model, {
232
234
  requestId: jobId,
233
235
  logs: true,
234
236
  ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
@@ -251,7 +253,7 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
251
253
  ): Promise<VideoUrlResult> {
252
254
  let result
253
255
  try {
254
- result = await fal.queue.result(this.model, {
256
+ result = await this.client.queue.result(this.model, {
255
257
  requestId: jobId,
256
258
  ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
257
259
  })
@@ -260,15 +262,11 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
260
262
  if (options?.abortSignal?.aborted) throw error
261
263
  // fal.ai may report COMPLETED status but throw on result fetch
262
264
  // (e.g. 422 validation errors). Extract the detailed error info.
263
- const err = error as { body?: { detail?: unknown }; message?: string }
264
- const detail = err.body?.detail
265
- if (Array.isArray(detail)) {
266
- const messages = detail.map(
267
- (d: { msg?: string; loc?: Array<string> }) =>
268
- d.loc ? `${d.loc.join('.')}: ${d.msg}` : d.msg,
269
- )
270
- throw new Error(`Video generation failed: ${messages.join('; ')}`)
265
+ const validation = falValidationMessage(error)
266
+ if (validation) {
267
+ throw new Error(`Video generation failed: ${validation}`)
271
268
  }
269
+ const err = error as { message?: string }
272
270
  throw new Error(
273
271
  `Failed to retrieve video result: ${err.message || String(error)}`,
274
272
  )