black-forest-labs/capabilities

18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Black Forest Labs video audio generation

Audio is generated by default for Black Forest Labs video models. Set `generateAudio` to turn audio generation off.

Black Forest Labs image models factory method

Create Black Forest Labs image models using the `.image()` factory method on the provider instance. The generateImage response includes provider metadata.

Black Forest Labs image model aspect ratio support

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

Black Forest Labs image editing with reference images

Black Forest Labs Kontext models support image editing using reference images. Pass input images via `prompt.images` to transform, combine, or edit existing images. Input images can be provided as URLs or base64-encoded strings and support up to 20MB or 20 megapixels per image.

Black Forest Labs multi-reference image editing

Black Forest Labs Kontext models support up to 10 input reference images for combining multiple images in complex transformations.

Black Forest Labs inpainting with flux-pro-1.0-fill

The flux-pro-1.0-fill model supports inpainting. Pass the source image via `prompt.images` and a mask image via `prompt.mask`. The mask image should be a grayscale image where white areas indicate regions to be filled and black areas indicate regions to preserve.

Black Forest Labs video generation with FLUX 3

Generate videos with the FLUX 3 model using the `experimental_generateVideo` function. FLUX 3 generates one video per call. Generation is asynchronous—the model submits a job and polls until completion, 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`.

Black Forest Labs FLUX 3 generation modes

FLUX 3 supports multiple generation modes inferred from inputs: Text-to-video (prompt only), Image-to-video (pass `image` or `frameImages` with `frameType: 'first_frame'` to animate a starting image; add `last_frame` to close the clip), Keyframes (for more than two images or images pinned to specific seconds, pass `providerOptions.blackForestLabs.keyframes`), Video continuation (pass a video-typed entry in `inputReferences` to continue from final frames), Draft enhance (pass `providerOptions.blackForestLabs.draftCache`).

Black Forest Labs FLUX 3 keyframes

Keyframes are positional: one image opens the clip, two open and close it, with more the first and last are endpoints while others space evenly. Each image is an HTTP(S) URL or base64 string; a request accepts 1 to 10 images. Pass [seconds, image] pairs in chronological order to pin each image to a specific second. Three or more untimed keyframes require an explicit `duration`.

Black Forest Labs FLUX 3 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. An enhance request with draft cache accepts only `safetyTolerance`; any other option is reported as an `unsupported` warning. A draft and its enhance are two separate generations, each billed separately.

Black Forest Labs basic image generation example

Example showing basic image generation: ```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}`); ```

Black Forest Labs single image editing example

Example showing image editing with single reference image: ```ts 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, }, }); ```

Black Forest Labs multi-reference image editing example

Example showing image editing with multiple reference 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', ], }, }); ```

Black Forest Labs inpainting example

Example showing inpainting with flux-pro-1.0-fill: ```ts 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', }, }); ```

Black Forest Labs video generation example

Example showing basic video generation: ```ts 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, }, }); ```

Black Forest Labs video keyframes example

Example showing video generation with timed keyframes: ```ts 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, }, }); ```

Black Forest Labs draft mode example

Example showing draft mode generation and enhancement: ```ts 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; 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, }, }); ```

Black Forest Labs video URL persistence warning

The signed URL in Black Forest Labs video provider metadata is time-limited. Persist the returned `video` bytes to your own storage.

Give your agent this brain