Black Forest Labs

Black Forest Labs provides a generative media platform for developers with FLUX-based models. Their platform offers fast, high quality, and in-context image generation and editing, plus video generation with FLUX 3. You can use Black Forest Labs models through AI Gateway (recommended) or connect directly with @ai-sdk/black-forest-labs.

import { generateImage } from 'ai';

const { image } = await generateImage({
  model: 'openai/gpt-image-2.5-sunburst',
  prompt: 'A sunlit mountain village in watercolor.',
});

console.log(image.base64);

Using AI Gateway

The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install ai:

pnpm add ai

npm install ai

yarn add ai

bun add ai

Set an AI Gateway API key in your environment:

export AI_GATEWAY_API_KEY=your_api_key_here

Vercel deployments can also use OIDC authentication. See the AI Gateway provider documentation for configuration and the model catalog for available models.

Gateway feature and provider-option support depends on the model and the provider serving the request. See Gateway provider options.

Using @ai-sdk/black-forest-labs

For direct access to Black Forest Labs, install ai and @ai-sdk/black-forest-labs:

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

npm install ai @ai-sdk/black-forest-labs

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

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

Set your Black Forest Labs API credential in the BFL_API_KEY environment variable:

export BFL_API_KEY=your_api_key_here

AI Gateway does not expose every API in @ai-sdk/black-forest-labs. Use the direct provider for provider-specific APIs or custom connection settings.

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.

• pollIntervalMillis number

  Interval in milliseconds between polling attempts when waiting for generation to complete. Defaults to 500ms for image models and 2000ms for video models.

• pollTimeoutMillis number

  Overall timeout in milliseconds for polling before giving up. Defaults to 60000ms (60 seconds) for image models and 600000ms (10 minutes) for video models.

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 { 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.

Unknown image model IDs use the latest supported image API, currently FLUX 3 Image Klein's request format and options. Known older families (flux-pro-*, flux-kontext-*, flux-1-*, and flux-2-*) retain the legacy format. The original flux-3-image retains its distinct grounding and version controls.

FLUX.1 and FLUX.2 models support aspect ratios from 3:7 (portrait) to 7:3 (landscape). FLUX 3 accepts only 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2, and 9:21. Omit aspectRatio to use the endpoint's auto default. Unsupported ratios are omitted with a warning.

FLUX.2 models take reference images on the same prompt.images field as the Kontext models, so a single model ID covers both text-to-image and editing. See Image Editing below.

FLUX 3 Image Generation and Editing

The flux-3-image and flux-3-image-klein models generate images from text and edit reference images through their respective endpoints. Pass reference images through prompt.images and select the output resolution with providerOptions.blackForestLabs.resolution:

import {
  blackForestLabs,
  type BlackForestLabsImageModelOptions,
} from '@ai-sdk/black-forest-labs';
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: blackForestLabs.image('flux-3-image'),
  prompt: 'A watercolor illustration of a coastal village at dawn',
  aspectRatio: '16:9',
  providerOptions: {
    blackForestLabs: {
      resolution: '2k',
      grounding: false,
      version: 'latest',
      pollTimeoutMillis: 240000,
    } satisfies BlackForestLabsImageModelOptions,
  },
});

For editing, use a prompt such as:

const { image } = await generateImage({
  model: blackForestLabs.image('flux-3-image'),
  prompt: {
    text: 'Change the sky to sunset while preserving the buildings',
    images: ['https://example.com/village.png'],
  },
});

Both FLUX 3 Image models accept up to ten reference images as URLs or base64-encoded data. For flux-3-image, each reference image must be at least 256 × 256 pixels and no larger than 16 megapixels. Omitting aspectRatio lets the endpoint choose the ratio from the prompt or the first reference image. Text-to-image generation defaults to 1k. Klein edits default to the first reference image's size. Web grounding is available only on flux-3-image and is enabled by default.

The flux-3-image model does not accept seed, masks, explicit width/height, or the legacy image options such as outputFormat, steps, and promptUpsampling. A size is used only to derive a supported aspect ratio; ratios outside the list above are omitted with a warning. Use resolution to select the pixel-area tier. Unsupported options are omitted with warnings; masks are rejected.

FLUX 3 Image Klein

Klein uses the same resolution, aspectRatio, and prompt.images inputs as flux-3-image. It also accepts seed, outputFormat ('jpeg' or 'png'), and steps (1–16, default 16):

const { image } = await generateImage({
  model: blackForestLabs.image('flux-3-image-klein'),
  prompt: {
    text: 'Change the sky to sunset while preserving the buildings',
    images: ['https://example.com/village.png'],
  },
  aspectRatio: '16:9',
  seed: 42,
  providerOptions: {
    blackForestLabs: {
      resolution: '2k',
      outputFormat: 'png',
      steps: 16,
      pollTimeoutMillis: 240000,
    } satisfies BlackForestLabsImageModelOptions,
  },
});

To request exact dimensions, pass size (for example, '2048x2048') or set both providerOptions.blackForestLabs.width and height. Each dimension must be an integer from 64 to 6256, and their product must not exceed 16,822,272 pixels. Provider dimensions override size; exact dimensions override resolution and aspectRatio. Klein does not accept masks, grounding, or version.

The provider polls through Pending, Reasoning, and Generating until the image is ready. Increase pollTimeoutMillis for requests that exceed the default 60 second polling timeout. It stops on moderation or task failures and downloads the signed image URL without sending API credentials.

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:

import {
  blackForestLabs,
  BlackForestLabsImageModelOptions,
} 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 BlackForestLabsImageModelOptions,
  },
});

Multi-Reference Editing

Combine multiple reference images for complex transformations. Black Forest Labs supports up to 10 input images:

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',
    ],
  },
});

FLUX.2 Editing

FLUX.2 models accept reference images on the same prompt.images field, so no separate editing model ID is needed:

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

const { image } = await generateImage({
  model: blackForestLabs.image('flux-2-pro'),
  prompt: {
    text: 'Place this logo on a plain ceramic mug.',
    images: ['https://example.com/logo.png'],
  },
  providerOptions: {
    blackForestLabs: {
      pollTimeoutMillis: 240000,
    },
  },
});

flux-2-flex additionally accepts steps and guidance, which let you trade generation time against quality:

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

const { image } = await generateImage({
  model: blackForestLabs.image('flux-2-flex'),
  prompt: 'A detailed macro shot of a dew-covered leaf',
  providerOptions: {
    blackForestLabs: {
      steps: 50,
      guidance: 4,
      pollTimeoutMillis: 240000,
    },
  },
});

Inpainting

The flux-pro-1.0-fill model supports inpainting, which allows you to fill masked regions of an image with new content. Pass the source image via prompt.images and a mask image via prompt.mask:

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

const { images } = await generateImage({
  model: blackForestLabs.image('flux-pro-1.0-fill'),
  prompt: {
    text: 'A beautiful garden with flowers',
    images: ['https://example.com/source-image.jpg'],
    mask: 'https://example.com/mask-image.png',
  },
});

The mask image should be a grayscale image where white areas indicate regions to be filled and black areas indicate regions to preserve.

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:

• resolution "768sq" | "1k" | "1.5k" | "2k" | "4k" - FLUX 3 Image output resolution class. Defaults to "1k" for generation; Klein edits default to the first reference image's size. Exact dimensions vary with aspect ratio.
• grounding boolean - flux-3-image web and image search grounding. Defaults to true; unavailable on Klein.
• version "latest" - flux-3-image endpoint version. Only "latest" is currently available; unavailable on Klein.
• width number - Output width in pixels (256–1920 for legacy models, 64–6256 for Klein; unsupported on flux-3-image). When set, this overrides any width derived from size.
• height number - Output height in pixels (256–1920 for legacy models, 64–6256 for Klein; unsupported on flux-3-image). 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. Klein accepts 1–16 (default 16). 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). FLUX 3 Image models accept 0–7 and default to 2; the endpoint and organization determine the approved maximum. Legacy models accept 0–6.
• 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.

Provider Metadata

The generateImage response includes provider-specific metadata in providerMetadata.blackForestLabs.images[]. Each image object may contain the following properties:

• seed number - The seed used for generation. Useful for reproducing results.
• start_time number - Unix timestamp when generation started.
• end_time number - Unix timestamp when generation completed.
• duration number - Generation duration in seconds.
• cost number - Cost of the generation request.
• inputMegapixels number - Input image size in megapixels.
• outputMegapixels number - Output image size in megapixels.

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

// Access provider metadata
const metadata = providerMetadata?.blackForestLabs?.images?.[0];
console.log('Seed:', metadata?.seed);
console.log('Cost:', metadata?.cost);
console.log('Duration:', metadata?.duration);

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

Video Models

You can generate videos with the FLUX 3 video model using the experimental_generateVideo function:

import {
  blackForestLabs,
  type BlackForestLabsVideoModelOptions,
} from '@ai-sdk/black-forest-labs';
import { experimental_generateVideo as generateVideo } from 'ai';

const { video } = await generateVideo({
  model: blackForestLabs.video('flux-3-video'),
  prompt: 'A white kitten chases a butterfly across a sunlit garden.',
  aspectRatio: '16:9',
  duration: 8,
  poll: {
    intervalMs: 2000,
    timeoutMs: 600000, // 10 minutes
  },
  providerOptions: {
    blackForestLabs: {
      resolution: 'fhd',
    } satisfies BlackForestLabsVideoModelOptions,
  },
});

FLUX 3 generates one video per call. Generation is asynchronous — the model submits a job and polls until it completes, then passes the signed MP4 URL to AI SDK Core. generateVideo downloads it before resolving, so video is a GeneratedFile. The signed URL remains available in providerMetadata.blackForestLabs.videos[0].videoUrl.

Use the top-level poll option to have AI SDK Core orchestrate polling and set the interval and timeout. The FLUX 3 video API does not currently expose a webhook callback input, so a top-level webhook falls back to polling.

duration accepts a whole number of seconds from 5 to 20. A fractional value is rounded and an out-of-range value is clamped, each with a warning. Omit it to let FLUX 3 fit the duration to the content.

Audio is generated by default, so generateAudio only has to be set to turn it off. fps and seed are not supported by the API and are reported as warnings.

Resolution and aspect ratio

The API takes a named resolution tier, hd or fhd (the default is hd), where fhd is finished by the video upsampler. The exact frame size depends on the aspect ratio.

The top-level resolution option is {width}x{height}, so it is mapped onto a tier by its shorter side — 1280x720 becomes hd and 1920x1080 becomes fhd. Other values map to hd when the shorter side is at most 720 pixels, and to fhd above 720, with a warning reporting the mapping. Use providerOptions.blackForestLabs.resolution to set the tier directly.

aspectRatio accepts 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, and 9:16. The API default is auto, which infers the ratio from the prompt and any conditioning media; because the top-level option must be {width}:{height}, auto can only be requested through providerOptions.blackForestLabs.aspectRatio.

Generation modes

FLUX 3 is a single endpoint with a mode discriminator. The mode is inferred from the inputs you pass:

• Text-to-video — prompt only.
• Image-to-video — pass image (or a frameImages entry with frameType: 'first_frame') to animate a starting image. Adding a last_frame closes the clip on that image. A last_frame without a first_frame cannot be expressed, and is dropped with a warning.
• Keyframes — for more than two images, or images pinned to a specific second, pass providerOptions.blackForestLabs.keyframes. It takes precedence over image and frameImages.
• Video continuation — pass a video-typed entry in inputReferences to continue from the final frames of an existing MP4. FLUX 3 accepts a single video; keyframes and continuation are mutually exclusive.
• Draft enhance — pass providerOptions.blackForestLabs.draftCache. See Draft mode.

FLUX 3 has no reference-image input, so an image passed in inputReferences is ignored with a warning pointing at image, frameImages, or keyframes.

Keyframes

Keyframes are positional: one image opens the clip, two open and close it, and with more the first and last are the endpoints while the others are spaced evenly between them. Each image is an http(s) URL or a base64 string, and a request accepts 1 to 10 of them.

Three or more untimed keyframes require an explicit duration; the provider reports a warning when that combination is sent, because the API rejects it.

Pass [seconds, image] pairs in chronological order to pin each image to a second of the clip instead:

import {
  blackForestLabs,
  type BlackForestLabsVideoModelOptions,
} from '@ai-sdk/black-forest-labs';
import { experimental_generateVideo as generateVideo } from 'ai';
import { readFileSync } from 'node:fs';

const asBase64 = (file: string) => readFileSync(file).toString('base64');

const { video } = await generateVideo({
  model: blackForestLabs.video('flux-3-video'),
  prompt: 'The cat, then the dog, then the owl each take a turn in the room.',
  duration: 12,
  providerOptions: {
    blackForestLabs: {
      keyframes: [
        [0, asBase64('cat.png')],
        [4.5, asBase64('dog.png')],
        [9, asBase64('owl.png')],
      ],
    } satisfies BlackForestLabsVideoModelOptions,
  },
});

Draft mode

Setting draft: true renders a fast, lower-quality preview and leaves behind an encrypted bundle, reported as providerMetadata.blackForestLabs.videos[0].draftCache. Passing that bundle back as draftCache reproduces the same generation at full quality.

The bundle pins the original mode, prompt, seed, and conditioning media, so an enhance request accepts nothing besides safetyTolerance. Any other option set on the call is reported as an unsupported warning. generateVideo requires a prompt argument, so pass an empty string to say there is nothing to add.

import {
  blackForestLabs,
  type BlackForestLabsVideoModelOptions,
} from '@ai-sdk/black-forest-labs';
import { experimental_generateVideo as generateVideo } from 'ai';

const draft = await generateVideo({
  model: blackForestLabs.video('flux-3-video'),
  prompt: 'A white kitten chases a butterfly across a sunlit garden.',
  duration: 6,
  providerOptions: {
    blackForestLabs: { draft: true } satisfies BlackForestLabsVideoModelOptions,
  },
});

const draftCacheUrl = (
  draft.providerMetadata.blackForestLabs?.videos as
    | Array<{ draftCache?: string }>
    | undefined
)?.[0]?.draftCache;

// The download URL expires; sending the base64 `.bin` is the durable path,
// though the URL itself also works while the link is still valid.
const response = await fetch(draftCacheUrl!);
const arrayBuffer = await response.arrayBuffer();

const enhanced = await generateVideo({
  model: blackForestLabs.video('flux-3-video'),
  prompt: '',
  providerOptions: {
    blackForestLabs: {
      draftCache: Buffer.from(arrayBuffer).toString('base64'),
    } satisfies BlackForestLabsVideoModelOptions,
  },
});

Video Provider Options

The following optional provider options are available for FLUX 3 video:

• resolution 'hd' | 'fhd'

  Output resolution tier. Takes precedence over the top-level resolution.

• aspectRatio '21:9' | '2:1' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16' | 'auto'

  Aspect ratio of the generated video. Takes precedence over the top-level aspectRatio, and unlike it can be set to auto.

• keyframes Array<string | [number, string]>

  Keyframes for image-to-video generation, for the shapes image and frameImages cannot express: more than two images, or images pinned to a specific second. Takes precedence over both.

• safetyTolerance number

  Moderation strictness from 0 (strictest) to 4. Defaults to 2. Sexual content is capped at 3 and hate content at 2 regardless of the request, and any request carrying conditioning media is capped at 2.

• draft boolean

  Render a fast, lower-quality preview instead of the finished video. Defaults to false.

• draftCache string

  Encrypted draft-cache bundle from a prior draft generation, which switches the request to draft-enhance mode.

• version string

  Model version to pin. Only latest is available today.

Video Provider Metadata

FLUX 3 video results include providerMetadata.blackForestLabs.videos[]. Each video object may contain the following properties:

• id string - ID of the Black Forest Labs generation request.
• videoUrl string - The signed MP4 URL (the same URL as video). Time-limited.
• draftCache string - Download URL for the draft bundle. Present only on a draft generation.
• seed number - The seed used for generation, when reported by the API.
• start_time number - Unix timestamp when generation started.
• end_time number - Unix timestamp when generation completed.
• duration number - Duration reported by the API, in seconds.
• cost number - Cost of the generation request in credits.
• inputMegapixels number - Input size in megapixels.
• outputMegapixels number - Output size in megapixels.

Video Model Capabilities