--- title: Black Forest Labs description: Learn how to use Black Forest Labs with AI Gateway and the direct provider. url: "https://ai-sdk.dev/providers/ai-sdk-providers/black-forest-labs" docs_index: /llms.txt --- > For an index of all documentation, see [/llms.txt](/llms.txt). [Black Forest Labs](https://bfl.ai/) 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](/providers/ai-sdk-providers/ai-gateway) (recommended) or connect directly with `@ai-sdk/black-forest-labs`. ```ts provider="bfl" model="bfl/flux-2-pro" import { generateImage } from 'ai'; const { image } = await generateImage({ model: "bfl/flux-2-pro", 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`: ```bash pnpm add ai ``` Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment: ```bash export AI_GATEWAY_API_KEY=your_api_key_here ``` Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments). See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models. Gateway feature and provider-option support depends on the model and the provider serving the request. See [Gateway provider options](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options). ## Using `@ai-sdk/black-forest-labs` For direct access to Black Forest Labs, install `ai` and `@ai-sdk/black-forest-labs`: ```bash pnpm add ai @ai-sdk/black-forest-labs ``` Set your Black Forest Labs API credential in the `BFL_API_KEY` environment variable: ```bash 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. The following sections document the direct `@ai-sdk/black-forest-labs` provider, including its model factories and settings. Gateway model and feature availability can differ. ## 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 | PromiseLike\ | (() => string | PromiseLike\)* Pass a function to resolve credentials before each request, including when keys rotate. The function can return a string or a promise. Credential caching and refresh are managed by the function. API key that is being sent using the `x-key` header. It defaults to the `BFL_API_KEY` environment variable. - **headers** *Record\* Custom headers to include in the requests. - **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\* 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. - **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()](/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 | Sizes | Image Editing | Mask Input | Max Images Per Call | | -------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------- | ---------- | ------------------- | | `flux-3-image` | FLUX 3 for text-to-image and editing with up to ten reference images and optional web grounding | Accepted size or aspect ratio depends on the model and operation. | ✓ | ✗ | 1 | | `flux-3-image-klein` | FLUX 3 Image Klein for fast generation and editing, with open weights and exact output dimensions | Accepted size or aspect ratio depends on the model and operation. | ✓ | ✗ | 1 | | `flux-kontext-pro` | FLUX.1 Kontext \[pro] handles both text and reference images as inputs, enabling targeted edits and complex transformations | Accepted size or aspect ratio depends on the model and operation. | ✓ | ✗ | 1 | | `flux-kontext-max` | FLUX.1 Kontext \[max] with improved prompt adherence and typography generation | Accepted size or aspect ratio depends on the model and operation. | ✓ | ✗ | 1 | | `flux-pro-1.1-ultra` | Ultra-fast, ultra high-resolution image creation | Accepted size or aspect ratio depends on the model and operation. | ✗ | ✗ | 1 | | `flux-pro-1.1` | Fast, high-quality image generation from text. | Accepted size or aspect ratio depends on the model and operation. | ✗ | ✗ | 1 | | `flux-pro-1.0-fill` | Inpainting model for filling masked regions of images with new content | Accepted size or aspect ratio depends on the model and operation. | ✓ | ✓ | 1 | 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](#image-editing) below. FLUX.2 generations can take longer than the 60 second default polling timeout, especially with reference images. Raise `pollTimeoutMillis` when a request reports `Black Forest Labs generation timed out.` ### 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`: ```ts 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: ```ts 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): ```ts 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: ```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, }, }); ``` #### 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', ], }, }); ``` Input images can be provided as URLs or base64-encoded strings. They support up to 20MB or 20 megapixels per image. #### FLUX.2 Editing FLUX.2 models accept reference images on the same `prompt.images` field, so no separate editing model ID is needed: ```ts 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: ```ts 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`: ```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', }, }); ``` 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. When set, Black Forest Labs returns a submit response without a polling URL. The webhook is delivered as configured, and `generateImage` still waits for completion (subject to `pollTimeoutMillis`) by polling the `get_result` endpoint by request id. Polling `get_result` without a `polling_url` is a best-effort fallback: the task must become visible on that endpoint before the poll timeout. - **webhookSecret** *string* - Secret for webhook signature verification, sent in the `X-Webhook-Secret` header. 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. ### 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. ```ts 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](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 }); ``` ## Video Models You can generate videos with the FLUX 3 video model using the [`experimental_generateVideo`](/docs/reference/ai-sdk-core/generate-video) function: ```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, }, }); ``` 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. The URL in provider metadata is time-limited. Persist the returned `video` bytes to your own storage. ### 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](#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: ```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, }, }); ``` ### 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. ```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; // 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, }, }); ``` A draft and its enhance are two separate generations, and each is billed separately. ### 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\* 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 | Model | Description | Image Input | First Frame | Last Frame | Reference Images | Reference Video | Audio | Aspect Ratio | Resolution | Duration | FPS | Seed | | -------------- | -------------------------------------------------------------------------------------------------------- | ----------- | ----------- | ---------- | ---------------- | --------------- | ----- | ------------ | ---------- | -------- | --- | ---- | | `flux-3-video` | Up to full-HD and 20 seconds, with synchronized audio. Text-to-video, keyframes, and video continuation. | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ## Provider Option Reference The following option definitions are generated from the provider catalog. | Operation | Option | Description | | --------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | image | `resolution` | resolution | | image | `grounding` | grounding | | image | `version` | version | | image | `imagePrompt` | imagePrompt | | image | `imagePromptStrength` | imagePromptStrength | | image | `inputImage` | inputImage | | image | `inputImage2` | inputImage2 | | image | `inputImage3` | inputImage3 | | image | `inputImage4` | inputImage4 | | image | `inputImage5` | inputImage5 | | image | `inputImage6` | inputImage6 | | image | `inputImage7` | inputImage7 | | image | `inputImage8` | inputImage8 | | image | `inputImage9` | inputImage9 | | image | `inputImage10` | inputImage10 | | image | `steps` | steps | | image | `guidance` | guidance | | image | `width` | width | | image | `height` | height | | image | `outputFormat` | outputFormat | | image | `promptUpsampling` | promptUpsampling | | image | `raw` | raw | | image | `safetyTolerance` | safetyTolerance | | image | `webhookSecret` | webhookSecret | | image | `webhookUrl` | webhookUrl | | image | `pollIntervalMillis` | pollIntervalMillis | | image | `pollTimeoutMillis` | pollTimeoutMillis | | video | `resolution` | Output resolution tier. Takes precedence over the top-level `resolution`, which is expressed as `{width}x{height}` and has to be mapped onto a tier. | | video | `aspectRatio` | Aspect ratio of the generated video. Takes precedence over the top-level `aspectRatio`, and unlike it can be set to `auto`. | | video | `keyframes` | Keyframes for image-to-video generation, for the shapes the top-level `image` and `frameImages` options cannot express: more than two images, or images pinned to a specific second. Takes precedence over both. One image opens the clip, two open and close it, and with more the extras are spaced evenly in between. Three or more plain images require an explicit `duration`. | | video | `safetyTolerance` | 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. | | video | `draft` | Render a fast, lower-quality preview instead of the finished video. Defaults to `false`. | | video | `draftCache` | Encrypted draft-cache bundle from a prior `draft` generation, which switches the request to draft-enhance mode: the bundle is replayed at full quality. Either the base64-encoded `.bin` downloaded from the draft's `draftCache` URL, or that URL itself while it is still in its expiry window. | | video | `version` | Model version to pin. Only `latest` is available today. | --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)