@ai-sdk/black-forest-labs 0.0.0-1c33ba03-20260114162300 → 0.0.0-4115c213-20260122152721

package/CHANGELOG.md

@@ -1,11 +1,40 @@
 # @ai-sdk/black-forest-labs
 
-## 0.0.0-1c33ba03-20260114162300
+## 0.0.0-4115c213-20260122152721
 
 ### Patch Changes
 
-- Updated dependencies [261c011]
-  - @ai-sdk/provider-utils@0.0.0-1c33ba03-20260114162300
+- 4caafb2: chore: excluded tests from src folder in npm package
+- Updated dependencies [4caafb2]
+  - @ai-sdk/provider@0.0.0-4115c213-20260122152721
+  - @ai-sdk/provider-utils@0.0.0-4115c213-20260122152721
+
+## 1.0.10
+
+### Patch Changes
+
+- 2b8369d: chore: add docs to package dist
+
+## 1.0.9
+
+### Patch Changes
+
+- 8dc54db: chore: add src folders to package bundle
+
+## 1.0.8
+
+### Patch Changes
+
+- Updated dependencies [5c090e7]
+  - @ai-sdk/provider@3.0.4
+  - @ai-sdk/provider-utils@4.0.8
+
+## 1.0.7
+
+### Patch Changes
+
+- Updated dependencies [46f46e4]
+  - @ai-sdk/provider-utils@4.0.7
 
 ## 1.0.6
 

package/dist/index.js

@@ -392,7 +392,7 @@ function bflErrorToMessage(error) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.0.0-1c33ba03-20260114162300" : "0.0.0-test";
+var VERSION = true ? "0.0.0-4115c213-20260122152721" : "0.0.0-test";
 
 // src/black-forest-labs-provider.ts
 var defaultBaseURL = "https://api.bfl.ai/v1";

package/dist/index.mjs

@@ -381,7 +381,7 @@ function bflErrorToMessage(error) {
 }
 
 // src/version.ts
-var VERSION = true ? "0.0.0-1c33ba03-20260114162300" : "0.0.0-test";
+var VERSION = true ? "0.0.0-4115c213-20260122152721" : "0.0.0-test";
 
 // src/black-forest-labs-provider.ts
 var defaultBaseURL = "https://api.bfl.ai/v1";

package/docs/12-black-forest-labs.mdx

@@ -0,0 +1,200 @@
+---
+title: Black Forest Labs
+description: Learn how to use Black Forest Labs models with the AI SDK.
+---
+
+# Black Forest Labs Provider
+
+[Black Forest Labs](https://bfl.ai/) provides a generative image platform for developers with FLUX-based models. Their platform offers fast, high quality, and in-context image generation and editing with precise and coherent results.
+
+## Setup
+
+The Black Forest Labs provider is available via the `@ai-sdk/black-forest-labs` module. You can install it with
+
+<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
+  <Tab>
+    <Snippet text="pnpm add @ai-sdk/black-forest-labs" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="npm install @ai-sdk/black-forest-labs" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="yarn add @ai-sdk/black-forest-labs" dark />
+  </Tab>
+
+  <Tab>
+    <Snippet text="bun add @ai-sdk/black-forest-labs" dark />
+  </Tab>
+</Tabs>
+
+## Provider Instance
+
+You can import the default provider instance `blackForestLabs` from `@ai-sdk/black-forest-labs`:
+
+```ts
+import { blackForestLabs } from '@ai-sdk/black-forest-labs';
+```
+
+If you need a customized setup, you can import `createBlackForestLabs` and create a provider instance with your settings:
+
+```ts
+import { createBlackForestLabs } from '@ai-sdk/black-forest-labs';
+
+const blackForestLabs = createBlackForestLabs({
+  apiKey: 'your-api-key', // optional, defaults to BFL_API_KEY environment variable
+  baseURL: 'custom-url', // optional
+  headers: {
+    /* custom headers */
+  }, // optional
+});
+```
+
+You can use the following optional settings to customize the Black Forest Labs provider instance:
+
+- **baseURL** _string_
+
+  Use a different URL prefix for API calls, e.g. to use a regional endpoint.
+  The default prefix is `https://api.bfl.ai/v1`.
+
+- **apiKey** _string_
+
+  API key that is being sent using the `x-key` header.
+  It defaults to the `BFL_API_KEY` environment variable.
+
+- **headers** _Record&lt;string,string&gt;_
+
+  Custom headers to include in the requests.
+
+- **fetch** _(input: RequestInfo, init?: RequestInit) => Promise&lt;Response&gt;_
+
+  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
+  You can use it as a middleware to intercept requests,
+  or to provide a custom fetch implementation for e.g. testing.
+
+## Image Models
+
+You can create Black Forest Labs image models using the `.image()` factory method.
+For more on image generation with the AI SDK see [generateImage()](/docs/reference/ai-sdk-core/generate-image).
+
+### Basic Usage
+
+```ts
+import { writeFileSync } from 'node:fs';
+import { blackForestLabs } from '@ai-sdk/black-forest-labs';
+import { generateImage } from 'ai';
+
+const { image, providerMetadata } = await generateImage({
+  model: blackForestLabs.image('flux-pro-1.1'),
+  prompt: 'A serene mountain landscape at sunset',
+});
+
+const filename = `image-${Date.now()}.png`;
+writeFileSync(filename, image.uint8Array);
+console.log(`Image saved to ${filename}`);
+```
+
+### Model Capabilities
+
+Black Forest Labs offers many models optimized for different use cases. Here are a few popular examples. For a full list of models, see the [Black Forest Labs Models Page](https://bfl.ai/models).
+
+| Model                | Description                                                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `flux-kontext-pro`   | FLUX.1 Kontext [pro] handles both text and reference images as inputs, enabling targeted edits and complex transformations |
+| `flux-kontext-max`   | FLUX.1 Kontext [max] with improved prompt adherence and typography generation                                              |
+| `flux-pro-1.1-ultra` | Ultra-fast, ultra high-resolution image creation                                                                           |
+| `flux-pro-1.1`       | Fast, high-quality image generation from text.                                                                             |
+
+Black Forest Labs models support aspect ratios from 3:7 (portrait) to 7:3 (landscape).
+
+### Image Editing
+
+Black Forest Labs Kontext models support powerful image editing capabilities using reference images. Pass input images via `prompt.images` to transform, combine, or edit existing images.
+
+#### Single Image Editing
+
+Transform an existing image using text prompts:
+
+```ts
+import {
+  blackForestLabs,
+  BlackForestLabsImageProviderOptions,
+} from '@ai-sdk/black-forest-labs';
+import { generateImage } from 'ai';
+
+const { images } = await generateImage({
+  model: blackForestLabs.image('flux-kontext-pro'),
+  prompt: {
+    text: 'A baby elephant with a shirt that has the logo from the input image.',
+    images: [
+      'https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png',
+    ],
+  },
+  providerOptions: {
+    blackForestLabs: {
+      width: 1024,
+      height: 768,
+    } satisfies BlackForestLabsImageProviderOptions,
+  },
+});
+```
+
+#### Multi-Reference Editing
+
+Combine multiple reference images for complex transformations. Black Forest Labs supports up to 10 input images:
+
+```ts
+import { blackForestLabs } from '@ai-sdk/black-forest-labs';
+import { generateImage } from 'ai';
+
+const { images } = await generateImage({
+  model: blackForestLabs.image('flux-kontext-pro'),
+  prompt: {
+    text: 'Combine the style of image 1 with the subject of image 2',
+    images: [
+      'https://example.com/style-reference.jpg',
+      'https://example.com/subject-reference.jpg',
+    ],
+  },
+});
+```
+
+<Note>
+  Input images can be provided as URLs or base64-encoded strings. They support
+  up to 20MB or 20 megapixels per image.
+</Note>
+
+### Provider Options
+
+Black Forest Labs image models support flexible provider options through the `providerOptions.blackForestLabs` object. The supported parameters depend on the used model ID:
+
+- **width** _number_ - Output width in pixels (256–1920). When set, this overrides any width derived from `size`.
+- **height** _number_ - Output height in pixels (256–1920). When set, this overrides any height derived from `size`.
+- **outputFormat** _string_ - Desired format of the output image (`"jpeg"` or `"png"`).
+- **steps** _number_ - Number of inference steps. Higher values may improve quality but increase generation time.
+- **guidance** _number_ - Guidance scale for generation. Higher values follow the prompt more closely.
+- **imagePrompt** _string_ - Base64-encoded image to use as additional visual context for generation.
+- **imagePromptStrength** _number_ - Strength of the image prompt influence on generation (0.0 to 1.0).
+- **promptUpsampling** _boolean_ - If true, performs upsampling on the prompt.
+- **raw** _boolean_ - Enable raw mode for more natural, authentic aesthetics.
+- **safetyTolerance** _number_ - Moderation level for inputs and outputs (0 = most strict, 6 = more permissive).
+- **pollIntervalMillis** _number_ - Interval in milliseconds between polling attempts (default 500ms).
+- **pollTimeoutMillis** _number_ - Overall timeout in milliseconds for polling before timing out (default 60s).
+- **webhookUrl** _string_ - URL for asynchronous completion notification. Must be a valid HTTP/HTTPS URL.
+- **webhookSecret** _string_ - Secret for webhook signature verification, sent in the `X-Webhook-Secret` header.
+
+<Note>
+  To pass reference images for editing, use `prompt.images` instead of provider
+  options. This supports up to 10 images as URLs or base64-encoded strings.
+</Note>
+
+### Regional Endpoints
+
+By default, requests are sent to `https://api.bfl.ai/v1`. You can select a [regional endpoint](https://docs.bfl.ai/api_integration/integration_guidelines#regional-endpoints) by setting `baseURL` when creating the provider instance:
+
+```ts
+import { createBlackForestLabs } from '@ai-sdk/black-forest-labs';
+
+const blackForestLabs = createBlackForestLabs({
+  baseURL: 'https://api.eu.bfl.ai/v1', // or https://api.us.bfl.ai/v1
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/black-forest-labs",
-  "version": "0.0.0-1c33ba03-20260114162300",
+  "version": "0.0.0-4115c213-20260122152721",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -8,8 +8,17 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
+    "docs/**/*",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "!src/**/__snapshots__",
+    "!src/**/__fixtures__",
     "CHANGELOG.md"
   ],
+  "directories": {
+    "doc": "./docs"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -19,15 +28,15 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "3.0.3",
-    "@ai-sdk/provider-utils": "0.0.0-1c33ba03-20260114162300"
+    "@ai-sdk/provider": "0.0.0-4115c213-20260122152721",
+    "@ai-sdk/provider-utils": "0.0.0-4115c213-20260122152721"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
     "tsup": "^8",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "1.0.1",
+    "@ai-sdk/test-server": "0.0.0-4115c213-20260122152721",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {
@@ -53,7 +62,7 @@
   "scripts": {
     "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
     "build:watch": "pnpm clean && tsup --watch",
-    "clean": "del-cli dist *.tsbuildinfo",
+    "clean": "del-cli dist docs *.tsbuildinfo",
     "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --build",
     "prettier-check": "prettier --check \"./**/*.ts*\"",

package/src/black-forest-labs-image-model.ts

@@ -0,0 +1,473 @@
+import type { ImageModelV3, SharedV3Warning } from '@ai-sdk/provider';
+import type { InferSchema, Resolvable } from '@ai-sdk/provider-utils';
+import {
+  FetchFunction,
+  combineHeaders,
+  createBinaryResponseHandler,
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
+  createStatusCodeErrorResponseHandler,
+  delay,
+  getFromApi,
+  lazySchema,
+  parseProviderOptions,
+  postJsonToApi,
+  resolve,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import type { BlackForestLabsAspectRatio } from './black-forest-labs-image-settings';
+import { BlackForestLabsImageModelId } from './black-forest-labs-image-settings';
+
+const DEFAULT_POLL_INTERVAL_MILLIS = 500;
+const DEFAULT_POLL_TIMEOUT_MILLIS = 60000;
+
+interface BlackForestLabsImageModelConfig {
+  provider: string;
+  baseURL: string;
+  headers?: Resolvable<Record<string, string | undefined>>;
+  fetch?: FetchFunction;
+  /**
+   Poll interval in milliseconds between status checks. Defaults to 500ms.
+   */
+  pollIntervalMillis?: number;
+  /**
+   Overall timeout in milliseconds for polling before giving up. Defaults to 60s.
+   */
+  pollTimeoutMillis?: number;
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+export class BlackForestLabsImageModel implements ImageModelV3 {
+  readonly specificationVersion = 'v3';
+  readonly maxImagesPerCall = 1;
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: BlackForestLabsImageModelId,
+    private readonly config: BlackForestLabsImageModelConfig,
+  ) {}
+
+  private async getArgs({
+    prompt,
+    files,
+    mask,
+    size,
+    aspectRatio,
+    seed,
+    providerOptions,
+  }: Parameters<ImageModelV3['doGenerate']>[0]) {
+    const warnings: Array<SharedV3Warning> = [];
+
+    const finalAspectRatio =
+      aspectRatio ?? (size ? convertSizeToAspectRatio(size) : undefined);
+
+    if (size && !aspectRatio) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'size',
+        details:
+          'Deriving aspect_ratio from size. Use the width and height provider options to specify dimensions for models that support them.',
+      });
+    } else if (size && aspectRatio) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'size',
+        details:
+          'Black Forest Labs ignores size when aspectRatio is provided. Use the width and height provider options to specify dimensions for models that support them',
+      });
+    }
+
+    const bflOptions = await parseProviderOptions({
+      provider: 'blackForestLabs',
+      providerOptions,
+      schema: blackForestLabsImageProviderOptionsSchema,
+    });
+
+    const [widthStr, heightStr] = size?.split('x') ?? [];
+
+    const inputImages: string[] =
+      files?.map(file => {
+        if (file.type === 'url') {
+          return file.url;
+        }
+
+        if (typeof file.data === 'string') {
+          return file.data;
+        }
+
+        return Buffer.from(file.data).toString('base64');
+      }) || [];
+
+    if (inputImages.length > 10) {
+      throw new Error('Black Forest Labs supports up to 10 input images.');
+    }
+
+    const inputImagesObj: Record<string, string> = inputImages.reduce<
+      Record<string, string>
+    >((acc, img, index) => {
+      acc[`input_image${index === 0 ? '' : `_${index + 1}`}`] = img;
+      return acc;
+    }, {});
+
+    let maskValue: string | undefined;
+    if (mask) {
+      if (mask.type === 'url') {
+        maskValue = mask.url;
+      } else {
+        if (typeof mask.data === 'string') {
+          maskValue = mask.data;
+        } else {
+          maskValue = Buffer.from(mask.data).toString('base64');
+        }
+      }
+    }
+
+    const body: Record<string, unknown> = {
+      prompt,
+      seed,
+      aspect_ratio: finalAspectRatio,
+      width: bflOptions?.width ?? (size ? Number(widthStr) : undefined),
+      height: bflOptions?.height ?? (size ? Number(heightStr) : undefined),
+      steps: bflOptions?.steps,
+      guidance: bflOptions?.guidance,
+      image_prompt_strength: bflOptions?.imagePromptStrength,
+      image_prompt: bflOptions?.imagePrompt,
+      ...inputImagesObj,
+      mask: maskValue,
+      output_format: bflOptions?.outputFormat,
+      prompt_upsampling: bflOptions?.promptUpsampling,
+      raw: bflOptions?.raw,
+      safety_tolerance: bflOptions?.safetyTolerance,
+      webhook_secret: bflOptions?.webhookSecret,
+      webhook_url: bflOptions?.webhookUrl,
+    };
+
+    return { body, warnings };
+  }
+
+  async doGenerate({
+    prompt,
+    files,
+    mask,
+    size,
+    aspectRatio,
+    seed,
+    providerOptions,
+    headers,
+    abortSignal,
+  }: Parameters<ImageModelV3['doGenerate']>[0]): Promise<
+    Awaited<ReturnType<ImageModelV3['doGenerate']>>
+  > {
+    const { body, warnings } = await this.getArgs({
+      prompt,
+      files,
+      mask,
+      size,
+      aspectRatio,
+      seed,
+      providerOptions,
+      n: 1,
+      headers,
+      abortSignal,
+    } as Parameters<ImageModelV3['doGenerate']>[0]);
+
+    const bflOptions = await parseProviderOptions({
+      provider: 'blackForestLabs',
+      providerOptions,
+      schema: blackForestLabsImageProviderOptionsSchema,
+    });
+
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const combinedHeaders = combineHeaders(
+      await resolve(this.config.headers),
+      headers,
+    );
+
+    const submit = await postJsonToApi({
+      url: `${this.config.baseURL}/${this.modelId}`,
+      headers: combinedHeaders,
+      body,
+      failedResponseHandler: bflFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(bflSubmitSchema),
+      abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    const pollUrl = submit.value.polling_url;
+    const requestId = submit.value.id;
+
+    const {
+      imageUrl,
+      seed: resultSeed,
+      start_time: resultStartTime,
+      end_time: resultEndTime,
+      duration: resultDuration,
+    } = await this.pollForImageUrl({
+      pollUrl,
+      requestId,
+      headers: combinedHeaders,
+      abortSignal,
+      pollOverrides: {
+        pollIntervalMillis: bflOptions?.pollIntervalMillis,
+        pollTimeoutMillis: bflOptions?.pollTimeoutMillis,
+      },
+    });
+
+    const { value: imageBytes, responseHeaders } = await getFromApi({
+      url: imageUrl,
+      headers: combinedHeaders,
+      abortSignal,
+      failedResponseHandler: createStatusCodeErrorResponseHandler(),
+      successfulResponseHandler: createBinaryResponseHandler(),
+      fetch: this.config.fetch,
+    });
+
+    return {
+      images: [imageBytes],
+      warnings,
+      providerMetadata: {
+        blackForestLabs: {
+          images: [
+            {
+              ...(resultSeed != null && { seed: resultSeed }),
+              ...(resultStartTime != null && { start_time: resultStartTime }),
+              ...(resultEndTime != null && { end_time: resultEndTime }),
+              ...(resultDuration != null && { duration: resultDuration }),
+              ...(submit.value.cost != null && { cost: submit.value.cost }),
+              ...(submit.value.input_mp != null && {
+                inputMegapixels: submit.value.input_mp,
+              }),
+              ...(submit.value.output_mp != null && {
+                outputMegapixels: submit.value.output_mp,
+              }),
+            },
+          ],
+        },
+      },
+      response: {
+        modelId: this.modelId,
+        timestamp: currentDate,
+        headers: responseHeaders,
+      },
+    };
+  }
+
+  private async pollForImageUrl({
+    pollUrl,
+    requestId,
+    headers,
+    abortSignal,
+    pollOverrides,
+  }: {
+    pollUrl: string;
+    requestId: string;
+    headers: Record<string, string | undefined>;
+    abortSignal: AbortSignal | undefined;
+    pollOverrides?: {
+      pollIntervalMillis?: number;
+      pollTimeoutMillis?: number;
+    };
+  }): Promise<{
+    imageUrl: string;
+    seed?: number;
+    start_time?: number;
+    end_time?: number;
+    duration?: number;
+  }> {
+    const pollIntervalMillis =
+      pollOverrides?.pollIntervalMillis ??
+      this.config.pollIntervalMillis ??
+      DEFAULT_POLL_INTERVAL_MILLIS;
+    const pollTimeoutMillis =
+      pollOverrides?.pollTimeoutMillis ??
+      this.config.pollTimeoutMillis ??
+      DEFAULT_POLL_TIMEOUT_MILLIS;
+    const maxPollAttempts = Math.ceil(
+      pollTimeoutMillis / Math.max(1, pollIntervalMillis),
+    );
+
+    const url = new URL(pollUrl);
+    if (!url.searchParams.has('id')) {
+      url.searchParams.set('id', requestId);
+    }
+
+    for (let i = 0; i < maxPollAttempts; i++) {
+      const { value } = await getFromApi({
+        url: url.toString(),
+        headers,
+        failedResponseHandler: bflFailedResponseHandler,
+        successfulResponseHandler: createJsonResponseHandler(bflPollSchema),
+        abortSignal,
+        fetch: this.config.fetch,
+      });
+
+      const status = value.status;
+      if (status === 'Ready') {
+        if (typeof value.result?.sample === 'string') {
+          return {
+            imageUrl: value.result.sample,
+            seed: value.result.seed ?? undefined,
+            start_time: value.result.start_time ?? undefined,
+            end_time: value.result.end_time ?? undefined,
+            duration: value.result.duration ?? undefined,
+          };
+        }
+        throw new Error(
+          'Black Forest Labs poll response is Ready but missing result.sample',
+        );
+      }
+      if (status === 'Error' || status === 'Failed') {
+        throw new Error('Black Forest Labs generation failed.');
+      }
+
+      await delay(pollIntervalMillis);
+    }
+
+    throw new Error('Black Forest Labs generation timed out.');
+  }
+}
+
+export const blackForestLabsImageProviderOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      imagePrompt: z.string().optional(),
+      imagePromptStrength: z.number().min(0).max(1).optional(),
+      /** @deprecated use prompt.images instead */
+      inputImage: z.string().optional(),
+      /** @deprecated use prompt.images instead */
+      inputImage2: z.string().optional(),
+      /** @deprecated use prompt.images instead */
+      inputImage3: z.string().optional(),
+      /** @deprecated use prompt.images instead */
+      inputImage4: z.string().optional(),
+      /** @deprecated use prompt.images instead */
+      inputImage5: z.string().optional(),
+      /** @deprecated use prompt.images instead */
+      inputImage6: z.string().optional(),
+      /** @deprecated use prompt.images instead */
+      inputImage7: z.string().optional(),
+      /** @deprecated use prompt.images instead */
+      inputImage8: z.string().optional(),
+      /** @deprecated use prompt.images instead */
+      inputImage9: z.string().optional(),
+      /** @deprecated use prompt.images instead */
+      inputImage10: z.string().optional(),
+      steps: z.number().int().positive().optional(),
+      guidance: z.number().min(0).optional(),
+      width: z.number().int().min(256).max(1920).optional(),
+      height: z.number().int().min(256).max(1920).optional(),
+      outputFormat: z.enum(['jpeg', 'png']).optional(),
+      promptUpsampling: z.boolean().optional(),
+      raw: z.boolean().optional(),
+      safetyTolerance: z.number().int().min(0).max(6).optional(),
+      webhookSecret: z.string().optional(),
+      webhookUrl: z.url().optional(),
+      pollIntervalMillis: z.number().int().positive().optional(),
+      pollTimeoutMillis: z.number().int().positive().optional(),
+    }),
+  ),
+);
+
+export type BlackForestLabsImageProviderOptions = InferSchema<
+  typeof blackForestLabsImageProviderOptionsSchema
+>;
+
+function convertSizeToAspectRatio(
+  size: string,
+): BlackForestLabsAspectRatio | undefined {
+  const [wStr, hStr] = size.split('x');
+  const width = Number(wStr);
+  const height = Number(hStr);
+  if (
+    !Number.isFinite(width) ||
+    !Number.isFinite(height) ||
+    width <= 0 ||
+    height <= 0
+  ) {
+    return undefined;
+  }
+  const g = gcd(width, height);
+  return `${Math.round(width / g)}:${Math.round(height / g)}`;
+}
+
+function gcd(a: number, b: number): number {
+  let x = Math.abs(a);
+  let y = Math.abs(b);
+  while (y !== 0) {
+    const t = y;
+    y = x % y;
+    x = t;
+  }
+  return x;
+}
+
+const bflSubmitSchema = z.object({
+  id: z.string(),
+  polling_url: z.url(),
+  cost: z.number().nullish(),
+  input_mp: z.number().nullish(),
+  output_mp: z.number().nullish(),
+});
+
+const bflStatus = z.union([
+  z.literal('Pending'),
+  z.literal('Ready'),
+  z.literal('Error'),
+  z.literal('Failed'),
+  z.literal('Request Moderated'),
+]);
+
+const bflPollSchema = z
+  .object({
+    status: bflStatus.optional(),
+    state: bflStatus.optional(),
+    details: z.unknown().optional(),
+    result: z
+      .object({
+        sample: z.url(),
+        seed: z.number().optional(),
+        start_time: z.number().optional(),
+        end_time: z.number().optional(),
+        duration: z.number().optional(),
+      })
+      .nullish(),
+  })
+  .refine(v => v.status != null || v.state != null, {
+    message: 'Missing status in Black Forest Labs poll response',
+  })
+  .transform(v => ({
+    status: (v.status ?? v.state)!,
+    result: v.result,
+  }));
+
+const bflErrorSchema = z.object({
+  message: z.string().optional(),
+  detail: z.any().optional(),
+});
+
+const bflFailedResponseHandler = createJsonErrorResponseHandler({
+  errorSchema: bflErrorSchema,
+  errorToMessage: error =>
+    bflErrorToMessage(error) ?? 'Unknown Black Forest Labs error',
+});
+
+function bflErrorToMessage(error: unknown): string | undefined {
+  const parsed = bflErrorSchema.safeParse(error);
+  if (!parsed.success) return undefined;
+  const { message, detail } = parsed.data;
+  if (typeof detail === 'string') return detail;
+  if (detail != null) {
+    try {
+      return JSON.stringify(detail);
+    } catch {
+      // ignore
+    }
+  }
+  return message;
+}

package/src/black-forest-labs-image-settings.ts

@@ -0,0 +1,9 @@
+export type BlackForestLabsImageModelId =
+  | 'flux-kontext-pro'
+  | 'flux-kontext-max'
+  | 'flux-pro-1.1-ultra'
+  | 'flux-pro-1.1'
+  | 'flux-pro-1.0-fill'
+  | (string & {});
+
+export type BlackForestLabsAspectRatio = `${number}:${number}`;

package/src/black-forest-labs-provider.ts

@@ -0,0 +1,113 @@
+import { ImageModelV3, NoSuchModelError, ProviderV3 } from '@ai-sdk/provider';
+import type { FetchFunction } from '@ai-sdk/provider-utils';
+import {
+  loadApiKey,
+  withoutTrailingSlash,
+  withUserAgentSuffix,
+} from '@ai-sdk/provider-utils';
+import { BlackForestLabsImageModel } from './black-forest-labs-image-model';
+import { BlackForestLabsImageModelId } from './black-forest-labs-image-settings';
+import { VERSION } from './version';
+
+export interface BlackForestLabsProviderSettings {
+  /**
+Black Forest Labs API key. Default value is taken from the `BFL_API_KEY` environment variable.
+   */
+  apiKey?: string;
+
+  /**
+Base URL for the API calls. Defaults to `https://api.bfl.ai/v1`.
+   */
+  baseURL?: string;
+
+  /**
+Custom headers to include in the requests.
+   */
+  headers?: Record<string, string>;
+
+  /**
+Custom fetch implementation. You can use it as a middleware to intercept
+requests, or to provide a custom fetch implementation for e.g. testing.
+   */
+  fetch?: FetchFunction;
+
+  /**
+ Poll interval in milliseconds between status checks. Defaults to 500ms.
+   */
+  pollIntervalMillis?: number;
+
+  /**
+ Overall timeout in milliseconds for polling before giving up. Defaults to 60s.
+   */
+  pollTimeoutMillis?: number;
+}
+
+export interface BlackForestLabsProvider extends ProviderV3 {
+  /**
+Creates a model for image generation.
+   */
+  image(modelId: BlackForestLabsImageModelId): ImageModelV3;
+
+  /**
+Creates a model for image generation.
+   */
+  imageModel(modelId: BlackForestLabsImageModelId): ImageModelV3;
+
+  /**
+   * @deprecated Use `embeddingModel` instead.
+   */
+  textEmbeddingModel(modelId: string): never;
+}
+
+const defaultBaseURL = 'https://api.bfl.ai/v1';
+
+export function createBlackForestLabs(
+  options: BlackForestLabsProviderSettings = {},
+): BlackForestLabsProvider {
+  const baseURL = withoutTrailingSlash(options.baseURL ?? defaultBaseURL);
+  const getHeaders = () =>
+    withUserAgentSuffix(
+      {
+        'x-key': loadApiKey({
+          apiKey: options.apiKey,
+          environmentVariableName: 'BFL_API_KEY',
+          description: 'Black Forest Labs',
+        }),
+        ...options.headers,
+      },
+      `ai-sdk/black-forest-labs/${VERSION}`,
+    );
+
+  const createImageModel = (modelId: BlackForestLabsImageModelId) =>
+    new BlackForestLabsImageModel(modelId, {
+      provider: 'black-forest-labs.image',
+      baseURL: baseURL ?? defaultBaseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+      pollIntervalMillis: options.pollIntervalMillis,
+      pollTimeoutMillis: options.pollTimeoutMillis,
+    });
+
+  const embeddingModel = (modelId: string) => {
+    throw new NoSuchModelError({
+      modelId,
+      modelType: 'embeddingModel',
+    });
+  };
+
+  return {
+    specificationVersion: 'v3',
+    imageModel: createImageModel,
+    image: createImageModel,
+    languageModel: (modelId: string) => {
+      throw new NoSuchModelError({
+        modelId,
+        modelType: 'languageModel',
+      });
+    },
+    embeddingModel,
+    textEmbeddingModel: embeddingModel,
+  };
+}
+
+export const blackForestLabs = createBlackForestLabs();

package/src/index.ts

@@ -0,0 +1,14 @@
+export {
+  createBlackForestLabs,
+  blackForestLabs,
+} from './black-forest-labs-provider';
+export type {
+  BlackForestLabsProvider,
+  BlackForestLabsProviderSettings,
+} from './black-forest-labs-provider';
+export type {
+  BlackForestLabsImageModelId,
+  BlackForestLabsAspectRatio,
+} from './black-forest-labs-image-settings';
+export type { BlackForestLabsImageProviderOptions } from './black-forest-labs-image-model';
+export { VERSION } from './version';

package/src/version.ts

@@ -0,0 +1,6 @@
+// Version string of this package injected at build time.
+declare const __PACKAGE_VERSION__: string | undefined;
+export const VERSION: string =
+  typeof __PACKAGE_VERSION__ !== 'undefined'
+    ? __PACKAGE_VERSION__
+    : '0.0.0-test';