Magick API User Guide

Routes, parameters, and examples for calling BFL official FLUX image generation, image editing, Fill, and Erase models through Magick API.

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

Request model	BFL upstream model or path	Recommended endpoint	Use case
`flux2_text_to_image`	`flux-2-pro-preview`	`POST /v1/images/generations`	FLUX.2 text-to-image
`flux2_image_editing`	`flux-2-pro-preview`	`POST /v1/images/edits`	FLUX.2 single or multi-reference editing
`flux-2-pro-preview`	`flux-2-pro-preview`	`POST /v1/images/generations` or `/v1/images/edits`	Native FLUX.2 preview model name
`flux-pro-1.1`	`flux-pro-1.1`	`POST /v1/images/generations`	FLUX.1.1 text-to-image
`flux_1_fill`	`flux-pro-1.0-fill`	`POST /v1/images/edits`	Masked inpainting, outpainting, and local edits
`flux-erase`	`flux-tools/erase-v1`	`POST /v1/images/edits`	Mask-based object removal

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

Field	Type	Description
`model`	string	Required. Use one of the request model names above
`prompt`	string	Required for text-to-image and FLUX.2 editing; optional instruction for `flux_1_fill`; not needed for `flux-erase`
`size`	string	OpenAI-compatible size such as `1024x1024`; converted to BFL `width` and `height`
`output_format`	string	BFL output format: `jpeg`, `png`, or `webp`
`response_format`	string	Magick API response format: `url` or `b64_json`
`quality`	string	Compatibility field. `hd` or `high` maps to BFL `prompt_upsampling: true`
`extra_fields`	object	Pass-through BFL official fields. BFL fields can also be sent at the top level

FLUX.2 Parameters

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

Field	Type	Default / range	Description
`prompt`	string	Required	Text-to-image or editing prompt
`input_image`	string	Optional	BFL official reference image field; accepts image URL or Base64
`input_image_2` ... `input_image_8`	string	Optional	Multi-reference editing, up to 8 images
`image` / `images`	string / array	Optional	OpenAI-compatible reference image fields mapped to `input_image*`
`width`	integer	`>= 64`	Output width
`height`	integer	`>= 64`	Output height
`seed`	integer	Optional	Reproducible result seed
`safety_tolerance`	integer	`0 ~ 5`, default `2`	Moderation tolerance. 0 is strictest
`output_format`	string	Default `jpeg`	`jpeg`, `png`, or `webp`
`webhook_url`	string	Optional	Passed through to BFL
`webhook_secret`	string	Optional	Passed through to BFL for webhook verification

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.

Field	Type	Default / range	Description
`prompt`	string	Optional	Text-to-image prompt
`image_prompt`	string	Optional	Base64 image prompt for Flux Redux guidance
`width`	integer	`256 ~ 1440`, multiple of 32, default `1024`	Output width
`height`	integer	`256 ~ 1440`, multiple of 32, default `768`	Output height
`prompt_upsampling`	boolean	Default `false`	Ask BFL to enrich the prompt
`seed`	integer	Optional	Reproducible result seed
`safety_tolerance`	integer	`0 ~ 6`, default `2`	Moderation tolerance
`output_format`	string	Default `jpeg`	`jpeg`, `png`, or `webp`

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_1_fill. For Magick API FLUX.1 Fill calls, downstream clients still call the OpenAI-compatible POST /v1/images/edits endpoint. Do not call the BFL official /v1/flux-pro-1.0-fill path directly; the gateway maps model: "flux_1_fill" to the upstream BFL model internally. 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.
Explicitly send response_format: "url" and output_format: "png" for predictable OpenAI-compatible image responses. :::

Field	Type	Default / range	Description
`image`	base64 string	Required	Source image
`mask`	base64 string	Required	Mask image with the same dimensions as the source
`prompt`	string	Required	Instruction for the masked area
`response_format`	string	Recommended `url`	Magick API response format, recommended to send explicitly
`steps`	integer	`15 ~ 50`, default `50`	Generation steps
`guidance`	number	`1.5 ~ 100`, default `60`	Guidance strength
`prompt_upsampling`	boolean	Default `false`	Ask BFL to enrich the prompt
`seed`	integer	Optional	Reproducible result seed
`safety_tolerance`	integer	`0 ~ 6`, default `2`	Moderation tolerance
`output_format`	string	Default `jpeg`	`jpeg`, `png`, or `webp`

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_1_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. The official upstream path is flux-tools/erase-v1.

Field	Type	Default / range	Description
`image`	base64 string	Required	Source image
`mask`	base64 string	Required	Black/white mask. White is removed and black is preserved
`dilate_pixels`	integer	`0 ~ 100`, default `10`	Expand mask edges before removal
`seed`	integer	Optional	Reproducible result seed
`safety_tolerance`	integer	`0 ~ 5`, default `2`	Moderation tolerance
`output_format`	string	Default `png`	`jpeg`, `png`, or `webp`

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.

BFL FLUX Official Models