@howells/motif-sdk 0.10.0 → 0.12.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/image.d.ts +20 -4
- package/dist/image.js +55 -2
- package/dist/index.cjs +4 -1
- package/dist/index.d.cts +16 -8
- package/dist/index.d.ts +16 -8
- package/dist/index.js +3 -1
- package/package.json +1 -1
package/dist/image.d.ts
CHANGED
|
@@ -14,7 +14,7 @@ declare class MotifError extends Error {
|
|
|
14
14
|
* Public types for the provider-agnostic image generation + editing layer
|
|
15
15
|
* (`@howells/motif-sdk/image`).
|
|
16
16
|
*
|
|
17
|
-
* This layer is additive: it sits alongside the fal-specific `
|
|
17
|
+
* This layer is additive: it sits alongside the fal-specific `FalClient`
|
|
18
18
|
* surface and reuses the SDK's Result convention (`Result<T, MotifError>` — no
|
|
19
19
|
* thrown exceptions). See docs/design/provider-agnostic-image-layer.md.
|
|
20
20
|
*/
|
|
@@ -97,6 +97,12 @@ interface GenerateImageOptions {
|
|
|
97
97
|
seed?: number;
|
|
98
98
|
/** Abort signal to cancel the in-flight request. */
|
|
99
99
|
signal?: AbortSignal;
|
|
100
|
+
/**
|
|
101
|
+
* Extra HTTP headers forwarded to the provider request. Fal's non-retained IO
|
|
102
|
+
* (paired with FalClient.deletePayloads) is
|
|
103
|
+
* `headers: { "X-Fal-Store-IO": "0" }`.
|
|
104
|
+
*/
|
|
105
|
+
headers?: Record<string, string>;
|
|
100
106
|
/**
|
|
101
107
|
* Provider-specific options, passed straight through to the underlying model
|
|
102
108
|
* as body parameters. Outer key = provider name, inner key = option name.
|
|
@@ -138,6 +144,12 @@ interface EditImageOptions {
|
|
|
138
144
|
seed?: number;
|
|
139
145
|
/** Abort signal to cancel the in-flight request. */
|
|
140
146
|
signal?: AbortSignal;
|
|
147
|
+
/**
|
|
148
|
+
* Extra HTTP headers forwarded to the provider request. Fal's non-retained IO
|
|
149
|
+
* (paired with FalClient.deletePayloads) is
|
|
150
|
+
* `headers: { "X-Fal-Store-IO": "0" }`.
|
|
151
|
+
*/
|
|
152
|
+
headers?: Record<string, string>;
|
|
141
153
|
/** Provider-specific options (see {@link GenerateImageOptions.providerOptions}). */
|
|
142
154
|
providerOptions?: Record<string, Record<string, unknown>>;
|
|
143
155
|
}
|
|
@@ -352,7 +364,7 @@ declare const REPLICATE_API_KEY_ENV = "REPLICATE_API_TOKEN";
|
|
|
352
364
|
* Builds a Vercel AI SDK `ImageModel` from `@ai-sdk/fal`. Building a model
|
|
353
365
|
* performs no network I/O — the request only happens when `generateImage`
|
|
354
366
|
* invokes `model.doGenerate`. This is the lightweight fal *image* adapter; the
|
|
355
|
-
* richer `
|
|
367
|
+
* richer `FalClient` fal client (queue, upload, upscale, rmbg, video, tools)
|
|
356
368
|
* is a separate, later fold (design doc §8, phase 1d).
|
|
357
369
|
*
|
|
358
370
|
* ENDPOINT QUIRK (Phase 0): fal's gpt-image endpoint wants `image_size` as a
|
|
@@ -368,7 +380,11 @@ declare const REPLICATE_API_KEY_ENV = "REPLICATE_API_TOKEN";
|
|
|
368
380
|
* });
|
|
369
381
|
*/
|
|
370
382
|
|
|
371
|
-
/**
|
|
383
|
+
/**
|
|
384
|
+
* Tier → fal model id. For fal, explicit `model:` endpoint ids are the primary
|
|
385
|
+
* path (any fal endpoint resolves via passthrough); this tier map is a
|
|
386
|
+
* convenience covering the two most common (FLUX Pro Ultra + gpt-image).
|
|
387
|
+
*/
|
|
372
388
|
declare const FAL_TIER_MODELS: Readonly<Record<ImageTier, string>>;
|
|
373
389
|
/** Env var read for the fal key when `apiKey` is not supplied in config. */
|
|
374
390
|
declare const FAL_API_KEY_ENV = "FAL_KEY";
|
|
@@ -400,7 +416,7 @@ declare function costForImages(provider: ImageProviderId, modelId: string, provi
|
|
|
400
416
|
* `@howells/motif-sdk/image` — provider-agnostic image generation + editing.
|
|
401
417
|
*
|
|
402
418
|
* ESM-only subpath export, built on the Vercel AI SDK image interface
|
|
403
|
-
* (`generateImage`, `@ai-sdk/*`). Additive to the fal-specific `
|
|
419
|
+
* (`generateImage`, `@ai-sdk/*`). Additive to the fal-specific `FalClient`
|
|
404
420
|
* surface; reuses the SDK's Result convention (`Result<T, MotifError>` — no
|
|
405
421
|
* thrown exceptions). Google (Gemini) is the only provider in Phase 1a.
|
|
406
422
|
*
|
package/dist/image.js
CHANGED
|
@@ -1291,8 +1291,58 @@ var FAL_TIER_MODELS = {
|
|
|
1291
1291
|
};
|
|
1292
1292
|
var FAL_API_KEY_ENV = "FAL_KEY";
|
|
1293
1293
|
var FAL_IMAGE_PRICE_USD = {
|
|
1294
|
+
// FLUX family.
|
|
1294
1295
|
[FAL_FLUX_MODEL]: MODELS.flux?.pricePerImageUsd ?? 0.06,
|
|
1295
|
-
|
|
1296
|
+
// MODELS.flux
|
|
1297
|
+
"fal-ai/flux/schnell": MODELS["flux-fast"]?.pricePerImageUsd ?? 3e-3,
|
|
1298
|
+
// MODELS["flux-fast"]
|
|
1299
|
+
// FLUX.2 family.
|
|
1300
|
+
"fal-ai/flux-2-max": MODELS["flux2-max"]?.pricePerImageUsd ?? 0.07,
|
|
1301
|
+
// MODELS["flux2-max"]
|
|
1302
|
+
"fal-ai/flux-2-pro": MODELS["flux2-pro"]?.pricePerImageUsd ?? 0.03,
|
|
1303
|
+
// MODELS["flux2-pro"]
|
|
1304
|
+
"fal-ai/flux-2-flex": MODELS["flux2-flex"]?.pricePerImageUsd ?? 0.05,
|
|
1305
|
+
// MODELS["flux2-flex"]
|
|
1306
|
+
"fal-ai/flux-2": MODELS["flux2-dev"]?.pricePerImageUsd ?? 0.012,
|
|
1307
|
+
// MODELS["flux2-dev"]
|
|
1308
|
+
"fal-ai/flux-2/turbo": MODELS["flux2-turbo"]?.pricePerImageUsd ?? 8e-3,
|
|
1309
|
+
// MODELS["flux2-turbo"]
|
|
1310
|
+
// gpt-image (fal adds overhead vs OpenAI-direct — see design doc §10).
|
|
1311
|
+
[FAL_GPT_IMAGE_MODEL]: MODELS.gpt?.pricePerImageUsd ?? 0.133,
|
|
1312
|
+
// MODELS.gpt
|
|
1313
|
+
"openai/gpt-image-2": MODELS.gpt2?.pricePerImageUsd ?? 0.211,
|
|
1314
|
+
// MODELS.gpt2
|
|
1315
|
+
// Nano Banana (Gemini image) family.
|
|
1316
|
+
"fal-ai/nano-banana-2": MODELS.banana2?.pricePerImageUsd ?? 0.08,
|
|
1317
|
+
// MODELS.banana2
|
|
1318
|
+
"fal-ai/nano-banana-pro": MODELS.banana?.pricePerImageUsd ?? 0.15,
|
|
1319
|
+
// MODELS.banana
|
|
1320
|
+
"fal-ai/gemini-25-flash-image": MODELS.gemini?.pricePerImageUsd ?? 0.0398,
|
|
1321
|
+
// MODELS.gemini
|
|
1322
|
+
"fal-ai/gemini-3-pro-image-preview": MODELS.gemini3?.pricePerImageUsd ?? 0.15,
|
|
1323
|
+
// MODELS.gemini3
|
|
1324
|
+
// Seedream family.
|
|
1325
|
+
"fal-ai/bytedance/seedream/v4/text-to-image": MODELS.seedream4?.pricePerImageUsd ?? 0.03,
|
|
1326
|
+
// MODELS.seedream4
|
|
1327
|
+
"fal-ai/bytedance/seedream/v4.5/text-to-image": MODELS.seedream45?.pricePerImageUsd ?? 0.04,
|
|
1328
|
+
// MODELS.seedream45
|
|
1329
|
+
"bytedance/seedream/v5/pro/text-to-image": MODELS.seedream5?.pricePerImageUsd ?? 0.0675,
|
|
1330
|
+
// MODELS.seedream5
|
|
1331
|
+
"fal-ai/bytedance/seedream/v5/lite/text-to-image": MODELS["seedream5-lite"]?.pricePerImageUsd ?? 0.035,
|
|
1332
|
+
// MODELS["seedream5-lite"]
|
|
1333
|
+
// Other priced fal generation endpoints.
|
|
1334
|
+
"fal-ai/recraft-v3": MODELS.recraft?.pricePerImageUsd ?? 0.04,
|
|
1335
|
+
// MODELS.recraft
|
|
1336
|
+
"fal-ai/recraft/v4/text-to-image": MODELS.recraft4?.pricePerImageUsd ?? 0.04,
|
|
1337
|
+
// MODELS.recraft4
|
|
1338
|
+
"fal-ai/ideogram/v3": MODELS.ideogram?.pricePerImageUsd ?? 0.03,
|
|
1339
|
+
// MODELS.ideogram
|
|
1340
|
+
"ideogram/v4": MODELS.ideogram4?.pricePerImageUsd ?? 0.03,
|
|
1341
|
+
// MODELS.ideogram4
|
|
1342
|
+
"xai/grok-imagine-image": MODELS["grok-image"]?.pricePerImageUsd ?? 0.02,
|
|
1343
|
+
// MODELS["grok-image"]
|
|
1344
|
+
"fal-ai/qwen-image": MODELS.qwen?.pricePerImageUsd ?? 0.02
|
|
1345
|
+
// MODELS.qwen
|
|
1296
1346
|
};
|
|
1297
1347
|
function resolveModel(modelId, apiKey) {
|
|
1298
1348
|
const key = apiKey ?? process.env[FAL_API_KEY_ENV];
|
|
@@ -1505,6 +1555,7 @@ function createMotifImage(config = {}, deps = {}) {
|
|
|
1505
1555
|
...opts.aspectRatio === void 0 ? {} : { aspectRatio: opts.aspectRatio },
|
|
1506
1556
|
...opts.seed === void 0 ? {} : { seed: opts.seed },
|
|
1507
1557
|
...opts.signal === void 0 ? {} : { abortSignal: opts.signal },
|
|
1558
|
+
...opts.headers === void 0 ? {} : { headers: opts.headers },
|
|
1508
1559
|
...opts.providerOptions === void 0 ? {} : { providerOptions: toProviderOptions(opts.providerOptions) }
|
|
1509
1560
|
});
|
|
1510
1561
|
return ok2(toMotifImageResult(result, provider, modelId));
|
|
@@ -1527,6 +1578,7 @@ function createMotifImage(config = {}, deps = {}) {
|
|
|
1527
1578
|
...opts.n === void 0 ? {} : { n: opts.n },
|
|
1528
1579
|
...opts.seed === void 0 ? {} : { seed: opts.seed },
|
|
1529
1580
|
...opts.signal === void 0 ? {} : { abortSignal: opts.signal },
|
|
1581
|
+
...opts.headers === void 0 ? {} : { headers: opts.headers },
|
|
1530
1582
|
...opts.providerOptions === void 0 ? {} : { providerOptions: toProviderOptions(opts.providerOptions) }
|
|
1531
1583
|
});
|
|
1532
1584
|
return ok2(toMotifImageResult(result, provider, modelId));
|
|
@@ -1739,7 +1791,8 @@ function toMotifError(error) {
|
|
|
1739
1791
|
}
|
|
1740
1792
|
const message = error instanceof Error ? error.message : String(error);
|
|
1741
1793
|
const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : void 0;
|
|
1742
|
-
|
|
1794
|
+
const status = error instanceof Error && "statusCode" in error && typeof error.statusCode === "number" ? error.statusCode : 0;
|
|
1795
|
+
return new MotifError(message, status, code);
|
|
1743
1796
|
}
|
|
1744
1797
|
export {
|
|
1745
1798
|
FAL_API_KEY_ENV,
|
package/dist/index.cjs
CHANGED
|
@@ -29,6 +29,7 @@ __export(src_exports, {
|
|
|
29
29
|
FAL_TOOLS_CHECKED_AT: () => FAL_TOOLS_CHECKED_AT,
|
|
30
30
|
FAL_TOOL_IDS: () => FAL_TOOL_IDS,
|
|
31
31
|
FORMAT_PRESETS: () => FORMAT_PRESETS,
|
|
32
|
+
FalClient: () => FalClient,
|
|
32
33
|
GENERATION_MODELS: () => GENERATION_MODELS,
|
|
33
34
|
IDEOGRAM_STYLES: () => IDEOGRAM_STYLES,
|
|
34
35
|
IMAGE_EDITING_TOP_20: () => IMAGE_EDITING_TOP_20,
|
|
@@ -2714,7 +2715,7 @@ var FAL_BASE_URL = "https://fal.run";
|
|
|
2714
2715
|
var FAL_QUEUE_URL = "https://queue.fal.run";
|
|
2715
2716
|
var FAL_API_URL = "https://api.fal.ai";
|
|
2716
2717
|
var FAL_REST_URL = "https://rest.alpha.fal.ai";
|
|
2717
|
-
var
|
|
2718
|
+
var FalClient = class {
|
|
2718
2719
|
apiKey;
|
|
2719
2720
|
timeout;
|
|
2720
2721
|
retries;
|
|
@@ -3236,6 +3237,7 @@ var MotifServer = class {
|
|
|
3236
3237
|
});
|
|
3237
3238
|
}
|
|
3238
3239
|
};
|
|
3240
|
+
var MotifServer = FalClient;
|
|
3239
3241
|
var MotifError = class extends Error {
|
|
3240
3242
|
status;
|
|
3241
3243
|
code;
|
|
@@ -3269,6 +3271,7 @@ function toMotifError(error) {
|
|
|
3269
3271
|
FAL_TOOLS_CHECKED_AT,
|
|
3270
3272
|
FAL_TOOL_IDS,
|
|
3271
3273
|
FORMAT_PRESETS,
|
|
3274
|
+
FalClient,
|
|
3272
3275
|
GENERATION_MODELS,
|
|
3273
3276
|
IDEOGRAM_STYLES,
|
|
3274
3277
|
IMAGE_EDITING_TOP_20,
|
package/dist/index.d.cts
CHANGED
|
@@ -388,13 +388,15 @@ interface JobStatus {
|
|
|
388
388
|
status: "queued" | "processing" | "completed" | "failed";
|
|
389
389
|
}
|
|
390
390
|
/** ─── Configuration ──────────────────────────────────────────── */
|
|
391
|
-
interface
|
|
391
|
+
interface FalClientConfig {
|
|
392
392
|
apiKey: string;
|
|
393
393
|
/** Max retry attempts for 429/5xx errors (default 3, set 0 to disable) */
|
|
394
394
|
retries?: number;
|
|
395
395
|
/** Request timeout in ms (default 120_000) */
|
|
396
396
|
timeout?: number;
|
|
397
397
|
}
|
|
398
|
+
/** @deprecated Renamed to {@link FalClientConfig}. */
|
|
399
|
+
type MotifServerConfig = FalClientConfig;
|
|
398
400
|
|
|
399
401
|
/** Ordered by popularity: square first, then common ratios */
|
|
400
402
|
declare const ASPECT_RATIOS: AspectRatio[];
|
|
@@ -475,16 +477,20 @@ declare const RECRAFT_STYLES: readonly ["realistic_image", "realistic_image/b_an
|
|
|
475
477
|
declare const IDEOGRAM_STYLES: readonly ["AUTO", "GENERAL", "REALISTIC", "DESIGN"];
|
|
476
478
|
|
|
477
479
|
/**
|
|
478
|
-
*
|
|
480
|
+
* FalClient — the fal-native client.
|
|
481
|
+
*
|
|
482
|
+
* The low-level, fal-specific client for AI image generation and fal utilities
|
|
483
|
+
* (queue, upload, upscale, rmbg, video, tools, generate). Pairs with the
|
|
484
|
+
* provider-agnostic `createMotifImage` (`@howells/motif-sdk/image`) as the
|
|
485
|
+
* fal-native entry point.
|
|
479
486
|
*
|
|
480
|
-
* Server-side SDK for AI image generation via fal.ai.
|
|
481
487
|
* All async methods return `Result<T, MotifError>` — no thrown exceptions.
|
|
482
488
|
*
|
|
483
489
|
* @example
|
|
484
490
|
* ```typescript
|
|
485
|
-
* import {
|
|
491
|
+
* import { FalClient } from "./fal";
|
|
486
492
|
*
|
|
487
|
-
* const motif = new
|
|
493
|
+
* const motif = new FalClient(process.env.FAL_KEY!);
|
|
488
494
|
* const result = await motif.generate({ prompt: "a red balloon", model: "banana" });
|
|
489
495
|
*
|
|
490
496
|
* if (result.isOk()) {
|
|
@@ -494,11 +500,11 @@ declare const IDEOGRAM_STYLES: readonly ["AUTO", "GENERAL", "REALISTIC", "DESIGN
|
|
|
494
500
|
* }
|
|
495
501
|
* ```
|
|
496
502
|
*/
|
|
497
|
-
declare class
|
|
503
|
+
declare class FalClient {
|
|
498
504
|
private readonly apiKey;
|
|
499
505
|
private readonly timeout;
|
|
500
506
|
private readonly retries;
|
|
501
|
-
constructor(config:
|
|
507
|
+
constructor(config: FalClientConfig | string);
|
|
502
508
|
/** ─── Synchronous Generation ──────────────────────────────── */
|
|
503
509
|
/** Generate images synchronously (blocks until fal.ai returns). */
|
|
504
510
|
generate(options: GenerateOptions): Promise<Result<MotifResponse, MotifError>>;
|
|
@@ -924,6 +930,8 @@ declare class MotifServer {
|
|
|
924
930
|
*/
|
|
925
931
|
private normalizeResponse;
|
|
926
932
|
}
|
|
933
|
+
/** @deprecated Renamed to {@link FalClient}. `MotifServer` is kept as an alias for backwards compatibility and will be removed in 1.0. */
|
|
934
|
+
declare const MotifServer: typeof FalClient;
|
|
927
935
|
declare class MotifError extends Error {
|
|
928
936
|
readonly status: number;
|
|
929
937
|
readonly code?: string;
|
|
@@ -1320,4 +1328,4 @@ type FalToolId = (typeof FAL_TOOL_IDS)[number];
|
|
|
1320
1328
|
declare function isFalToolId(tool: string): tool is FalToolId;
|
|
1321
1329
|
declare function buildFalToolRequest(options: FalToolRunOptions): FalToolRequest;
|
|
1322
1330
|
|
|
1323
|
-
export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, MotifServer, type MotifServerConfig, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, enrichPrompt, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv, sanitizePrompt };
|
|
1331
|
+
export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, FalClient, type FalClientConfig, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, MotifServer, type MotifServerConfig, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, enrichPrompt, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv, sanitizePrompt };
|
package/dist/index.d.ts
CHANGED
|
@@ -388,13 +388,15 @@ interface JobStatus {
|
|
|
388
388
|
status: "queued" | "processing" | "completed" | "failed";
|
|
389
389
|
}
|
|
390
390
|
/** ─── Configuration ──────────────────────────────────────────── */
|
|
391
|
-
interface
|
|
391
|
+
interface FalClientConfig {
|
|
392
392
|
apiKey: string;
|
|
393
393
|
/** Max retry attempts for 429/5xx errors (default 3, set 0 to disable) */
|
|
394
394
|
retries?: number;
|
|
395
395
|
/** Request timeout in ms (default 120_000) */
|
|
396
396
|
timeout?: number;
|
|
397
397
|
}
|
|
398
|
+
/** @deprecated Renamed to {@link FalClientConfig}. */
|
|
399
|
+
type MotifServerConfig = FalClientConfig;
|
|
398
400
|
|
|
399
401
|
/** Ordered by popularity: square first, then common ratios */
|
|
400
402
|
declare const ASPECT_RATIOS: AspectRatio[];
|
|
@@ -475,16 +477,20 @@ declare const RECRAFT_STYLES: readonly ["realistic_image", "realistic_image/b_an
|
|
|
475
477
|
declare const IDEOGRAM_STYLES: readonly ["AUTO", "GENERAL", "REALISTIC", "DESIGN"];
|
|
476
478
|
|
|
477
479
|
/**
|
|
478
|
-
*
|
|
480
|
+
* FalClient — the fal-native client.
|
|
481
|
+
*
|
|
482
|
+
* The low-level, fal-specific client for AI image generation and fal utilities
|
|
483
|
+
* (queue, upload, upscale, rmbg, video, tools, generate). Pairs with the
|
|
484
|
+
* provider-agnostic `createMotifImage` (`@howells/motif-sdk/image`) as the
|
|
485
|
+
* fal-native entry point.
|
|
479
486
|
*
|
|
480
|
-
* Server-side SDK for AI image generation via fal.ai.
|
|
481
487
|
* All async methods return `Result<T, MotifError>` — no thrown exceptions.
|
|
482
488
|
*
|
|
483
489
|
* @example
|
|
484
490
|
* ```typescript
|
|
485
|
-
* import {
|
|
491
|
+
* import { FalClient } from "./fal";
|
|
486
492
|
*
|
|
487
|
-
* const motif = new
|
|
493
|
+
* const motif = new FalClient(process.env.FAL_KEY!);
|
|
488
494
|
* const result = await motif.generate({ prompt: "a red balloon", model: "banana" });
|
|
489
495
|
*
|
|
490
496
|
* if (result.isOk()) {
|
|
@@ -494,11 +500,11 @@ declare const IDEOGRAM_STYLES: readonly ["AUTO", "GENERAL", "REALISTIC", "DESIGN
|
|
|
494
500
|
* }
|
|
495
501
|
* ```
|
|
496
502
|
*/
|
|
497
|
-
declare class
|
|
503
|
+
declare class FalClient {
|
|
498
504
|
private readonly apiKey;
|
|
499
505
|
private readonly timeout;
|
|
500
506
|
private readonly retries;
|
|
501
|
-
constructor(config:
|
|
507
|
+
constructor(config: FalClientConfig | string);
|
|
502
508
|
/** ─── Synchronous Generation ──────────────────────────────── */
|
|
503
509
|
/** Generate images synchronously (blocks until fal.ai returns). */
|
|
504
510
|
generate(options: GenerateOptions): Promise<Result<MotifResponse, MotifError>>;
|
|
@@ -924,6 +930,8 @@ declare class MotifServer {
|
|
|
924
930
|
*/
|
|
925
931
|
private normalizeResponse;
|
|
926
932
|
}
|
|
933
|
+
/** @deprecated Renamed to {@link FalClient}. `MotifServer` is kept as an alias for backwards compatibility and will be removed in 1.0. */
|
|
934
|
+
declare const MotifServer: typeof FalClient;
|
|
927
935
|
declare class MotifError extends Error {
|
|
928
936
|
readonly status: number;
|
|
929
937
|
readonly code?: string;
|
|
@@ -1320,4 +1328,4 @@ type FalToolId = (typeof FAL_TOOL_IDS)[number];
|
|
|
1320
1328
|
declare function isFalToolId(tool: string): tool is FalToolId;
|
|
1321
1329
|
declare function buildFalToolRequest(options: FalToolRunOptions): FalToolRequest;
|
|
1322
1330
|
|
|
1323
|
-
export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, MotifServer, type MotifServerConfig, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, enrichPrompt, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv, sanitizePrompt };
|
|
1331
|
+
export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, FalClient, type FalClientConfig, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, MotifServer, type MotifServerConfig, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, enrichPrompt, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv, sanitizePrompt };
|
package/dist/index.js
CHANGED
|
@@ -2655,7 +2655,7 @@ var FAL_BASE_URL = "https://fal.run";
|
|
|
2655
2655
|
var FAL_QUEUE_URL = "https://queue.fal.run";
|
|
2656
2656
|
var FAL_API_URL = "https://api.fal.ai";
|
|
2657
2657
|
var FAL_REST_URL = "https://rest.alpha.fal.ai";
|
|
2658
|
-
var
|
|
2658
|
+
var FalClient = class {
|
|
2659
2659
|
apiKey;
|
|
2660
2660
|
timeout;
|
|
2661
2661
|
retries;
|
|
@@ -3177,6 +3177,7 @@ var MotifServer = class {
|
|
|
3177
3177
|
});
|
|
3178
3178
|
}
|
|
3179
3179
|
};
|
|
3180
|
+
var MotifServer = FalClient;
|
|
3180
3181
|
var MotifError = class extends Error {
|
|
3181
3182
|
status;
|
|
3182
3183
|
code;
|
|
@@ -3209,6 +3210,7 @@ export {
|
|
|
3209
3210
|
FAL_TOOLS_CHECKED_AT,
|
|
3210
3211
|
FAL_TOOL_IDS,
|
|
3211
3212
|
FORMAT_PRESETS,
|
|
3213
|
+
FalClient,
|
|
3212
3214
|
GENERATION_MODELS,
|
|
3213
3215
|
IDEOGRAM_STYLES,
|
|
3214
3216
|
IMAGE_EDITING_TOP_20,
|