Black Forest Labs Provider

Black Forest Labs 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

pnpm add @ai-sdk/black-forest-labs

Provider Instance

You can import the default provider instance blackForestLabs from @ai-sdk/black-forest-labs:

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:

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<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom 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().

Basic Usage

import { writeFileSync } from 'node:fs';
import { blackForestLabs } from '@ai-sdk/black-forest-labs';
import { experimental_generateImage as 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.

Black Forest Labs models support aspect ratios from 3:7 (portrait) to 7:3 (landscape).

Modify Image

Transform existing images using text prompts.

import {
  blackForestLabs,
  BlackForestLabsImageProviderOptions,
} from '@ai-sdk/black-forest-labs';
import { experimental_generateImage as generateImage } from 'ai';

// Example: Modify existing image
await generateImage({
  model: blackForestLabs.image('flux-kontext-pro'),
  prompt: 'Put a donut next to the flour.',
  providerOptions: {
    blackForestLabs: {
      inputImage: '<base64 converted image>',
    } satisfies BlackForestLabsImageProviderOptions,
  },
});

Provider Options

Black Forest Labs image models support flexible provider options through the providerOptions.blackForestLabs object. You can pass any parameters supported by the specific endpoint's API. The supported parameters depend on the used model ID:

• imagePrompt - Base64-encoded image to use as additional visual context for generation
• imagePromptStrength - Strength of the image prompt influence on generation (0.0 to 1.0)
• inputImage - Base64 encoded image or URL of image to use as reference. Supports up to 20MB or 20 megapixels.
• outputFormat - Desired format of the output image. Can be “jpeg” or “png”.
• promptUpsampling - If true, performs upsampling on the prompt.
• raw - Enable raw mode for more natural, authentic aesthetics
• safetyTolerance - Moderation level for inputs and outputs. Value ranges from 0 (most strict) to 6 (more permissive).
• webhookSecret - Secret for webhook signature verification, sent in the X-Webhook-Secret header.
• webhookUrl - URL for asynchronous completion notification. Must be a valid HTTP/HTTPS URL.

Regional Endpoints

By default, requests are sent to https://api.bfl.ai/v1. You can select a regional endpoint by setting baseURL when creating the provider instance:

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
});