Black Forest Labs

This page adapts the original AI SDK documentation: Black Forest Labs.

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 in the BlackForestLabsProvider module. Add it to your Swift package:

// Package.swift (excerpt)
dependencies: [
  .package(url: "https://github.com/teunlao/swift-ai-sdk", from: "0.14.0")
],
targets: [
  .target(
    name: "YourTarget",
    dependencies: [
      .product(name: "SwiftAISDK", package: "swift-ai-sdk"),
      .product(name: "BlackForestLabsProvider", package: "swift-ai-sdk")
    ]
  )
]

Provider Instance

You can import the default provider instance blackForestLabs:

import SwiftAISDK
import BlackForestLabsProvider

let model = blackForestLabs.image("flux-pro-1.1")

If you need a customized setup, use createBlackForestLabs and create a provider instance with your settings:

import BlackForestLabsProvider

let blackForestLabs = createBlackForestLabs(settings: BlackForestLabsProviderSettings(
  apiKey: ProcessInfo.processInfo.environment["BFL_API_KEY"],
  baseURL: "https://api.bfl.ai/v1",
  headers: ["X-Custom-Header": "value"],
  pollIntervalMillis: 500,
  pollTimeoutMillis: 60_000
))

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 [String: String]

Custom headers to include in the requests.
fetch FetchFunction

Custom fetch implementation (middleware) for testing or request interception.
pollIntervalMillis Int

Interval in milliseconds between polling attempts when waiting for image generation to complete. Defaults to 500ms.
pollTimeoutMillis Int

Overall timeout in milliseconds for polling before giving up. Defaults to 60000ms (60 seconds).

Image Models

You can create Black Forest Labs image models using the .image() factory method. For more on image generation with the Swift AI SDK see Image Generation.

Basic Usage

import SwiftAISDK
import BlackForestLabsProvider

let result = try await generateImage(
  model: blackForestLabs.image("flux-pro-1.1"),
  prompt: "A serene mountain landscape at sunset"
)

try result.image.data.write(to: URL(fileURLWithPath: "image.png"))

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.

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.
`flux-pro-1.0-fill`	Inpainting model for filling masked regions of images with new content

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.

Note: In Swift, pass reference images (and optional masks) via prompt: .imageEditing(images:text:mask:) (type GenerateImagePrompt). This maps to the provider files / mask fields.

Single Image Editing

Transform an existing image using text prompts:

import SwiftAISDK
import BlackForestLabsProvider

let result = try await generateImage(
  model: blackForestLabs.image("flux-kontext-pro"),
  prompt: .imageEditing(
    images: [
      .string("https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png")
    ],
    text: "A baby elephant with a shirt that has the logo from the input image."
  ),
  providerOptions: [
    "blackForestLabs": [
      "width": 1024,
      "height": 768
    ]
  ]
)

Multi-Reference Editing

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

import SwiftAISDK
import BlackForestLabsProvider

let result = try await generateImage(
  model: blackForestLabs.image("flux-kontext-pro"),
  prompt: .imageEditing(
    images: [
      .string("https://example.com/style-reference.jpg"),
      .string("https://example.com/subject-reference.jpg")
    ],
    text: "Combine the style of image 1 with the subject of image 2"
  )
)

Note: Input images can be provided as URLs or base64-encoded strings. They support up to 20MB or 20 megapixels per image.

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 and mask via prompt: .imageEditing(images:text:mask:):

import SwiftAISDK
import BlackForestLabsProvider

let result = try await generateImage(
  model: blackForestLabs.image("flux-pro-1.0-fill"),
  prompt: .imageEditing(
    images: [.string("https://example.com/source-image.jpg")],
    text: "A beautiful garden with flowers",
    mask: .string("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:

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: .imageEditing(images:text:mask:) instead of provider options. Black Forest Labs supports up to 10 input images.

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 SwiftAISDK
import BlackForestLabsProvider

let result = try await generateImage(
  model: blackForestLabs.image("flux-pro-1.1"),
  prompt: "A serene mountain landscape at sunset"
)

if let first = result.providerMetadata["blackForestLabs"]?.images.first,
   case let .object(fields) = first,
   case let .number(seed)? = fields["seed"] {
  print("Seed:", seed)
}

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 BlackForestLabsProvider

let blackForestLabs = createBlackForestLabs(settings: .init(
  baseURL: "https://api.eu.bfl.ai/v1" // or https://api.us.bfl.ai/v1
))