@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
@@ -1,6 +1,7 @@
1
1
  import { EndpointTypeMap } from '@fal-ai/client/endpoints';
2
2
  import { MediaPromptModality } from '@tanstack/ai';
3
3
  import { FalImageFieldName } from './image/generated/image-field-overrides.js';
4
+ import { FAL_MESH_FIELD_MAP, FalMeshFieldName } from './model3d/generated/mesh-field-overrides.js';
4
5
  export type { EndpointTypeMap } from '@fal-ai/client/endpoints';
5
6
  /**
6
7
  * All known fal.ai model IDs with autocomplete support.
@@ -142,3 +143,51 @@ export type FalTranscriptionProviderOptions<TModel extends string> = Omit<FalMod
142
143
  * Use this for the `modelOptions` parameter in audio generation.
143
144
  */
144
145
  export type FalAudioProviderOptions<TModel extends string> = Omit<FalModelInput<TModel>, 'prompt'>;
146
+ /**
147
+ * The fal 3D endpoints that `fal3DModel()` knows. Each id is a key of the
148
+ * installed SDK's `EndpointTypeMap`, and each endpoint returns a mesh file.
149
+ *
150
+ * @experimental 3D model generation is experimental and may change.
151
+ */
152
+ export type Fal3DKnownModel = 'fal-ai/hunyuan3d/v2' | 'fal-ai/hunyuan3d/v2/turbo' | 'fal-ai/hunyuan3d/v2/mini' | 'fal-ai/hunyuan3d/v2/mini/turbo' | 'fal-ai/hunyuan3d/v2/multi-view' | 'fal-ai/hunyuan3d/v2/multi-view/turbo' | 'fal-ai/hunyuan3d-v3/image-to-3d' | 'fal-ai/hunyuan3d-v3/text-to-3d' | 'fal-ai/hunyuan-3d/v3.1/pro/image-to-3d' | 'fal-ai/hunyuan-3d/v3.1/pro/text-to-3d' | 'fal-ai/hunyuan-3d/v3.1/rapid/image-to-3d' | 'fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d' | 'fal-ai/hyper3d/rodin' | 'fal-ai/hyper3d/rodin/v2' | 'fal-ai/meshy/v6/image-to-3d' | 'fal-ai/meshy/v6/text-to-3d' | 'fal-ai/meshy/v6-preview/text-to-3d' | 'meshy/v7.1/image-to-3d' | 'meshy/v7.1/multi-image-to-3d' | 'meshy/v7.1/text-to-3d' | 'meshy/v7/retexture' | 'fal-ai/trellis' | 'fal-ai/trellis/multi' | 'fal-ai/trellis-2' | 'fal-ai/trellis-2/retexture' | 'tripo3d/tripo/v2.5/image-to-3d' | 'tripo3d/tripo/v2.5/multiview-to-3d' | 'tripo3d/tripo/remesh' | 'fal-ai/sam-3/3d-objects' | 'fal-ai/sam-3/3d-body';
153
+ /**
154
+ * A fal 3D endpoint id. The known ids autocomplete. Any other string also
155
+ * works, without typed options, so a new fal endpoint is usable at once.
156
+ *
157
+ * @experimental 3D model generation is experimental and may change.
158
+ */
159
+ export type Fal3DModel = Fal3DKnownModel | (string & {});
160
+ /**
161
+ * Input fields that take the text of a 3D prompt: `prompt`, or
162
+ * `text_style_prompt` for Meshy retexture.
163
+ */
164
+ export type Fal3DTextFieldName = 'prompt' | 'text_style_prompt';
165
+ /**
166
+ * Input fields that take the image parts of a 3D prompt: the fields of the
167
+ * generated image field map, and `image_style_url` for Meshy retexture.
168
+ */
169
+ export type Fal3DImageFieldName = FalImageFieldName | 'image_style_url';
170
+ /** Input fields that the 3D adapter fills from the prompt. */
171
+ type Fal3DPromptFieldName = Fal3DTextFieldName | Fal3DImageFieldName | FalMeshFieldName;
172
+ /**
173
+ * Provider options for 3D model generation: the endpoint input without the
174
+ * fields that the adapter fills from the prompt (the text field, the image
175
+ * fields, and the mesh field). Endpoints that the installed SDK does not know
176
+ * take any options.
177
+ *
178
+ * @example
179
+ * type Options = Fal3DModelProviderOptions<'fal-ai/hunyuan3d-v3/image-to-3d'>
180
+ * // { face_count?: number; generate_type?: 'Normal' | 'LowPoly' | 'Geometry'; ... }
181
+ *
182
+ * @experimental 3D model generation is experimental and may change.
183
+ */
184
+ export type Fal3DModelProviderOptions<TModel extends string> = TModel extends keyof EndpointTypeMap ? Omit<FalModelInput<TModel>, Fal3DPromptFieldName> : Record<string, unknown>;
185
+ /**
186
+ * Prompt input modalities for a fal 3D endpoint. An endpoint takes image
187
+ * parts when its input has one of the {@link Fal3DImageFieldName} fields. It
188
+ * takes a `model3d` part when the generated mesh field map lists it.
189
+ * Endpoints that the installed SDK does not know are unconstrained.
190
+ *
191
+ * @experimental 3D model generation is experimental and may change.
192
+ */
193
+ export type Fal3DPromptModalitiesFor<TModel extends string> = TModel extends keyof EndpointTypeMap ? ReadonlyArray<(Extract<keyof FalModelInput<TModel>, Fal3DImageFieldName> extends never ? never : 'image') | (TModel extends keyof typeof FAL_MESH_FIELD_MAP ? 'model3d' : never)> : ReadonlyArray<MediaPromptModality>;
@@ -0,0 +1,20 @@
1
+ /** sha256 of the endpoints.d.ts this file was generated from. */
2
+ export declare const FAL_MESH_ENDPOINTS_DTS_SHA256 = "be36a2f9a11b0c7d011036915e1615f80e60bfc341ec6b770e897770c63cb511";
3
+ /** Every input field name that fal 3D endpoints use for an input mesh. */
4
+ export type FalMeshFieldName = 'model_url' | 'mesh_url' | 'input_file_url';
5
+ /** fal endpoint id -> the input field that takes the mesh. */
6
+ export declare const FAL_MESH_FIELD_MAP: {
7
+ readonly 'fal-ai/hunyuan-3d/v3.1/part': "input_file_url";
8
+ readonly 'fal-ai/hunyuan-3d/v3.1/smart-topology': "input_file_url";
9
+ readonly 'fal-ai/meshy/rigging': "model_url";
10
+ readonly 'fal-ai/meshy/rigging/multi-animation': "model_url";
11
+ readonly 'fal-ai/trellis-2/retexture': "mesh_url";
12
+ readonly 'hitem3d/hi3d/multicolor': "mesh_url";
13
+ readonly 'hitem3d/hi3d/split': "mesh_url";
14
+ readonly 'hitem3d/hi3d/texture': "mesh_url";
15
+ readonly 'meshy/v6-lite/retexture': "model_url";
16
+ readonly 'meshy/v6/retexture': "model_url";
17
+ readonly 'meshy/v7/retexture': "model_url";
18
+ readonly 'tripo3d/tripo/remesh': "mesh_url";
19
+ readonly 'tripo3d/tripo/segment': "mesh_url";
20
+ };
@@ -0,0 +1,20 @@
1
+ // src/model3d/generated/mesh-field-overrides.ts
2
+ /** fal endpoint id -> the input field that takes the mesh. */
3
+ var FAL_MESH_FIELD_MAP = {
4
+ "fal-ai/hunyuan-3d/v3.1/part": "input_file_url",
5
+ "fal-ai/hunyuan-3d/v3.1/smart-topology": "input_file_url",
6
+ "fal-ai/meshy/rigging": "model_url",
7
+ "fal-ai/meshy/rigging/multi-animation": "model_url",
8
+ "fal-ai/trellis-2/retexture": "mesh_url",
9
+ "hitem3d/hi3d/multicolor": "mesh_url",
10
+ "hitem3d/hi3d/split": "mesh_url",
11
+ "hitem3d/hi3d/texture": "mesh_url",
12
+ "meshy/v6-lite/retexture": "model_url",
13
+ "meshy/v6/retexture": "model_url",
14
+ "meshy/v7/retexture": "model_url",
15
+ "tripo3d/tripo/remesh": "mesh_url",
16
+ "tripo3d/tripo/segment": "mesh_url"
17
+ };
18
+ export { FAL_MESH_FIELD_MAP };
19
+
20
+ //# sourceMappingURL=mesh-field-overrides.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mesh-field-overrides.js","names":[],"sources":["../../../../src/model3d/generated/mesh-field-overrides.ts"],"sourcesContent":["/* eslint-disable */\n// ---------------------------------------------------------------------------\n// AUTO-GENERATED. Do not edit by hand.\n//\n// Generated from @fal-ai/client@1.11.0 EndpointTypeMap by\n// scripts/generate-fal-image-field-map.ts. Regenerate after bumping\n// @fal-ai/client:\n//\n// pnpm tsx scripts/generate-fal-image-field-map.ts\n//\n// Maps every fal 3D endpoint that takes an existing mesh to the input field\n// for that mesh. Endpoints with no mesh input are not listed. The\n// `satisfies` clause below checks every field name against the SDK's\n// endpoint input types at compile time (type-only import, so nothing from\n// endpoints.d.ts ships at runtime).\n// ---------------------------------------------------------------------------\nimport type { EndpointTypeMap } from '@fal-ai/client/endpoints'\n\n/** sha256 of the endpoints.d.ts this file was generated from. */\nexport const FAL_MESH_ENDPOINTS_DTS_SHA256 =\n 'be36a2f9a11b0c7d011036915e1615f80e60bfc341ec6b770e897770c63cb511'\n\n/** Every input field name that fal 3D endpoints use for an input mesh. */\nexport type FalMeshFieldName = 'model_url' | 'mesh_url' | 'input_file_url'\n\n/** fal endpoint id -> the input field that takes the mesh. */\nexport const FAL_MESH_FIELD_MAP = {\n 'fal-ai/hunyuan-3d/v3.1/part': 'input_file_url',\n 'fal-ai/hunyuan-3d/v3.1/smart-topology': 'input_file_url',\n 'fal-ai/meshy/rigging': 'model_url',\n 'fal-ai/meshy/rigging/multi-animation': 'model_url',\n 'fal-ai/trellis-2/retexture': 'mesh_url',\n 'hitem3d/hi3d/multicolor': 'mesh_url',\n 'hitem3d/hi3d/split': 'mesh_url',\n 'hitem3d/hi3d/texture': 'mesh_url',\n 'meshy/v6-lite/retexture': 'model_url',\n 'meshy/v6/retexture': 'model_url',\n 'meshy/v7/retexture': 'model_url',\n 'tripo3d/tripo/remesh': 'mesh_url',\n 'tripo3d/tripo/segment': 'mesh_url',\n} as const satisfies {\n [K in keyof EndpointTypeMap]?: Extract<\n keyof EndpointTypeMap[K]['input'],\n FalMeshFieldName\n >\n}\n"],"mappings":";;AA0BA,IAAa,qBAAqB;CAChC,+BAA+B;CAC/B,yCAAyC;CACzC,wBAAwB;CACxB,wCAAwC;CACxC,8BAA8B;CAC9B,2BAA2B;CAC3B,sBAAsB;CACtB,wBAAwB;CACxB,2BAA2B;CAC3B,sBAAsB;CACtB,sBAAsB;CACtB,wBAAwB;CACxB,yBAAyB;AAC3B"}
@@ -0,0 +1,39 @@
1
+ import { MediaPrompt } from '@tanstack/ai';
2
+ import { Fal3DModel } from '../model-meta.js';
3
+ /**
4
+ * Map a 3D prompt onto the input fields of a fal 3D endpoint.
5
+ *
6
+ * - Text goes to the `prompt` field (`text_style_prompt` for Meshy
7
+ * retexture). It throws when the endpoint is known and takes no
8
+ * text, so the text is never dropped without a warning. An endpoint that
9
+ * is not known gets `prompt`.
10
+ * - Image parts go through the generated image field map (for example
11
+ * `input_image_url` for Hunyuan3D v3, `image_urls` for TRELLIS multi).
12
+ * Meshy retexture takes one image in `image_style_url`. It throws when the endpoint is known and takes no image parts.
13
+ * - One `model3d` part goes to the mesh field from the generated mesh field
14
+ * map (`model_url`, `mesh_url`, or `input_file_url`). It throws for a second
15
+ * mesh, and for an endpoint that has no mesh field.
16
+ * - Video and audio parts throw, because no fal 3D endpoint takes them.
17
+ *
18
+ * Every image and mesh source goes through `contentSourceToFalUrl`, so URL,
19
+ * `data:`, and fal file sources all work.
20
+ *
21
+ * @example
22
+ * mapModel3DPromptToFalFields('fal-ai/trellis-2/retexture', [
23
+ * { type: 'model3d', source: { type: 'url', value: 'https://x/chair.glb' } },
24
+ * ])
25
+ * // { mesh_url: 'https://x/chair.glb' }
26
+ */
27
+ export declare function mapModel3DPromptToFalFields(model: Fal3DModel, prompt: MediaPrompt): {
28
+ image_style_url?: undefined;
29
+ prompt: string;
30
+ } | {
31
+ image_style_url: string;
32
+ prompt: string;
33
+ } | {
34
+ image_style_url?: undefined;
35
+ prompt?: undefined;
36
+ } | {
37
+ image_style_url: string;
38
+ prompt?: undefined;
39
+ };
@@ -0,0 +1,206 @@
1
+ import { contentSourceToFalUrl, mapImageInputsToFalFields } from "../image/image-inputs.js";
2
+ import { FAL_MESH_FIELD_MAP } from "./generated/mesh-field-overrides.js";
3
+ import { resolveMediaPrompt } from "@tanstack/ai";
4
+ // src/model3d/model3d-inputs.ts
5
+ /** The same tables, readable with any endpoint id. */
6
+ var PROMPT_FIELDS_BY_ENDPOINT = {
7
+ "fal-ai/hunyuan3d/v2": {
8
+ text: null,
9
+ image: ["input_image_url"]
10
+ },
11
+ "fal-ai/hunyuan3d/v2/turbo": {
12
+ text: null,
13
+ image: ["input_image_url"]
14
+ },
15
+ "fal-ai/hunyuan3d/v2/mini": {
16
+ text: null,
17
+ image: ["input_image_url"]
18
+ },
19
+ "fal-ai/hunyuan3d/v2/mini/turbo": {
20
+ text: null,
21
+ image: ["input_image_url"]
22
+ },
23
+ "fal-ai/hunyuan3d/v2/multi-view": {
24
+ text: null,
25
+ image: null
26
+ },
27
+ "fal-ai/hunyuan3d/v2/multi-view/turbo": {
28
+ text: null,
29
+ image: null
30
+ },
31
+ "fal-ai/hunyuan3d-v3/image-to-3d": {
32
+ text: null,
33
+ image: ["input_image_url"]
34
+ },
35
+ "fal-ai/hunyuan3d-v3/text-to-3d": {
36
+ text: "prompt",
37
+ image: null
38
+ },
39
+ "fal-ai/hunyuan-3d/v3.1/pro/image-to-3d": {
40
+ text: null,
41
+ image: ["input_image_url"]
42
+ },
43
+ "fal-ai/hunyuan-3d/v3.1/pro/text-to-3d": {
44
+ text: "prompt",
45
+ image: null
46
+ },
47
+ "fal-ai/hunyuan-3d/v3.1/rapid/image-to-3d": {
48
+ text: null,
49
+ image: ["input_image_url"]
50
+ },
51
+ "fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d": {
52
+ text: "prompt",
53
+ image: null
54
+ },
55
+ "fal-ai/hyper3d/rodin": {
56
+ text: "prompt",
57
+ image: ["input_image_urls"]
58
+ },
59
+ "fal-ai/hyper3d/rodin/v2": {
60
+ text: "prompt",
61
+ image: ["input_image_urls"]
62
+ },
63
+ "fal-ai/meshy/v6/image-to-3d": {
64
+ text: null,
65
+ image: ["image_url"]
66
+ },
67
+ "fal-ai/meshy/v6/text-to-3d": {
68
+ text: "prompt",
69
+ image: null
70
+ },
71
+ "fal-ai/meshy/v6-preview/text-to-3d": {
72
+ text: "prompt",
73
+ image: null
74
+ },
75
+ "meshy/v7.1/image-to-3d": {
76
+ text: null,
77
+ image: ["image_url"]
78
+ },
79
+ "meshy/v7.1/multi-image-to-3d": {
80
+ text: null,
81
+ image: ["image_urls"]
82
+ },
83
+ "meshy/v7.1/text-to-3d": {
84
+ text: "prompt",
85
+ image: null
86
+ },
87
+ "meshy/v7/retexture": {
88
+ text: "text_style_prompt",
89
+ image: "image_style_url"
90
+ },
91
+ "fal-ai/trellis": {
92
+ text: null,
93
+ image: ["image_url"]
94
+ },
95
+ "fal-ai/trellis/multi": {
96
+ text: null,
97
+ image: ["image_urls"]
98
+ },
99
+ "fal-ai/trellis-2": {
100
+ text: null,
101
+ image: ["image_url"]
102
+ },
103
+ "fal-ai/trellis-2/retexture": {
104
+ text: null,
105
+ image: ["image_url"]
106
+ },
107
+ "tripo3d/tripo/v2.5/image-to-3d": {
108
+ text: null,
109
+ image: ["image_url"]
110
+ },
111
+ "tripo3d/tripo/v2.5/multiview-to-3d": {
112
+ text: null,
113
+ image: null
114
+ },
115
+ "tripo3d/tripo/remesh": {
116
+ text: null,
117
+ image: null
118
+ },
119
+ "fal-ai/sam-3/3d-objects": {
120
+ text: "prompt",
121
+ image: ["image_url"]
122
+ },
123
+ "fal-ai/sam-3/3d-body": {
124
+ text: null,
125
+ image: ["image_url", "mask_url"]
126
+ }
127
+ };
128
+ var MESH_FIELD_BY_ENDPOINT = FAL_MESH_FIELD_MAP;
129
+ /**
130
+ * The shared image mapper sends each part to the field of its role (for
131
+ * example a second source image to `image_urls`, and a `reference` image to
132
+ * `reference_image_urls`). A known endpoint ignores a field that it does not
133
+ * have, so reject that case before submit.
134
+ */
135
+ function rejectUnknownImageFields(model, fields, allowed) {
136
+ const unknown = Object.keys(fields).filter((field) => !allowed.includes(field));
137
+ if (unknown.length === 0) return;
138
+ const list = (names) => names.map((name) => `'${name}'`).join(", ");
139
+ throw new Error(`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.`);
140
+ }
141
+ function mapTextToFalField(model, text) {
142
+ if (!text) return {};
143
+ const known = PROMPT_FIELDS_BY_ENDPOINT[model];
144
+ if (!known) return { prompt: text };
145
+ if (known.text === null) throw new Error(`fal: model ${model} takes no text prompt. Remove the text from the prompt, or use an endpoint that takes text.`);
146
+ return { [known.text]: text };
147
+ }
148
+ function mapImagesToFalFields(model, images) {
149
+ if (images.length === 0) return {};
150
+ const known = PROMPT_FIELDS_BY_ENDPOINT[model];
151
+ if (!known) return mapImageInputsToFalFields(model, images);
152
+ const imageRouting = known.image;
153
+ if (imageRouting === null) throw new Error(`fal: model ${model} takes no image prompt parts. Pass its image fields through modelOptions.`);
154
+ if (imageRouting === "image_style_url") {
155
+ const [image, ...rest] = images;
156
+ if (!image || rest.length > 0) throw new Error(`fal: model ${model} takes one style image (received ${images.length}).`);
157
+ return { image_style_url: contentSourceToFalUrl(image.source) };
158
+ }
159
+ const fields = mapImageInputsToFalFields(model, images);
160
+ rejectUnknownImageFields(model, fields, imageRouting);
161
+ return fields;
162
+ }
163
+ function mapMeshToFalField(model, meshes) {
164
+ if (meshes.length === 0) return {};
165
+ const [mesh, ...rest] = meshes;
166
+ if (!mesh || rest.length > 0) throw new Error(`fal: model ${model} takes one model3d prompt part (received ${meshes.length}).`);
167
+ const meshField = MESH_FIELD_BY_ENDPOINT[model];
168
+ if (!meshField) throw new Error(`fal: model ${model} takes no model3d prompt part. Use an endpoint that takes a mesh, or pass the mesh field through modelOptions.`);
169
+ return { [meshField]: contentSourceToFalUrl(mesh.source) };
170
+ }
171
+ /**
172
+ * Map a 3D prompt onto the input fields of a fal 3D endpoint.
173
+ *
174
+ * - Text goes to the `prompt` field (`text_style_prompt` for Meshy
175
+ * retexture). It throws when the endpoint is known and takes no
176
+ * text, so the text is never dropped without a warning. An endpoint that
177
+ * is not known gets `prompt`.
178
+ * - Image parts go through the generated image field map (for example
179
+ * `input_image_url` for Hunyuan3D v3, `image_urls` for TRELLIS multi).
180
+ * Meshy retexture takes one image in `image_style_url`. It throws when the endpoint is known and takes no image parts.
181
+ * - One `model3d` part goes to the mesh field from the generated mesh field
182
+ * map (`model_url`, `mesh_url`, or `input_file_url`). It throws for a second
183
+ * mesh, and for an endpoint that has no mesh field.
184
+ * - Video and audio parts throw, because no fal 3D endpoint takes them.
185
+ *
186
+ * Every image and mesh source goes through `contentSourceToFalUrl`, so URL,
187
+ * `data:`, and fal file sources all work.
188
+ *
189
+ * @example
190
+ * mapModel3DPromptToFalFields('fal-ai/trellis-2/retexture', [
191
+ * { type: 'model3d', source: { type: 'url', value: 'https://x/chair.glb' } },
192
+ * ])
193
+ * // { mesh_url: 'https://x/chair.glb' }
194
+ */
195
+ function mapModel3DPromptToFalFields(model, prompt) {
196
+ const resolved = resolveMediaPrompt(prompt);
197
+ if (resolved.videos.length > 0 || resolved.audios.length > 0) throw new Error(`fal: model ${model} takes text, image, and model3d prompt parts only. Remove the video and audio parts.`);
198
+ return {
199
+ ...mapTextToFalField(model, resolved.text),
200
+ ...mapImagesToFalFields(model, resolved.images),
201
+ ...mapMeshToFalField(model, resolved.models3d)
202
+ };
203
+ }
204
+ export { mapModel3DPromptToFalFields };
205
+
206
+ //# sourceMappingURL=model3d-inputs.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"model3d-inputs.js","names":[],"sources":["../../../src/model3d/model3d-inputs.ts"],"sourcesContent":["import { resolveMediaPrompt } from '@tanstack/ai'\nimport {\n contentSourceToFalUrl,\n mapImageInputsToFalFields,\n} from '../image/image-inputs'\nimport { FAL_MESH_FIELD_MAP } from './generated/mesh-field-overrides'\nimport type { FalImageFieldName } from '../image/generated/image-field-overrides'\nimport type {\n ImagePart,\n MediaInputMetadata,\n MediaPrompt,\n Model3DPart,\n} from '@tanstack/ai'\nimport type { EndpointTypeMap } from '@fal-ai/client/endpoints'\nimport type { FalMeshFieldName } from './generated/mesh-field-overrides'\nimport type {\n Fal3DKnownModel,\n Fal3DModel,\n Fal3DTextFieldName,\n} from '../model-meta'\n\n/**\n * How a known 3D endpoint takes the text and image parts of a prompt.\n *\n * - `text`: the input field for the prompt text, or `null` when the endpoint\n * takes no text.\n * - `image`: the image fields of the endpoint. The generated image field map\n * routes the image parts, and a part that lands on another field throws.\n * `'image_style_url'` for Meshy retexture (one style image), or `null`\n * when the endpoint takes no image parts (for example multi-view\n * endpoints, which take their views through `modelOptions`).\n */\ntype Fal3DPromptFields<TInput> = {\n text: Extract<keyof TInput, Fal3DTextFieldName> extends never\n ? null\n : Extract<keyof TInput, Fal3DTextFieldName>\n image: Extract<keyof TInput, FalImageFieldName> extends never\n ? Extract<keyof TInput, 'image_style_url'> extends never\n ? null\n : 'image_style_url'\n : ReadonlyArray<Extract<keyof TInput, FalImageFieldName>>\n}\n\ntype Fal3DImageRouting =\n | ReadonlyArray<FalImageFieldName>\n | 'image_style_url'\n | null\n\n/**\n * The prompt fields of every known 3D endpoint. The `satisfies` clause checks\n * each entry against the endpoint input type of the installed SDK, so a wrong\n * or missing entry is a compile error.\n */\nconst FAL_3D_PROMPT_FIELDS = {\n 'fal-ai/hunyuan3d/v2': { text: null, image: ['input_image_url'] },\n 'fal-ai/hunyuan3d/v2/turbo': { text: null, image: ['input_image_url'] },\n 'fal-ai/hunyuan3d/v2/mini': { text: null, image: ['input_image_url'] },\n 'fal-ai/hunyuan3d/v2/mini/turbo': { text: null, image: ['input_image_url'] },\n 'fal-ai/hunyuan3d/v2/multi-view': { text: null, image: null },\n 'fal-ai/hunyuan3d/v2/multi-view/turbo': { text: null, image: null },\n 'fal-ai/hunyuan3d-v3/image-to-3d': { text: null, image: ['input_image_url'] },\n 'fal-ai/hunyuan3d-v3/text-to-3d': { text: 'prompt', image: null },\n 'fal-ai/hunyuan-3d/v3.1/pro/image-to-3d': {\n text: null,\n image: ['input_image_url'],\n },\n 'fal-ai/hunyuan-3d/v3.1/pro/text-to-3d': { text: 'prompt', image: null },\n 'fal-ai/hunyuan-3d/v3.1/rapid/image-to-3d': {\n text: null,\n image: ['input_image_url'],\n },\n 'fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d': { text: 'prompt', image: null },\n 'fal-ai/hyper3d/rodin': { text: 'prompt', image: ['input_image_urls'] },\n 'fal-ai/hyper3d/rodin/v2': { text: 'prompt', image: ['input_image_urls'] },\n 'fal-ai/meshy/v6/image-to-3d': { text: null, image: ['image_url'] },\n 'fal-ai/meshy/v6/text-to-3d': { text: 'prompt', image: null },\n 'fal-ai/meshy/v6-preview/text-to-3d': { text: 'prompt', image: null },\n 'meshy/v7.1/image-to-3d': { text: null, image: ['image_url'] },\n 'meshy/v7.1/multi-image-to-3d': { text: null, image: ['image_urls'] },\n 'meshy/v7.1/text-to-3d': { text: 'prompt', image: null },\n 'meshy/v7/retexture': {\n text: 'text_style_prompt',\n image: 'image_style_url',\n },\n 'fal-ai/trellis': { text: null, image: ['image_url'] },\n 'fal-ai/trellis/multi': { text: null, image: ['image_urls'] },\n 'fal-ai/trellis-2': { text: null, image: ['image_url'] },\n 'fal-ai/trellis-2/retexture': { text: null, image: ['image_url'] },\n 'tripo3d/tripo/v2.5/image-to-3d': { text: null, image: ['image_url'] },\n 'tripo3d/tripo/v2.5/multiview-to-3d': { text: null, image: null },\n 'tripo3d/tripo/remesh': { text: null, image: null },\n 'fal-ai/sam-3/3d-objects': { text: 'prompt', image: ['image_url'] },\n 'fal-ai/sam-3/3d-body': { text: null, image: ['image_url', 'mask_url'] },\n} as const satisfies {\n [K in Fal3DKnownModel]: Fal3DPromptFields<EndpointTypeMap[K]['input']>\n}\n\n/** The same tables, readable with any endpoint id. */\nconst PROMPT_FIELDS_BY_ENDPOINT: Partial<\n Record<\n string,\n {\n text: Fal3DTextFieldName | null\n image: Fal3DImageRouting\n }\n >\n> = FAL_3D_PROMPT_FIELDS\nconst MESH_FIELD_BY_ENDPOINT: Partial<Record<string, FalMeshFieldName>> =\n FAL_MESH_FIELD_MAP\n\n/**\n * The shared image mapper sends each part to the field of its role (for\n * example a second source image to `image_urls`, and a `reference` image to\n * `reference_image_urls`). A known endpoint ignores a field that it does not\n * have, so reject that case before submit.\n */\nfunction rejectUnknownImageFields(\n model: string,\n fields: Record<string, unknown>,\n allowed: ReadonlyArray<string>,\n) {\n const unknown = Object.keys(fields).filter(\n (field) => !allowed.includes(field),\n )\n if (unknown.length === 0) return\n const list = (names: ReadonlyArray<string>) =>\n names.map((name) => `'${name}'`).join(', ')\n throw new Error(\n `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.`,\n )\n}\n\nfunction mapTextToFalField(model: string, text: string) {\n if (!text) return {}\n const known = PROMPT_FIELDS_BY_ENDPOINT[model]\n // An endpoint that the table does not know gets the common `prompt` field.\n if (!known) return { prompt: text }\n if (known.text === null) {\n throw new Error(\n `fal: model ${model} takes no text prompt. Remove the text from the prompt, or use an endpoint that takes text.`,\n )\n }\n return { [known.text]: text }\n}\n\nfunction mapImagesToFalFields(\n model: string,\n images: ReadonlyArray<ImagePart<MediaInputMetadata>>,\n) {\n if (images.length === 0) return {}\n const known = PROMPT_FIELDS_BY_ENDPOINT[model]\n // An endpoint that the table does not know uses the generated image map.\n if (!known) return mapImageInputsToFalFields(model, images)\n const imageRouting = known.image\n if (imageRouting === null) {\n throw new Error(\n `fal: model ${model} takes no image prompt parts. Pass its image fields through modelOptions.`,\n )\n }\n if (imageRouting === 'image_style_url') {\n const [image, ...rest] = images\n if (!image || rest.length > 0) {\n throw new Error(\n `fal: model ${model} takes one style image (received ${images.length}).`,\n )\n }\n return { image_style_url: contentSourceToFalUrl(image.source) }\n }\n const fields = mapImageInputsToFalFields(model, images)\n rejectUnknownImageFields(model, fields, imageRouting)\n return fields\n}\n\nfunction mapMeshToFalField(model: string, meshes: ReadonlyArray<Model3DPart>) {\n if (meshes.length === 0) return {}\n const [mesh, ...rest] = meshes\n if (!mesh || rest.length > 0) {\n throw new Error(\n `fal: model ${model} takes one model3d prompt part (received ${meshes.length}).`,\n )\n }\n const meshField = MESH_FIELD_BY_ENDPOINT[model]\n if (!meshField) {\n throw new Error(\n `fal: model ${model} takes no model3d prompt part. Use an endpoint that takes a mesh, or pass the mesh field through modelOptions.`,\n )\n }\n return { [meshField]: contentSourceToFalUrl(mesh.source) }\n}\n\n/**\n * Map a 3D prompt onto the input fields of a fal 3D endpoint.\n *\n * - Text goes to the `prompt` field (`text_style_prompt` for Meshy\n * retexture). It throws when the endpoint is known and takes no\n * text, so the text is never dropped without a warning. An endpoint that\n * is not known gets `prompt`.\n * - Image parts go through the generated image field map (for example\n * `input_image_url` for Hunyuan3D v3, `image_urls` for TRELLIS multi).\n * Meshy retexture takes one image in `image_style_url`. It throws when the endpoint is known and takes no image parts.\n * - One `model3d` part goes to the mesh field from the generated mesh field\n * map (`model_url`, `mesh_url`, or `input_file_url`). It throws for a second\n * mesh, and for an endpoint that has no mesh field.\n * - Video and audio parts throw, because no fal 3D endpoint takes them.\n *\n * Every image and mesh source goes through `contentSourceToFalUrl`, so URL,\n * `data:`, and fal file sources all work.\n *\n * @example\n * mapModel3DPromptToFalFields('fal-ai/trellis-2/retexture', [\n * { type: 'model3d', source: { type: 'url', value: 'https://x/chair.glb' } },\n * ])\n * // { mesh_url: 'https://x/chair.glb' }\n */\nexport function mapModel3DPromptToFalFields(\n model: Fal3DModel,\n prompt: MediaPrompt,\n) {\n const resolved = resolveMediaPrompt(prompt)\n const hasUnsupportedParts =\n resolved.videos.length > 0 || resolved.audios.length > 0\n if (hasUnsupportedParts) {\n throw new Error(\n `fal: model ${model} takes text, image, and model3d prompt parts only. Remove the video and audio parts.`,\n )\n }\n return {\n ...mapTextToFalField(model, resolved.text),\n ...mapImagesToFalFields(model, resolved.images),\n ...mapMeshToFalField(model, resolved.models3d),\n }\n}\n"],"mappings":"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"}
@@ -0,0 +1,25 @@
1
+ import { Model3DFile } from '@tanstack/ai';
2
+ /**
3
+ * Map the output of any fal 3D endpoint to a `Model3DResult`. One generic
4
+ * mapper reads the known output fields, so there is no table per model.
5
+ *
6
+ * `url` is the best mesh of the PBR and base files: the first GLB in the
7
+ * order `pbr_model`, `model_glb_pbr`, `model_glb`, `model_urls.glb`,
8
+ * `model_mesh`, `base_model`. When there is no GLB, it is the first
9
+ * non-GLB file in that order, with `model_urls` in the order gltf, fbx,
10
+ * usdz, obj, stl. When the output has no PBR or base file, the same rule
11
+ * runs on the rigged, animated, and part files. `files` holds every mesh
12
+ * file with its format and role, the main file included, and then the
13
+ * texture files with the role `'texture'` and no format.
14
+ *
15
+ * `previewImageUrl` comes from `rendered_image` or `thumbnail`.
16
+ *
17
+ * Throws when the output has no mesh file.
18
+ */
19
+ export declare function mapFalModel3DOutput(jobId: string, output: unknown): {
20
+ previewImageUrl?: string | undefined;
21
+ jobId: string;
22
+ url: string;
23
+ format: "glb" | "obj" | "fbx" | "usdz" | "stl" | "gltf";
24
+ files: Model3DFile[];
25
+ };
@@ -0,0 +1,181 @@
1
+ import { extractUrlExtension } from "../utils/client.js";
2
+ // src/model3d/model3d-output.ts
3
+ var FORMAT_BY_EXTENSION = {
4
+ glb: "glb",
5
+ gltf: "gltf",
6
+ fbx: "fbx",
7
+ obj: "obj",
8
+ usdz: "usdz",
9
+ stl: "stl"
10
+ };
11
+ var FORMAT_BY_CONTENT_TYPE = {
12
+ "model/gltf-binary": "glb",
13
+ "model/gltf+json": "gltf",
14
+ "model/obj": "obj",
15
+ "model/stl": "stl",
16
+ "application/sla": "stl",
17
+ "model/vnd.usdz+zip": "usdz"
18
+ };
19
+ /**
20
+ * The `model_urls` keys in the order the mapper prefers them when there is
21
+ * no GLB. FBX keeps materials and rigs, so it comes before OBJ.
22
+ */
23
+ var MODEL_URL_FORMATS = [
24
+ "glb",
25
+ "gltf",
26
+ "fbx",
27
+ "usdz",
28
+ "obj",
29
+ "stl"
30
+ ];
31
+ /**
32
+ * Output fields that hold one mesh file, in the order the mapper prefers
33
+ * them for the main `url`. Then come `model_urls`, rigged and animated
34
+ * meshes, and mesh parts (see {@link collectMeshFiles}).
35
+ */
36
+ var PBR_FIELDS = ["pbr_model", "model_glb_pbr"];
37
+ var BASE_FIELDS = ["model_mesh", "base_model"];
38
+ var RIGGED_FIELDS = ["rigged_character_glb", "rigged_character_fbx"];
39
+ var ANIMATION_FIELDS = ["animation_glb", "animation_fbx"];
40
+ var PART_LIST_FIELDS = [
41
+ "result_files",
42
+ "individual_glbs",
43
+ "meshes"
44
+ ];
45
+ var PREVIEW_FIELDS = ["rendered_image", "thumbnail"];
46
+ var TEXTURE_FIELDS = ["texture", "material_mtl"];
47
+ function isRecord(value) {
48
+ return typeof value === "object" && value !== null && !Array.isArray(value);
49
+ }
50
+ function isFalFile(value) {
51
+ return isRecord(value) && typeof value.url === "string";
52
+ }
53
+ function fileNameExtension(fileName) {
54
+ if (typeof fileName !== "string" || !fileName.includes(".")) return void 0;
55
+ return fileName.split(".").pop();
56
+ }
57
+ /**
58
+ * Find the format of a fal file from its file name, then its URL extension,
59
+ * then its content type. Returns `undefined` when the file is not a mesh
60
+ * format that `Model3DFormat` names (for example a PNG texture).
61
+ */
62
+ function detectFormat(file) {
63
+ const extension = fileNameExtension(file.file_name) ?? extractUrlExtension(file.url);
64
+ const byExtension = extension ? FORMAT_BY_EXTENSION[extension.toLowerCase()] : void 0;
65
+ if (byExtension) return byExtension;
66
+ if (typeof file.content_type !== "string") return void 0;
67
+ const mimeType = file.content_type.split(";")[0]?.trim().toLowerCase();
68
+ return mimeType ? FORMAT_BY_CONTENT_TYPE[mimeType] : void 0;
69
+ }
70
+ function contentTypeField(file) {
71
+ return typeof file.content_type === "string" ? { contentType: file.content_type } : {};
72
+ }
73
+ function toMeshFile(value, role, knownFormat) {
74
+ if (!isFalFile(value)) return void 0;
75
+ const format = detectFormat(value) ?? knownFormat;
76
+ if (!format) return void 0;
77
+ return {
78
+ url: value.url,
79
+ format,
80
+ role,
81
+ ...contentTypeField(value)
82
+ };
83
+ }
84
+ /**
85
+ * Read every mesh file from a fal 3D output, in the order the mapper prefers
86
+ * them, without two files that share a URL. Files that are not a
87
+ * `Model3DFormat` (textures, MTL files, Gaussian splats) are left out.
88
+ */
89
+ function collectMeshFiles(output) {
90
+ const files = [];
91
+ const add = (value, role, knownFormat) => {
92
+ const file = toMeshFile(value, role, knownFormat);
93
+ const isNewFile = file && !files.some((seen) => seen.url === file.url);
94
+ if (file && isNewFile) files.push(file);
95
+ };
96
+ for (const field of PBR_FIELDS) add(output[field], "pbr");
97
+ add(output.model_glb, "base", "glb");
98
+ const modelUrls = isRecord(output.model_urls) ? output.model_urls : {};
99
+ for (const format of MODEL_URL_FORMATS) add(modelUrls[format], "base", format);
100
+ for (const field of BASE_FIELDS) add(output[field], "base");
101
+ for (const field of RIGGED_FIELDS) add(output[field], "rigged");
102
+ for (const field of ANIMATION_FIELDS) add(output[field], "animation");
103
+ const basicAnimations = isRecord(output.basic_animations) ? Object.values(output.basic_animations) : [];
104
+ for (const animation of basicAnimations) add(animation, "animation");
105
+ for (const field of PART_LIST_FIELDS) {
106
+ const parts = output[field];
107
+ if (!Array.isArray(parts)) continue;
108
+ for (const part of parts) add(part, "part");
109
+ }
110
+ return files;
111
+ }
112
+ /**
113
+ * Read the texture files of a fal 3D output: the `textures` images (Rodin),
114
+ * the `base_color`, `metallic`, `normal`, and `roughness` files of each
115
+ * `texture_urls` entry (Meshy), and the `texture` and `material_mtl` files
116
+ * (Hunyuan3D rapid). They have the role `'texture'` and no `format`.
117
+ */
118
+ function collectTextureFiles(output) {
119
+ const values = [];
120
+ if (Array.isArray(output.textures)) values.push(...output.textures);
121
+ const textureSets = Array.isArray(output.texture_urls) ? output.texture_urls : [];
122
+ for (const textureSet of textureSets) if (isRecord(textureSet)) values.push(...Object.values(textureSet));
123
+ for (const field of TEXTURE_FIELDS) values.push(output[field]);
124
+ const files = [];
125
+ for (const value of values) {
126
+ if (!isFalFile(value)) continue;
127
+ files.push({
128
+ url: value.url,
129
+ role: "texture",
130
+ ...contentTypeField(value)
131
+ });
132
+ }
133
+ return files;
134
+ }
135
+ /** The first GLB in the list, else the first file. */
136
+ function pickMainFile(files) {
137
+ return files.find((file) => file.format === "glb") ?? files[0];
138
+ }
139
+ function findPreviewUrl(output) {
140
+ for (const field of PREVIEW_FIELDS) {
141
+ const preview = output[field];
142
+ if (isFalFile(preview)) return preview.url;
143
+ }
144
+ }
145
+ /**
146
+ * Map the output of any fal 3D endpoint to a `Model3DResult`. One generic
147
+ * mapper reads the known output fields, so there is no table per model.
148
+ *
149
+ * `url` is the best mesh of the PBR and base files: the first GLB in the
150
+ * order `pbr_model`, `model_glb_pbr`, `model_glb`, `model_urls.glb`,
151
+ * `model_mesh`, `base_model`. When there is no GLB, it is the first
152
+ * non-GLB file in that order, with `model_urls` in the order gltf, fbx,
153
+ * usdz, obj, stl. When the output has no PBR or base file, the same rule
154
+ * runs on the rigged, animated, and part files. `files` holds every mesh
155
+ * file with its format and role, the main file included, and then the
156
+ * texture files with the role `'texture'` and no format.
157
+ *
158
+ * `previewImageUrl` comes from `rendered_image` or `thumbnail`.
159
+ *
160
+ * Throws when the output has no mesh file.
161
+ */
162
+ function mapFalModel3DOutput(jobId, output) {
163
+ const fields = isRecord(output) ? output : {};
164
+ const meshFiles = collectMeshFiles(fields);
165
+ const main = pickMainFile(meshFiles.filter((file) => file.role === "pbr" || file.role === "base")) ?? pickMainFile(meshFiles);
166
+ if (!main) {
167
+ const fieldNames = Object.keys(fields).join(", ") || "none";
168
+ throw new Error(`fal: job ${jobId} returned no 3D model file. Output fields: ${fieldNames}.`);
169
+ }
170
+ const previewImageUrl = findPreviewUrl(fields);
171
+ return {
172
+ jobId,
173
+ url: main.url,
174
+ format: main.format,
175
+ files: [...meshFiles, ...collectTextureFiles(fields)],
176
+ ...previewImageUrl ? { previewImageUrl } : {}
177
+ };
178
+ }
179
+ export { mapFalModel3DOutput };
180
+
181
+ //# sourceMappingURL=model3d-output.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"model3d-output.js","names":[],"sources":["../../../src/model3d/model3d-output.ts"],"sourcesContent":["import { extractUrlExtension } from '../utils/client'\nimport type { Model3DFile, Model3DFileRole, Model3DFormat } from '@tanstack/ai'\n\n/** The fields of a fal `File` that the mapper reads. */\ninterface FalFileLike {\n url: string\n content_type?: unknown\n file_name?: unknown\n}\n\nconst FORMAT_BY_EXTENSION: Partial<Record<string, Model3DFormat>> = {\n glb: 'glb',\n gltf: 'gltf',\n fbx: 'fbx',\n obj: 'obj',\n usdz: 'usdz',\n stl: 'stl',\n}\n\nconst FORMAT_BY_CONTENT_TYPE: Partial<Record<string, Model3DFormat>> = {\n 'model/gltf-binary': 'glb',\n 'model/gltf+json': 'gltf',\n 'model/obj': 'obj',\n 'model/stl': 'stl',\n 'application/sla': 'stl',\n 'model/vnd.usdz+zip': 'usdz',\n}\n\n/**\n * The `model_urls` keys in the order the mapper prefers them when there is\n * no GLB. FBX keeps materials and rigs, so it comes before OBJ.\n */\nconst MODEL_URL_FORMATS = ['glb', 'gltf', 'fbx', 'usdz', 'obj', 'stl'] as const\n\n/**\n * Output fields that hold one mesh file, in the order the mapper prefers\n * them for the main `url`. Then come `model_urls`, rigged and animated\n * meshes, and mesh parts (see {@link collectMeshFiles}).\n */\nconst PBR_FIELDS = ['pbr_model', 'model_glb_pbr'] as const\nconst BASE_FIELDS = ['model_mesh', 'base_model'] as const\nconst RIGGED_FIELDS = ['rigged_character_glb', 'rigged_character_fbx'] as const\nconst ANIMATION_FIELDS = ['animation_glb', 'animation_fbx'] as const\nconst PART_LIST_FIELDS = ['result_files', 'individual_glbs', 'meshes'] as const\nconst PREVIEW_FIELDS = ['rendered_image', 'thumbnail'] as const\nconst TEXTURE_FIELDS = ['texture', 'material_mtl'] as const\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\nfunction isFalFile(value: unknown): value is FalFileLike {\n return isRecord(value) && typeof value.url === 'string'\n}\n\nfunction fileNameExtension(fileName: unknown) {\n if (typeof fileName !== 'string' || !fileName.includes('.')) return undefined\n return fileName.split('.').pop()\n}\n\n/**\n * Find the format of a fal file from its file name, then its URL extension,\n * then its content type. Returns `undefined` when the file is not a mesh\n * format that `Model3DFormat` names (for example a PNG texture).\n */\nfunction detectFormat(file: FalFileLike) {\n const extension =\n fileNameExtension(file.file_name) ?? extractUrlExtension(file.url)\n const byExtension = extension\n ? FORMAT_BY_EXTENSION[extension.toLowerCase()]\n : undefined\n if (byExtension) return byExtension\n if (typeof file.content_type !== 'string') return undefined\n const mimeType = file.content_type.split(';')[0]?.trim().toLowerCase()\n return mimeType ? FORMAT_BY_CONTENT_TYPE[mimeType] : undefined\n}\n\n/** A mesh file. Unlike a texture, a mesh always has a format. */\ntype Model3DMeshFile = Model3DFile & { format: Model3DFormat }\n\nfunction contentTypeField(file: FalFileLike) {\n return typeof file.content_type === 'string'\n ? { contentType: file.content_type }\n : {}\n}\n\nfunction toMeshFile(\n value: unknown,\n role: Model3DFileRole,\n knownFormat?: Model3DFormat,\n) {\n if (!isFalFile(value)) return undefined\n const format = detectFormat(value) ?? knownFormat\n if (!format) return undefined\n const file: Model3DMeshFile = {\n url: value.url,\n format,\n role,\n ...contentTypeField(value),\n }\n return file\n}\n\n/**\n * Read every mesh file from a fal 3D output, in the order the mapper prefers\n * them, without two files that share a URL. Files that are not a\n * `Model3DFormat` (textures, MTL files, Gaussian splats) are left out.\n */\nfunction collectMeshFiles(output: Record<string, unknown>) {\n const files: Array<Model3DMeshFile> = []\n const add = (\n value: unknown,\n role: Model3DFileRole,\n knownFormat?: Model3DFormat,\n ) => {\n const file = toMeshFile(value, role, knownFormat)\n const isNewFile = file && !files.some((seen) => seen.url === file.url)\n if (file && isNewFile) files.push(file)\n }\n\n for (const field of PBR_FIELDS) add(output[field], 'pbr')\n add(output.model_glb, 'base', 'glb')\n const modelUrls = isRecord(output.model_urls) ? output.model_urls : {}\n for (const format of MODEL_URL_FORMATS) add(modelUrls[format], 'base', format)\n for (const field of BASE_FIELDS) add(output[field], 'base')\n for (const field of RIGGED_FIELDS) add(output[field], 'rigged')\n for (const field of ANIMATION_FIELDS) add(output[field], 'animation')\n const basicAnimations = isRecord(output.basic_animations)\n ? Object.values(output.basic_animations)\n : []\n for (const animation of basicAnimations) add(animation, 'animation')\n for (const field of PART_LIST_FIELDS) {\n const parts = output[field]\n if (!Array.isArray(parts)) continue\n for (const part of parts) add(part, 'part')\n }\n return files\n}\n\n/**\n * Read the texture files of a fal 3D output: the `textures` images (Rodin),\n * the `base_color`, `metallic`, `normal`, and `roughness` files of each\n * `texture_urls` entry (Meshy), and the `texture` and `material_mtl` files\n * (Hunyuan3D rapid). They have the role `'texture'` and no `format`.\n */\nfunction collectTextureFiles(output: Record<string, unknown>) {\n const values: Array<unknown> = []\n if (Array.isArray(output.textures)) values.push(...output.textures)\n const textureSets = Array.isArray(output.texture_urls)\n ? output.texture_urls\n : []\n for (const textureSet of textureSets) {\n if (isRecord(textureSet)) values.push(...Object.values(textureSet))\n }\n for (const field of TEXTURE_FIELDS) values.push(output[field])\n\n const files: Array<Model3DFile> = []\n for (const value of values) {\n if (!isFalFile(value)) continue\n files.push({ url: value.url, role: 'texture', ...contentTypeField(value) })\n }\n return files\n}\n\n/** The first GLB in the list, else the first file. */\nfunction pickMainFile(files: ReadonlyArray<Model3DMeshFile>) {\n return files.find((file) => file.format === 'glb') ?? files[0]\n}\n\nfunction findPreviewUrl(output: Record<string, unknown>) {\n for (const field of PREVIEW_FIELDS) {\n const preview = output[field]\n if (isFalFile(preview)) return preview.url\n }\n return undefined\n}\n\n/**\n * Map the output of any fal 3D endpoint to a `Model3DResult`. One generic\n * mapper reads the known output fields, so there is no table per model.\n *\n * `url` is the best mesh of the PBR and base files: the first GLB in the\n * order `pbr_model`, `model_glb_pbr`, `model_glb`, `model_urls.glb`,\n * `model_mesh`, `base_model`. When there is no GLB, it is the first\n * non-GLB file in that order, with `model_urls` in the order gltf, fbx,\n * usdz, obj, stl. When the output has no PBR or base file, the same rule\n * runs on the rigged, animated, and part files. `files` holds every mesh\n * file with its format and role, the main file included, and then the\n * texture files with the role `'texture'` and no format.\n *\n * `previewImageUrl` comes from `rendered_image` or `thumbnail`.\n *\n * Throws when the output has no mesh file.\n */\nexport function mapFalModel3DOutput(jobId: string, output: unknown) {\n const fields = isRecord(output) ? output : {}\n const meshFiles = collectMeshFiles(fields)\n const primaryFiles = meshFiles.filter(\n (file) => file.role === 'pbr' || file.role === 'base',\n )\n const main = pickMainFile(primaryFiles) ?? pickMainFile(meshFiles)\n if (!main) {\n const fieldNames = Object.keys(fields).join(', ') || 'none'\n throw new Error(\n `fal: job ${jobId} returned no 3D model file. Output fields: ${fieldNames}.`,\n )\n }\n const previewImageUrl = findPreviewUrl(fields)\n return {\n jobId,\n url: main.url,\n format: main.format,\n files: [...meshFiles, ...collectTextureFiles(fields)],\n ...(previewImageUrl ? { previewImageUrl } : {}),\n }\n}\n"],"mappings":"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"}
@@ -1,4 +1,4 @@
1
- //#region src/utils/billing.ts
1
+ // src/utils/billing.ts
2
2
  /**
3
3
  * Response header fal sets on a queue *result* fetch carrying the real billed
4
4
  * quantity for the generation, denominated in the endpoint's priced unit.
@@ -97,7 +97,6 @@ function createBillingFetch(baseFetch = globalThis.fetch) {
97
97
  return response;
98
98
  };
99
99
  }
100
- //#endregion
101
100
  export { buildFalUsage, createBillingFetch, parseBillableUnits, recordBillableUnitsFromResponse, takeBillableUnits };
102
101
 
103
102
  //# sourceMappingURL=billing.js.map