用户指南
生图模型

BFL FLUX 官方模型

通过 Magick API 调用 BFL 官方 FLUX 图片生成、图片编辑、Fill 和 Erase 模型的路由、参数和示例。

本页说明 Magick API 中 BFL 官方 FLUX 模型的统一调用方式。外部调用仍使用 OpenAI 兼容图片接口，网关会把请求转换为 BFL 官方异步任务，轮询完成后同步返回 ImageResponse。

支持模型

请求模型名BFL 上游模型或路径推荐接口用途
flux2_text_to_imageflux-2-pro-previewPOST /v1/images/generationsFLUX.2 文生图
flux2_image_editingflux-2-pro-previewPOST /v1/images/editsFLUX.2 单图或多参考图编辑
flux-2-pro-previewflux-2-pro-previewPOST /v1/images/generations 或 /v1/images/editsFLUX.2 preview 原生模型名
flux-pro-1.1flux-pro-1.1POST /v1/images/generationsFLUX.1.1 文生图
flux_1_fillflux-pro-1.0-fillPOST /v1/images/edits遮罩重绘、扩图、局部编辑
flux-eraseflux-tools/erase-v1POST /v1/images/edits按遮罩擦除对象

认证与返回

客户端调用 Magick API 时使用平台令牌：

Authorization: Bearer YOUR_API_KEY

BFL 官方密钥配置在后台 BFL 渠道中，调用方不需要也不应该把 BFL 官方密钥直接放到客户端请求里。

成功响应为 OpenAI 兼容图片响应：

{
  "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
  }
}

如果请求中设置 "response_format": "b64_json"，网关会下载 BFL 返回的图片并返回 data[0].b64_json。

通用兼容字段

字段类型说明
modelstring必填，使用上表中的请求模型名
promptstring文生图和 FLUX.2 编辑必填；flux_1_fill 可用于描述遮罩区域；flux-erase 不需要 prompt
sizestringOpenAI 兼容尺寸，例如 1024x1024；网关会转换为 BFL 的 width 和 height
output_formatstringBFL 输出格式，支持 jpeg、png、webp
response_formatstringMagick API 返回格式，支持 url、b64_json
qualitystring兼容字段。hd 或 high 会转换为 BFL prompt_upsampling: true
extra_fieldsobject透传 BFL 官方字段。也可以把 BFL 字段直接放在顶层

FLUX.2 参数

适用于 flux2_text_to_image、flux2_image_editing、flux-2-pro-preview。

字段类型默认值/范围说明
promptstring必填文生图或编辑指令
input_imagestring可选BFL 官方参考图字段，可为图片 URL 或 Base64
input_image_2 ... input_image_8string可选多参考图编辑，最多 8 张
image / imagesstring / array可选OpenAI 兼容参考图字段，网关会映射为 input_image*
widthinteger>= 64输出宽度
heightinteger>= 64输出高度
seedinteger可选复现结果
safety_toleranceinteger0 ~ 5，默认 2审核容忍度，0 最严格
output_formatstring默认 jpegjpeg、png 或 webp
webhook_urlstring可选透传到 BFL，上游任务完成回调
webhook_secretstring可选透传到 BFL，用于 webhook 校验

FLUX.2 文生图示例

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"
  }'

FLUX.2 多参考图编辑示例

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 参数

适用于 flux-pro-1.1。

字段类型默认值/范围说明
promptstring可选文生图提示词
image_promptstring可选Base64 图片提示，用于 Flux Redux 引导
widthinteger256 ~ 1440，32 的倍数，默认 1024输出宽度
heightinteger256 ~ 1440，32 的倍数，默认 768输出高度
prompt_upsamplingboolean默认 false是否让 BFL 自动增强提示词
seedinteger可选复现结果
safety_toleranceinteger0 ~ 6，默认 2审核容忍度
output_formatstring默认 jpegjpeg、png 或 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 参数

适用于 flux_1_fill。在 Magick API 的 FLUX.1 Fill 调用中，下游仍调用 OpenAI 兼容接口 POST /v1/images/edits，不要直接请求 BFL 官方路径 /v1/flux-pro-1.0-fill；网关内部会把 model: "flux_1_fill" 转换为 BFL 上游模型 flux-pro-1.0-fill。请同时提供 image、mask、prompt。image 和 mask 必须是 Base64 图片；黑色区域保留，白色区域重绘。

:::warning[调试重点]

  • image 和 mask 可以带 data:image/...;base64, 前缀，也可以只传纯 Base64；不要传图片 URL，否则会返回 “requires base64 image data”。
  • mask 尺寸必须和 image 原图尺寸完全一致。常见错误是前端按预览尺寸导出 mask，例如原图 1152x896、mask 720x560，BFL 上游会返回 422，网关可能只透出 openai_error / bad_response_status_code。
  • 建议显式传 response_format: "url" 和 output_format: "png"，便于网关按 OpenAI 图片响应返回结果。 :::
字段类型默认值/范围说明
imagebase64 string必填要编辑的原图
maskbase64 string必填遮罩图，尺寸需与原图一致
promptstring必填对遮罩区域的编辑描述
response_formatstring推荐 urlMagick API 返回格式，建议显式传入
stepsinteger15 ~ 50，默认 50生成步数
guidancenumber1.5 ~ 100，默认 60引导强度
prompt_upsamplingboolean默认 false是否自动增强提示词
seedinteger可选复现结果
safety_toleranceinteger0 ~ 6，默认 2审核容忍度
output_formatstring默认 jpegjpeg、png 或 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 参数

适用于 flux-erase。上游官方路径为 flux-tools/erase-v1。

字段类型默认值/范围说明
imagebase64 string必填要处理的原图
maskbase64 string必填黑白遮罩，白色区域移除，黑色区域保留，尺寸需与原图一致
dilate_pixelsinteger0 ~ 100，默认 10擦除前扩张遮罩边缘
seedinteger可选复现结果
safety_toleranceinteger0 ~ 5，默认 2审核容忍度
output_formatstring默认 pngjpeg、png 或 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
  }'

最后更新于

GPT Image 2 Official

说明当前项目对 `gpt-image-2-official` 的接入状态，以及统一图片接口的请求字段和返回结构。

Seedream 4 图像生成

当前项目公开模型列表中可见 `doubao-seedream-4-0-250828` / `seedream-4-0-250828`；调用统一图片接口并同步返回结果。

目录

支持模型
认证与返回
通用兼容字段
FLUX.2 参数
FLUX.2 文生图示例
FLUX.2 多参考图编辑示例
FLUX.1.1 Pro 参数
FLUX.1 Fill 参数
FLUX Erase 参数