@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
package/src/index.ts CHANGED
@@ -10,6 +10,23 @@ export { FalImageAdapter, falImage } from './adapters/image'
10
10
 
11
11
  export { FalVideoAdapter, falVideo } from './adapters/video'
12
12
 
13
+ // ============================================================================
14
+ // Motion Adapter (Experimental)
15
+ // ============================================================================
16
+
17
+ export { FalMotionAdapter, falMotion } from './adapters/motion'
18
+ export type {
19
+ FalMotionModel,
20
+ FalMotionProviderOptions,
21
+ FalHunyuanMotionProviderOptions,
22
+ } from './adapters/motion'
23
+
24
+ // ============================================================================
25
+ // 3D Model Adapter (Experimental)
26
+ // ============================================================================
27
+
28
+ export { Fal3DModelAdapter, fal3DModel } from './adapters/model3d'
29
+
13
30
  // ============================================================================
14
31
  // Live Adapter (Experimental)
15
32
  // ============================================================================
@@ -76,6 +93,8 @@ export {
76
93
  type FalModelImageSize,
77
94
  type FalModelVideoSize,
78
95
  type FalModelVideoDuration,
96
+ type Fal3DModel,
97
+ type Fal3DModelProviderOptions,
79
98
  } from './model-meta'
80
99
  // ============================================================================
81
100
  // Utils
package/src/model-meta.ts CHANGED
@@ -6,6 +6,10 @@
6
6
  import type { EndpointTypeMap } from '@fal-ai/client/endpoints'
7
7
  import type { MediaPromptModality } from '@tanstack/ai'
8
8
  import type { FalImageFieldName } from './image/generated/image-field-overrides'
9
+ import type {
10
+ FAL_MESH_FIELD_MAP,
11
+ FalMeshFieldName,
12
+ } from './model3d/generated/mesh-field-overrides'
9
13
 
10
14
  export type { EndpointTypeMap } from '@fal-ai/client/endpoints'
11
15
 
@@ -251,3 +255,105 @@ export type FalAudioProviderOptions<TModel extends string> = Omit<
251
255
  FalModelInput<TModel>,
252
256
  'prompt'
253
257
  >
258
+
259
+ /**
260
+ * The fal 3D endpoints that `fal3DModel()` knows. Each id is a key of the
261
+ * installed SDK's `EndpointTypeMap`, and each endpoint returns a mesh file.
262
+ *
263
+ * @experimental 3D model generation is experimental and may change.
264
+ */
265
+ export type Fal3DKnownModel =
266
+ | 'fal-ai/hunyuan3d/v2'
267
+ | 'fal-ai/hunyuan3d/v2/turbo'
268
+ | 'fal-ai/hunyuan3d/v2/mini'
269
+ | 'fal-ai/hunyuan3d/v2/mini/turbo'
270
+ | 'fal-ai/hunyuan3d/v2/multi-view'
271
+ | 'fal-ai/hunyuan3d/v2/multi-view/turbo'
272
+ | 'fal-ai/hunyuan3d-v3/image-to-3d'
273
+ | 'fal-ai/hunyuan3d-v3/text-to-3d'
274
+ | 'fal-ai/hunyuan-3d/v3.1/pro/image-to-3d'
275
+ | 'fal-ai/hunyuan-3d/v3.1/pro/text-to-3d'
276
+ | 'fal-ai/hunyuan-3d/v3.1/rapid/image-to-3d'
277
+ | 'fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d'
278
+ | 'fal-ai/hyper3d/rodin'
279
+ | 'fal-ai/hyper3d/rodin/v2'
280
+ | 'fal-ai/meshy/v6/image-to-3d'
281
+ | 'fal-ai/meshy/v6/text-to-3d'
282
+ | 'fal-ai/meshy/v6-preview/text-to-3d'
283
+ | 'meshy/v7.1/image-to-3d'
284
+ | 'meshy/v7.1/multi-image-to-3d'
285
+ | 'meshy/v7.1/text-to-3d'
286
+ | 'meshy/v7/retexture'
287
+ | 'fal-ai/trellis'
288
+ | 'fal-ai/trellis/multi'
289
+ | 'fal-ai/trellis-2'
290
+ | 'fal-ai/trellis-2/retexture'
291
+ | 'tripo3d/tripo/v2.5/image-to-3d'
292
+ | 'tripo3d/tripo/v2.5/multiview-to-3d'
293
+ | 'tripo3d/tripo/remesh'
294
+ | 'fal-ai/sam-3/3d-objects'
295
+ | 'fal-ai/sam-3/3d-body'
296
+
297
+ /**
298
+ * A fal 3D endpoint id. The known ids autocomplete. Any other string also
299
+ * works, without typed options, so a new fal endpoint is usable at once.
300
+ *
301
+ * @experimental 3D model generation is experimental and may change.
302
+ */
303
+ export type Fal3DModel = Fal3DKnownModel | (string & {})
304
+
305
+ /**
306
+ * Input fields that take the text of a 3D prompt: `prompt`, or
307
+ * `text_style_prompt` for Meshy retexture.
308
+ */
309
+ export type Fal3DTextFieldName = 'prompt' | 'text_style_prompt'
310
+
311
+ /**
312
+ * Input fields that take the image parts of a 3D prompt: the fields of the
313
+ * generated image field map, and `image_style_url` for Meshy retexture.
314
+ */
315
+ export type Fal3DImageFieldName = FalImageFieldName | 'image_style_url'
316
+
317
+ /** Input fields that the 3D adapter fills from the prompt. */
318
+ type Fal3DPromptFieldName =
319
+ | Fal3DTextFieldName
320
+ | Fal3DImageFieldName
321
+ | FalMeshFieldName
322
+
323
+ /**
324
+ * Provider options for 3D model generation: the endpoint input without the
325
+ * fields that the adapter fills from the prompt (the text field, the image
326
+ * fields, and the mesh field). Endpoints that the installed SDK does not know
327
+ * take any options.
328
+ *
329
+ * @example
330
+ * type Options = Fal3DModelProviderOptions<'fal-ai/hunyuan3d-v3/image-to-3d'>
331
+ * // { face_count?: number; generate_type?: 'Normal' | 'LowPoly' | 'Geometry'; ... }
332
+ *
333
+ * @experimental 3D model generation is experimental and may change.
334
+ */
335
+ export type Fal3DModelProviderOptions<TModel extends string> =
336
+ TModel extends keyof EndpointTypeMap
337
+ ? Omit<FalModelInput<TModel>, Fal3DPromptFieldName>
338
+ : Record<string, unknown>
339
+
340
+ /**
341
+ * Prompt input modalities for a fal 3D endpoint. An endpoint takes image
342
+ * parts when its input has one of the {@link Fal3DImageFieldName} fields. It
343
+ * takes a `model3d` part when the generated mesh field map lists it.
344
+ * Endpoints that the installed SDK does not know are unconstrained.
345
+ *
346
+ * @experimental 3D model generation is experimental and may change.
347
+ */
348
+ export type Fal3DPromptModalitiesFor<TModel extends string> =
349
+ TModel extends keyof EndpointTypeMap
350
+ ? ReadonlyArray<
351
+ | (Extract<
352
+ keyof FalModelInput<TModel>,
353
+ Fal3DImageFieldName
354
+ > extends never
355
+ ? never
356
+ : 'image')
357
+ | (TModel extends keyof typeof FAL_MESH_FIELD_MAP ? 'model3d' : never)
358
+ >
359
+ : ReadonlyArray<MediaPromptModality>
@@ -0,0 +1,46 @@
1
+ /* eslint-disable */
2
+ // ---------------------------------------------------------------------------
3
+ // AUTO-GENERATED. Do not edit by hand.
4
+ //
5
+ // Generated from @fal-ai/client@1.11.0 EndpointTypeMap by
6
+ // scripts/generate-fal-image-field-map.ts. Regenerate after bumping
7
+ // @fal-ai/client:
8
+ //
9
+ // pnpm tsx scripts/generate-fal-image-field-map.ts
10
+ //
11
+ // Maps every fal 3D endpoint that takes an existing mesh to the input field
12
+ // for that mesh. Endpoints with no mesh input are not listed. The
13
+ // `satisfies` clause below checks every field name against the SDK's
14
+ // endpoint input types at compile time (type-only import, so nothing from
15
+ // endpoints.d.ts ships at runtime).
16
+ // ---------------------------------------------------------------------------
17
+ import type { EndpointTypeMap } from '@fal-ai/client/endpoints'
18
+
19
+ /** sha256 of the endpoints.d.ts this file was generated from. */
20
+ export const FAL_MESH_ENDPOINTS_DTS_SHA256 =
21
+ 'be36a2f9a11b0c7d011036915e1615f80e60bfc341ec6b770e897770c63cb511'
22
+
23
+ /** Every input field name that fal 3D endpoints use for an input mesh. */
24
+ export type FalMeshFieldName = 'model_url' | 'mesh_url' | 'input_file_url'
25
+
26
+ /** fal endpoint id -> the input field that takes the mesh. */
27
+ export const FAL_MESH_FIELD_MAP = {
28
+ 'fal-ai/hunyuan-3d/v3.1/part': 'input_file_url',
29
+ 'fal-ai/hunyuan-3d/v3.1/smart-topology': 'input_file_url',
30
+ 'fal-ai/meshy/rigging': 'model_url',
31
+ 'fal-ai/meshy/rigging/multi-animation': 'model_url',
32
+ 'fal-ai/trellis-2/retexture': 'mesh_url',
33
+ 'hitem3d/hi3d/multicolor': 'mesh_url',
34
+ 'hitem3d/hi3d/split': 'mesh_url',
35
+ 'hitem3d/hi3d/texture': 'mesh_url',
36
+ 'meshy/v6-lite/retexture': 'model_url',
37
+ 'meshy/v6/retexture': 'model_url',
38
+ 'meshy/v7/retexture': 'model_url',
39
+ 'tripo3d/tripo/remesh': 'mesh_url',
40
+ 'tripo3d/tripo/segment': 'mesh_url',
41
+ } as const satisfies {
42
+ [K in keyof EndpointTypeMap]?: Extract<
43
+ keyof EndpointTypeMap[K]['input'],
44
+ FalMeshFieldName
45
+ >
46
+ }
@@ -0,0 +1,232 @@
1
+ import { resolveMediaPrompt } from '@tanstack/ai'
2
+ import {
3
+ contentSourceToFalUrl,
4
+ mapImageInputsToFalFields,
5
+ } from '../image/image-inputs'
6
+ import { FAL_MESH_FIELD_MAP } from './generated/mesh-field-overrides'
7
+ import type { FalImageFieldName } from '../image/generated/image-field-overrides'
8
+ import type {
9
+ ImagePart,
10
+ MediaInputMetadata,
11
+ MediaPrompt,
12
+ Model3DPart,
13
+ } from '@tanstack/ai'
14
+ import type { EndpointTypeMap } from '@fal-ai/client/endpoints'
15
+ import type { FalMeshFieldName } from './generated/mesh-field-overrides'
16
+ import type {
17
+ Fal3DKnownModel,
18
+ Fal3DModel,
19
+ Fal3DTextFieldName,
20
+ } from '../model-meta'
21
+
22
+ /**
23
+ * How a known 3D endpoint takes the text and image parts of a prompt.
24
+ *
25
+ * - `text`: the input field for the prompt text, or `null` when the endpoint
26
+ * takes no text.
27
+ * - `image`: the image fields of the endpoint. The generated image field map
28
+ * routes the image parts, and a part that lands on another field throws.
29
+ * `'image_style_url'` for Meshy retexture (one style image), or `null`
30
+ * when the endpoint takes no image parts (for example multi-view
31
+ * endpoints, which take their views through `modelOptions`).
32
+ */
33
+ type Fal3DPromptFields<TInput> = {
34
+ text: Extract<keyof TInput, Fal3DTextFieldName> extends never
35
+ ? null
36
+ : Extract<keyof TInput, Fal3DTextFieldName>
37
+ image: Extract<keyof TInput, FalImageFieldName> extends never
38
+ ? Extract<keyof TInput, 'image_style_url'> extends never
39
+ ? null
40
+ : 'image_style_url'
41
+ : ReadonlyArray<Extract<keyof TInput, FalImageFieldName>>
42
+ }
43
+
44
+ type Fal3DImageRouting =
45
+ | ReadonlyArray<FalImageFieldName>
46
+ | 'image_style_url'
47
+ | null
48
+
49
+ /**
50
+ * The prompt fields of every known 3D endpoint. The `satisfies` clause checks
51
+ * each entry against the endpoint input type of the installed SDK, so a wrong
52
+ * or missing entry is a compile error.
53
+ */
54
+ const FAL_3D_PROMPT_FIELDS = {
55
+ 'fal-ai/hunyuan3d/v2': { text: null, image: ['input_image_url'] },
56
+ 'fal-ai/hunyuan3d/v2/turbo': { text: null, image: ['input_image_url'] },
57
+ 'fal-ai/hunyuan3d/v2/mini': { text: null, image: ['input_image_url'] },
58
+ 'fal-ai/hunyuan3d/v2/mini/turbo': { text: null, image: ['input_image_url'] },
59
+ 'fal-ai/hunyuan3d/v2/multi-view': { text: null, image: null },
60
+ 'fal-ai/hunyuan3d/v2/multi-view/turbo': { text: null, image: null },
61
+ 'fal-ai/hunyuan3d-v3/image-to-3d': { text: null, image: ['input_image_url'] },
62
+ 'fal-ai/hunyuan3d-v3/text-to-3d': { text: 'prompt', image: null },
63
+ 'fal-ai/hunyuan-3d/v3.1/pro/image-to-3d': {
64
+ text: null,
65
+ image: ['input_image_url'],
66
+ },
67
+ 'fal-ai/hunyuan-3d/v3.1/pro/text-to-3d': { text: 'prompt', image: null },
68
+ 'fal-ai/hunyuan-3d/v3.1/rapid/image-to-3d': {
69
+ text: null,
70
+ image: ['input_image_url'],
71
+ },
72
+ 'fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d': { text: 'prompt', image: null },
73
+ 'fal-ai/hyper3d/rodin': { text: 'prompt', image: ['input_image_urls'] },
74
+ 'fal-ai/hyper3d/rodin/v2': { text: 'prompt', image: ['input_image_urls'] },
75
+ 'fal-ai/meshy/v6/image-to-3d': { text: null, image: ['image_url'] },
76
+ 'fal-ai/meshy/v6/text-to-3d': { text: 'prompt', image: null },
77
+ 'fal-ai/meshy/v6-preview/text-to-3d': { text: 'prompt', image: null },
78
+ 'meshy/v7.1/image-to-3d': { text: null, image: ['image_url'] },
79
+ 'meshy/v7.1/multi-image-to-3d': { text: null, image: ['image_urls'] },
80
+ 'meshy/v7.1/text-to-3d': { text: 'prompt', image: null },
81
+ 'meshy/v7/retexture': {
82
+ text: 'text_style_prompt',
83
+ image: 'image_style_url',
84
+ },
85
+ 'fal-ai/trellis': { text: null, image: ['image_url'] },
86
+ 'fal-ai/trellis/multi': { text: null, image: ['image_urls'] },
87
+ 'fal-ai/trellis-2': { text: null, image: ['image_url'] },
88
+ 'fal-ai/trellis-2/retexture': { text: null, image: ['image_url'] },
89
+ 'tripo3d/tripo/v2.5/image-to-3d': { text: null, image: ['image_url'] },
90
+ 'tripo3d/tripo/v2.5/multiview-to-3d': { text: null, image: null },
91
+ 'tripo3d/tripo/remesh': { text: null, image: null },
92
+ 'fal-ai/sam-3/3d-objects': { text: 'prompt', image: ['image_url'] },
93
+ 'fal-ai/sam-3/3d-body': { text: null, image: ['image_url', 'mask_url'] },
94
+ } as const satisfies {
95
+ [K in Fal3DKnownModel]: Fal3DPromptFields<EndpointTypeMap[K]['input']>
96
+ }
97
+
98
+ /** The same tables, readable with any endpoint id. */
99
+ const PROMPT_FIELDS_BY_ENDPOINT: Partial<
100
+ Record<
101
+ string,
102
+ {
103
+ text: Fal3DTextFieldName | null
104
+ image: Fal3DImageRouting
105
+ }
106
+ >
107
+ > = FAL_3D_PROMPT_FIELDS
108
+ const MESH_FIELD_BY_ENDPOINT: Partial<Record<string, FalMeshFieldName>> =
109
+ FAL_MESH_FIELD_MAP
110
+
111
+ /**
112
+ * The shared image mapper sends each part to the field of its role (for
113
+ * example a second source image to `image_urls`, and a `reference` image to
114
+ * `reference_image_urls`). A known endpoint ignores a field that it does not
115
+ * have, so reject that case before submit.
116
+ */
117
+ function rejectUnknownImageFields(
118
+ model: string,
119
+ fields: Record<string, unknown>,
120
+ allowed: ReadonlyArray<string>,
121
+ ) {
122
+ const unknown = Object.keys(fields).filter(
123
+ (field) => !allowed.includes(field),
124
+ )
125
+ if (unknown.length === 0) return
126
+ const list = (names: ReadonlyArray<string>) =>
127
+ names.map((name) => `'${name}'`).join(', ')
128
+ throw new Error(
129
+ `fal: model ${model} takes images only in ${list(allowed)}, not in ${list(unknown)}. Send one source image, or check the metadata.role of each image.`,
130
+ )
131
+ }
132
+
133
+ function mapTextToFalField(model: string, text: string) {
134
+ if (!text) return {}
135
+ const known = PROMPT_FIELDS_BY_ENDPOINT[model]
136
+ // An endpoint that the table does not know gets the common `prompt` field.
137
+ if (!known) return { prompt: text }
138
+ if (known.text === null) {
139
+ throw new Error(
140
+ `fal: model ${model} takes no text prompt. Remove the text from the prompt, or use an endpoint that takes text.`,
141
+ )
142
+ }
143
+ return { [known.text]: text }
144
+ }
145
+
146
+ function mapImagesToFalFields(
147
+ model: string,
148
+ images: ReadonlyArray<ImagePart<MediaInputMetadata>>,
149
+ ) {
150
+ if (images.length === 0) return {}
151
+ const known = PROMPT_FIELDS_BY_ENDPOINT[model]
152
+ // An endpoint that the table does not know uses the generated image map.
153
+ if (!known) return mapImageInputsToFalFields(model, images)
154
+ const imageRouting = known.image
155
+ if (imageRouting === null) {
156
+ throw new Error(
157
+ `fal: model ${model} takes no image prompt parts. Pass its image fields through modelOptions.`,
158
+ )
159
+ }
160
+ if (imageRouting === 'image_style_url') {
161
+ const [image, ...rest] = images
162
+ if (!image || rest.length > 0) {
163
+ throw new Error(
164
+ `fal: model ${model} takes one style image (received ${images.length}).`,
165
+ )
166
+ }
167
+ return { image_style_url: contentSourceToFalUrl(image.source) }
168
+ }
169
+ const fields = mapImageInputsToFalFields(model, images)
170
+ rejectUnknownImageFields(model, fields, imageRouting)
171
+ return fields
172
+ }
173
+
174
+ function mapMeshToFalField(model: string, meshes: ReadonlyArray<Model3DPart>) {
175
+ if (meshes.length === 0) return {}
176
+ const [mesh, ...rest] = meshes
177
+ if (!mesh || rest.length > 0) {
178
+ throw new Error(
179
+ `fal: model ${model} takes one model3d prompt part (received ${meshes.length}).`,
180
+ )
181
+ }
182
+ const meshField = MESH_FIELD_BY_ENDPOINT[model]
183
+ if (!meshField) {
184
+ throw new Error(
185
+ `fal: model ${model} takes no model3d prompt part. Use an endpoint that takes a mesh, or pass the mesh field through modelOptions.`,
186
+ )
187
+ }
188
+ return { [meshField]: contentSourceToFalUrl(mesh.source) }
189
+ }
190
+
191
+ /**
192
+ * Map a 3D prompt onto the input fields of a fal 3D endpoint.
193
+ *
194
+ * - Text goes to the `prompt` field (`text_style_prompt` for Meshy
195
+ * retexture). It throws when the endpoint is known and takes no
196
+ * text, so the text is never dropped without a warning. An endpoint that
197
+ * is not known gets `prompt`.
198
+ * - Image parts go through the generated image field map (for example
199
+ * `input_image_url` for Hunyuan3D v3, `image_urls` for TRELLIS multi).
200
+ * Meshy retexture takes one image in `image_style_url`. It throws when the endpoint is known and takes no image parts.
201
+ * - One `model3d` part goes to the mesh field from the generated mesh field
202
+ * map (`model_url`, `mesh_url`, or `input_file_url`). It throws for a second
203
+ * mesh, and for an endpoint that has no mesh field.
204
+ * - Video and audio parts throw, because no fal 3D endpoint takes them.
205
+ *
206
+ * Every image and mesh source goes through `contentSourceToFalUrl`, so URL,
207
+ * `data:`, and fal file sources all work.
208
+ *
209
+ * @example
210
+ * mapModel3DPromptToFalFields('fal-ai/trellis-2/retexture', [
211
+ * { type: 'model3d', source: { type: 'url', value: 'https://x/chair.glb' } },
212
+ * ])
213
+ * // { mesh_url: 'https://x/chair.glb' }
214
+ */
215
+ export function mapModel3DPromptToFalFields(
216
+ model: Fal3DModel,
217
+ prompt: MediaPrompt,
218
+ ) {
219
+ const resolved = resolveMediaPrompt(prompt)
220
+ const hasUnsupportedParts =
221
+ resolved.videos.length > 0 || resolved.audios.length > 0
222
+ if (hasUnsupportedParts) {
223
+ throw new Error(
224
+ `fal: model ${model} takes text, image, and model3d prompt parts only. Remove the video and audio parts.`,
225
+ )
226
+ }
227
+ return {
228
+ ...mapTextToFalField(model, resolved.text),
229
+ ...mapImagesToFalFields(model, resolved.images),
230
+ ...mapMeshToFalField(model, resolved.models3d),
231
+ }
232
+ }
@@ -0,0 +1,216 @@
1
+ import { extractUrlExtension } from '../utils/client'
2
+ import type { Model3DFile, Model3DFileRole, Model3DFormat } from '@tanstack/ai'
3
+
4
+ /** The fields of a fal `File` that the mapper reads. */
5
+ interface FalFileLike {
6
+ url: string
7
+ content_type?: unknown
8
+ file_name?: unknown
9
+ }
10
+
11
+ const FORMAT_BY_EXTENSION: Partial<Record<string, Model3DFormat>> = {
12
+ glb: 'glb',
13
+ gltf: 'gltf',
14
+ fbx: 'fbx',
15
+ obj: 'obj',
16
+ usdz: 'usdz',
17
+ stl: 'stl',
18
+ }
19
+
20
+ const FORMAT_BY_CONTENT_TYPE: Partial<Record<string, Model3DFormat>> = {
21
+ 'model/gltf-binary': 'glb',
22
+ 'model/gltf+json': 'gltf',
23
+ 'model/obj': 'obj',
24
+ 'model/stl': 'stl',
25
+ 'application/sla': 'stl',
26
+ 'model/vnd.usdz+zip': 'usdz',
27
+ }
28
+
29
+ /**
30
+ * The `model_urls` keys in the order the mapper prefers them when there is
31
+ * no GLB. FBX keeps materials and rigs, so it comes before OBJ.
32
+ */
33
+ const MODEL_URL_FORMATS = ['glb', 'gltf', 'fbx', 'usdz', 'obj', 'stl'] as const
34
+
35
+ /**
36
+ * Output fields that hold one mesh file, in the order the mapper prefers
37
+ * them for the main `url`. Then come `model_urls`, rigged and animated
38
+ * meshes, and mesh parts (see {@link collectMeshFiles}).
39
+ */
40
+ const PBR_FIELDS = ['pbr_model', 'model_glb_pbr'] as const
41
+ const BASE_FIELDS = ['model_mesh', 'base_model'] as const
42
+ const RIGGED_FIELDS = ['rigged_character_glb', 'rigged_character_fbx'] as const
43
+ const ANIMATION_FIELDS = ['animation_glb', 'animation_fbx'] as const
44
+ const PART_LIST_FIELDS = ['result_files', 'individual_glbs', 'meshes'] as const
45
+ const PREVIEW_FIELDS = ['rendered_image', 'thumbnail'] as const
46
+ const TEXTURE_FIELDS = ['texture', 'material_mtl'] as const
47
+
48
+ function isRecord(value: unknown): value is Record<string, unknown> {
49
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
50
+ }
51
+
52
+ function isFalFile(value: unknown): value is FalFileLike {
53
+ return isRecord(value) && typeof value.url === 'string'
54
+ }
55
+
56
+ function fileNameExtension(fileName: unknown) {
57
+ if (typeof fileName !== 'string' || !fileName.includes('.')) return undefined
58
+ return fileName.split('.').pop()
59
+ }
60
+
61
+ /**
62
+ * Find the format of a fal file from its file name, then its URL extension,
63
+ * then its content type. Returns `undefined` when the file is not a mesh
64
+ * format that `Model3DFormat` names (for example a PNG texture).
65
+ */
66
+ function detectFormat(file: FalFileLike) {
67
+ const extension =
68
+ fileNameExtension(file.file_name) ?? extractUrlExtension(file.url)
69
+ const byExtension = extension
70
+ ? FORMAT_BY_EXTENSION[extension.toLowerCase()]
71
+ : undefined
72
+ if (byExtension) return byExtension
73
+ if (typeof file.content_type !== 'string') return undefined
74
+ const mimeType = file.content_type.split(';')[0]?.trim().toLowerCase()
75
+ return mimeType ? FORMAT_BY_CONTENT_TYPE[mimeType] : undefined
76
+ }
77
+
78
+ /** A mesh file. Unlike a texture, a mesh always has a format. */
79
+ type Model3DMeshFile = Model3DFile & { format: Model3DFormat }
80
+
81
+ function contentTypeField(file: FalFileLike) {
82
+ return typeof file.content_type === 'string'
83
+ ? { contentType: file.content_type }
84
+ : {}
85
+ }
86
+
87
+ function toMeshFile(
88
+ value: unknown,
89
+ role: Model3DFileRole,
90
+ knownFormat?: Model3DFormat,
91
+ ) {
92
+ if (!isFalFile(value)) return undefined
93
+ const format = detectFormat(value) ?? knownFormat
94
+ if (!format) return undefined
95
+ const file: Model3DMeshFile = {
96
+ url: value.url,
97
+ format,
98
+ role,
99
+ ...contentTypeField(value),
100
+ }
101
+ return file
102
+ }
103
+
104
+ /**
105
+ * Read every mesh file from a fal 3D output, in the order the mapper prefers
106
+ * them, without two files that share a URL. Files that are not a
107
+ * `Model3DFormat` (textures, MTL files, Gaussian splats) are left out.
108
+ */
109
+ function collectMeshFiles(output: Record<string, unknown>) {
110
+ const files: Array<Model3DMeshFile> = []
111
+ const add = (
112
+ value: unknown,
113
+ role: Model3DFileRole,
114
+ knownFormat?: Model3DFormat,
115
+ ) => {
116
+ const file = toMeshFile(value, role, knownFormat)
117
+ const isNewFile = file && !files.some((seen) => seen.url === file.url)
118
+ if (file && isNewFile) files.push(file)
119
+ }
120
+
121
+ for (const field of PBR_FIELDS) add(output[field], 'pbr')
122
+ add(output.model_glb, 'base', 'glb')
123
+ const modelUrls = isRecord(output.model_urls) ? output.model_urls : {}
124
+ for (const format of MODEL_URL_FORMATS) add(modelUrls[format], 'base', format)
125
+ for (const field of BASE_FIELDS) add(output[field], 'base')
126
+ for (const field of RIGGED_FIELDS) add(output[field], 'rigged')
127
+ for (const field of ANIMATION_FIELDS) add(output[field], 'animation')
128
+ const basicAnimations = isRecord(output.basic_animations)
129
+ ? Object.values(output.basic_animations)
130
+ : []
131
+ for (const animation of basicAnimations) add(animation, 'animation')
132
+ for (const field of PART_LIST_FIELDS) {
133
+ const parts = output[field]
134
+ if (!Array.isArray(parts)) continue
135
+ for (const part of parts) add(part, 'part')
136
+ }
137
+ return files
138
+ }
139
+
140
+ /**
141
+ * Read the texture files of a fal 3D output: the `textures` images (Rodin),
142
+ * the `base_color`, `metallic`, `normal`, and `roughness` files of each
143
+ * `texture_urls` entry (Meshy), and the `texture` and `material_mtl` files
144
+ * (Hunyuan3D rapid). They have the role `'texture'` and no `format`.
145
+ */
146
+ function collectTextureFiles(output: Record<string, unknown>) {
147
+ const values: Array<unknown> = []
148
+ if (Array.isArray(output.textures)) values.push(...output.textures)
149
+ const textureSets = Array.isArray(output.texture_urls)
150
+ ? output.texture_urls
151
+ : []
152
+ for (const textureSet of textureSets) {
153
+ if (isRecord(textureSet)) values.push(...Object.values(textureSet))
154
+ }
155
+ for (const field of TEXTURE_FIELDS) values.push(output[field])
156
+
157
+ const files: Array<Model3DFile> = []
158
+ for (const value of values) {
159
+ if (!isFalFile(value)) continue
160
+ files.push({ url: value.url, role: 'texture', ...contentTypeField(value) })
161
+ }
162
+ return files
163
+ }
164
+
165
+ /** The first GLB in the list, else the first file. */
166
+ function pickMainFile(files: ReadonlyArray<Model3DMeshFile>) {
167
+ return files.find((file) => file.format === 'glb') ?? files[0]
168
+ }
169
+
170
+ function findPreviewUrl(output: Record<string, unknown>) {
171
+ for (const field of PREVIEW_FIELDS) {
172
+ const preview = output[field]
173
+ if (isFalFile(preview)) return preview.url
174
+ }
175
+ return undefined
176
+ }
177
+
178
+ /**
179
+ * Map the output of any fal 3D endpoint to a `Model3DResult`. One generic
180
+ * mapper reads the known output fields, so there is no table per model.
181
+ *
182
+ * `url` is the best mesh of the PBR and base files: the first GLB in the
183
+ * order `pbr_model`, `model_glb_pbr`, `model_glb`, `model_urls.glb`,
184
+ * `model_mesh`, `base_model`. When there is no GLB, it is the first
185
+ * non-GLB file in that order, with `model_urls` in the order gltf, fbx,
186
+ * usdz, obj, stl. When the output has no PBR or base file, the same rule
187
+ * runs on the rigged, animated, and part files. `files` holds every mesh
188
+ * file with its format and role, the main file included, and then the
189
+ * texture files with the role `'texture'` and no format.
190
+ *
191
+ * `previewImageUrl` comes from `rendered_image` or `thumbnail`.
192
+ *
193
+ * Throws when the output has no mesh file.
194
+ */
195
+ export function mapFalModel3DOutput(jobId: string, output: unknown) {
196
+ const fields = isRecord(output) ? output : {}
197
+ const meshFiles = collectMeshFiles(fields)
198
+ const primaryFiles = meshFiles.filter(
199
+ (file) => file.role === 'pbr' || file.role === 'base',
200
+ )
201
+ const main = pickMainFile(primaryFiles) ?? pickMainFile(meshFiles)
202
+ if (!main) {
203
+ const fieldNames = Object.keys(fields).join(', ') || 'none'
204
+ throw new Error(
205
+ `fal: job ${jobId} returned no 3D model file. Output fields: ${fieldNames}.`,
206
+ )
207
+ }
208
+ const previewImageUrl = findPreviewUrl(fields)
209
+ return {
210
+ jobId,
211
+ url: main.url,
212
+ format: main.format,
213
+ files: [...meshFiles, ...collectTextureFiles(fields)],
214
+ ...(previewImageUrl ? { previewImageUrl } : {}),
215
+ }
216
+ }
@@ -38,6 +38,31 @@ export function createAdapterFalClient(config?: FalClientConfig) {
38
38
  return createFalClient(toFalClientOptions(config))
39
39
  }
40
40
 
41
+ /**
42
+ * fal can report a request COMPLETED and then answer the result fetch with a
43
+ * 422. Returns its `detail` text, or joins a detail list as `field: message`
44
+ * pairs. Returns undefined when the error has no detail.
45
+ */
46
+ export function falValidationMessage(error: unknown): string | undefined {
47
+ if (typeof error !== 'object' || error === null || !('body' in error)) {
48
+ return undefined
49
+ }
50
+ const body = error.body
51
+ if (typeof body !== 'object' || body === null || !('detail' in body)) {
52
+ return undefined
53
+ }
54
+ const detail = body.detail
55
+ if (typeof detail === 'string') return detail || undefined
56
+ if (!Array.isArray(detail)) return undefined
57
+ const message = detail
58
+ .map((d: { msg?: string; loc?: Array<string> }) => {
59
+ const msg = d.msg ?? 'invalid value'
60
+ return d.loc ? `${d.loc.join('.')}: ${msg}` : msg
61
+ })
62
+ .join('; ')
63
+ return message || undefined
64
+ }
65
+
41
66
  export function generateId(prefix: string): string {
42
67
  return _generateId(prefix)
43
68
  }