BFL FLUX Official Models

This page describes the Magick API integration for BFL official FLUX models. Clients call the OpenAI-compatible image endpoints. The gateway converts the request to the BFL async API, polls the result, and returns a synchronous ImageResponse.

Supported Models

Authentication And Response

Use a Magick API token when calling the gateway:

Authorization: Bearer YOUR_API_KEY

The BFL official key is configured on the BFL channel in the dashboard. Do not send the BFL upstream key directly from clients.

Successful responses use the OpenAI-compatible image shape:

{
  "created": 1712345678,
  "data": [
    {
      "url": "https://signed-result-url.example/image.png"
    }
  ],
  "metadata": {
    "id": "bfl-task-id",
    "status": "Ready",
    "cost": 3,
    "input_mp": 0,
    "output_mp": 1
  }
}

Set "response_format": "b64_json" if you need the gateway to download the BFL result image and return data[0].b64_json.

Common Compatibility Fields

FLUX.2 Parameters

Applies to flux2_text_to_image, flux2_image_editing, and flux-2-pro-preview.

curl --request POST \
  --url https://api.magickapi.com/v1/images/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux2_text_to_image",
    "prompt": "A precise product photo of a matte black espresso machine on a white counter",
    "size": "1024x1024",
    "output_format": "png",
    "safety_tolerance": 2,
    "seed": 42,
    "response_format": "url"
  }'

curl --request POST \
  --url https://api.magickapi.com/v1/images/edits \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux2_image_editing",
    "prompt": "Use the chair from image 2 in the room from image 1, keep natural shadows",
    "images": [
      "https://example.com/room.png",
      "https://example.com/chair.png"
    ],
    "size": "1024x1024",
    "output_format": "jpeg",
    "safety_tolerance": 2
  }'

FLUX.1.1 Pro Parameters

Applies to flux-pro-1.1.

curl --request POST \
  --url https://api.magickapi.com/v1/images/generations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-pro-1.1",
    "prompt": "A futuristic city skyline at sunset with flying cars",
    "width": 1024,
    "height": 768,
    "prompt_upsampling": true,
    "output_format": "jpeg"
  }'

FLUX.1 Fill Parameters

Applies to flux-pro-1.0-fill. When calling the Magick API gateway, continue to use the OpenAI-compatible POST /v1/images/edits endpoint with a JSON body. The gateway converts the request to the BFL official async task /v1/flux-pro-1.0-fill internally and polls the result. Provide image, mask, and prompt together. image and mask must be Base64 images. Black is preserved and white is inpainted.

:::warning[Debugging]

• image and mask may include a data:image/...;base64, prefix or may be raw Base64. Do not send image URLs, otherwise the gateway will return “requires base64 image data”.
• mask must have exactly the same dimensions as the original image. A common frontend bug is exporting the mask at preview size, for example image=1152x896 but mask=720x560; BFL will reject this with 422 and the gateway may only expose openai_error / bad_response_status_code.
• BFL is sensitive to very large inputs. Before submitting, the gateway or client should resize image and mask proportionally to around 4MP or less, with the longest side no larger than 2048px, while keeping both images at exactly the same final dimensions.
• Convert mask to a strict black/white binary image. White marks the region to repaint or erase, and black marks the preserved region; transparent or gray antialiased edges may cause upstream 422 errors or unstable results.
• Explicitly send response_format: "url" and output_format: "png" for predictable OpenAI-compatible image responses. :::

curl --request POST \
  --url https://api.magickapi.com/v1/images/edits \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-pro-1.0-fill",
    "image": "<base64 encoded image>",
    "mask": "<base64 encoded mask>",
    "prompt": "Replace the masked object with a glossy blue glass orb",
    "steps": 15,
    "guidance": 30,
    "output_format": "png",
    "response_format": "url",
    "safety_tolerance": 2,
    "seed": 3205
  }'

FLUX Erase Parameters

Applies to flux-erase. When calling the Magick API gateway, continue to use POST /v1/images/edits with a JSON body. The gateway converts the request to the BFL official async task /v1/flux-tools/erase-v1 internally and polls the result.

:::warning[Debugging]

• image and mask may include a data:image/...;base64, prefix or may be raw Base64. Do not send image URLs, otherwise the gateway will return “requires base64 image data”.
• mask must have exactly the same dimensions as the original image. A common frontend bug is exporting the mask at preview size, for example image=1152x896 but mask=720x560; BFL will reject this with 422.
• BFL is sensitive to very large inputs. Before submitting, the gateway or client should resize image and mask proportionally to around 4MP or less, with the longest side no larger than 2048px, while keeping both images at exactly the same final dimensions.
• Convert mask to a strict black/white binary image. White marks the region to erase, and black marks the preserved region. :::

curl --request POST \
  --url https://api.magickapi.com/v1/images/edits \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "flux-erase",
    "image": "<base64 encoded image>",
    "mask": "<base64 encoded mask>",
    "dilate_pixels": 10,
    "output_format": "png",
    "safety_tolerance": 2
  }'

Billing

BFL may return cost, input_mp, and output_mp in the submission response. Magick API uses the returned cost for final settlement when present. If BFL does not return dynamic cost, the configured fixed model price is used. One BFL credit is treated as $0.01.