Back to Details

flux

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Flux CLI (BFL / FLUX)

Flux CLI（BFL / FLUX）

CLI to generate and edit images via the BFL FLUX API.
一款可通过BFL FLUX API生成和编辑图片的CLI工具。

Quick start

快速开始

  1. API key:
  • env: 
    • export BFL_API_KEY="..."
  • or save locally (reads from stdin; avoid shell history leaks): 
    • echo "$BFL_API_KEY" | flux config set apiKey
  1. Generate:
  • flux gen "a cat astronaut" --model flux-2-pro --width 1024 --height 1024 -o out/
  1. Edit with a reference image:
  • flux edit "make it sunset lighting" --model flux-2-pro --input ./in.jpg -o out/
  1. API密钥：
  • 环境变量方式： 
    • export BFL_API_KEY="..."
  • 或本地保存（从标准输入读取；避免泄露到shell历史）： 
    • echo "$BFL_API_KEY" | flux config set apiKey
  1. 生成图片：
  • flux gen "a cat astronaut" --model flux-2-pro --width 1024 --height 1024 -o out/
  1. 基于参考图编辑：
  • flux edit "make it sunset lighting" --model flux-2-pro --input ./in.jpg -o out/

Commands

命令说明

flux gen [prompt]
  • text-to-image
  • prompt can be positional, or 
    -
    / stdin
flux edit [prompt] --input <path|url|base64> [--input ...]
  • image editing using a prompt + 1..N input images (base + refs)
flux fill [prompt] --image <path|url|base64> [--mask <path|url|base64>]
  • inpaint (explicit mask image, or alpha channel)
flux expand [prompt] --image <path|url|base64> [--top/--bottom/--left/--right <px>]
  • outpaint (expand canvas by pixels on any side)
flux result <id> [--out <path|->]
  • fetch status/result by id
  • if 
    status=Ready
    and 
    --out
    is set, downloads the result
flux wait <id> [--polling-url <url>] [--out <path|->]
  • wait until 
    Ready
    /error; optionally download the result
flux credits
  • show remaining credits
flux models
  • list model keys supported by the CLI
flux config path|get|set|unset
  • local config (including saving API key via stdin)
flux gen [prompt]
  • 文本生成图片
  • prompt可以是位置参数，或使用
    -
    从标准输入读取
flux edit [prompt] --input <path|url|base64> [--input ...]
  • 结合prompt和1至N张输入图（基础图+参考图）进行图片编辑
flux fill [prompt] --image <path|url|base64> [--mask <path|url|base64>]
  • 图像修复（支持显式蒙版图或alpha通道）
flux expand [prompt] --image <path|url|base64> [--top/--bottom/--left/--right <px>]
  • 图像扩展（在任意方向按像素扩展画布）
flux result <id> [--out <path|->]
  • 通过ID获取任务状态/结果
  • 若状态为
    Ready
    且设置了
    --out
    ，则自动下载结果
flux wait <id> [--polling-url <url>] [--out <path|->]
  • 等待任务完成（就绪/错误）；可选择自动下载结果
flux credits
  • 查看剩余余额
flux models
  • 列出CLI支持的模型密钥
flux config path|get|set|unset
  • 本地配置管理（包括通过标准输入保存API密钥）

Global flags

全局参数

  • --json
    : single JSON object to stdout (for scripts)
  • --plain
    : stable line output (paths/ids)
  • -q, --quiet
    : less logging
  • -v, --verbose
    : diagnostics to stderr (no secrets)
  • --endpoint <host>
    : API host (default 
    api.bfl.ai
    )
  • --region <us|eu|global>
    : endpoint shortcut
  • --timeout <ms>
    : timeout
  • --retries <n>
    : retries for 429/5xx
  • --out-dir <dir>
    : default output directory
  • --json
    : 向标准输出输出单个JSON对象（适用于脚本）
  • --plain
    : 输出稳定的行格式（路径/ID）
  • -q, --quiet
    : 减少日志输出
  • -v, --verbose
    : 向标准错误输出诊断信息（不包含敏感信息）
  • --endpoint <host>
    : API主机地址（默认
    api.bfl.ai
    ）
  • --region <us|eu|global>
    : API区域快捷选择
  • --timeout <ms>
    : 请求超时时间
  • --retries <n>
    : 针对429/5xx错误的重试次数
  • --out-dir <dir>
    : 默认输出目录

Common gen/edit flags

生成/编辑通用参数

  • --model <key>
    : model key (see 
    flux models
    )
  • --seed <n>
  • --safety <n>
    : safety_tolerance (range depends on model)
  • --format <jpeg|png>
    : output_format
  • -o, --out <path|->
    : file/dir or 
    -
    for stdout
  • --no-wait
    : submit only; print 
    id
    (+ 
    pollingUrl
    in 
    --json
    )
  • --poll-interval <ms>
Advanced (escape hatch):
  • --body <json|@file>
    : raw request body (full control)
  • --model <key>
    : 模型密钥（可通过
    flux models
    查看）
  • --seed <n>
    : 随机种子
  • --safety <n>
    : 安全容忍度（范围取决于模型）
  • --format <jpeg|png>
    : 输出格式
  • -o, --out <path|->
    : 文件/目录，或使用
    -
    输出到标准输出
  • --no-wait
    : 仅提交任务；输出
    id
    （使用
    --json
    时会额外输出
    pollingUrl
    ）
  • --poll-interval <ms>
    : 轮询间隔时间
高级用法（自定义请求）：
  • --body <json|@file>
    : 原始请求体（完全自定义控制）

Models (keys)

模型（密钥）

Official model lineup evolves; use 
flux models
for the current list.
Built-in keys, when to use them, and pricing tier (rule of thumb; pricing can change):
Model keyBest forPricing tierNotes
flux-2-klein-4b
quick drafts; high-volume generationcheapMP-based
flux-2-klein-9b
better drafts; still fast iterationcheap-to-balancedMP-based
flux-2-pro
default pick; production workflows; general-purpose gen/editbalancedMP-based; edits typically cost more than T2I
flux-2-flex
maximum quality with control knobspremiumMP-based; supports 
--steps
/
--guidance
; image editing is the most expensive tier in FLUX.2
flux-2-max
final assets; quality-first; grounding searchpremium/most expensiveMP-based
flux-kontext-pro
controlled edits/variations with multiple referencesbalancedcredits per call
flux-kontext-max
stronger Kontext edits; quality-firstexpensivecredits per call
flux-pro-1.1
FLUX 1.1 behavior; compatibility workflowsbalancedcredits per call
flux-pro-1.1-ultra
Ultra mode; aspect-ratio driven generation; optional raw lookexpensivecredits per call
flux-pro-1.0-fill
inpainting (mask/alpha)expensivecredits per call (tool endpoint)
flux-pro-1.0-expand
outpainting (extend canvas)mid-to-expensivetool endpoint; check returned 
cost
/credits
flux-dev
passthrough via 
--body
when you know the exact API shape		cheapcredits per call; check returned 
cost
flux-pro
passthrough via 
--body
when you know the exact API shape		variescheck returned 
cost
/credits
Footnote:
  • MP-based: cost scales with output size in megapixels (width * height / 1,000,000). Larger images cost more.
官方模型阵容会不断更新；使用
flux models
查看当前列表。
以下是内置模型密钥、适用场景、价格档位（仅供参考；价格可能变动）：
模型密钥适用场景价格档位说明
flux-2-klein-4b
快速草稿；大批量生成低廉基于MP计费
flux-2-klein-9b
更高质量草稿；仍支持快速迭代低廉至适中基于MP计费
flux-2-pro
默认选择；生产工作流；通用生成/编辑适中基于MP计费；编辑通常比文本生成图片成本更高
flux-2-flex
极致画质，支持更多控制参数高端基于MP计费；支持
--steps
/
--guidance
；图片编辑是FLUX.2中成本最高的档位
flux-2-max
最终资产；画质优先；支持 grounding 搜索高端/最贵基于MP计费
flux-kontext-pro
多参考图控制下的编辑/变体生成适中按调用次数计费
flux-kontext-max
更强的Kontext编辑能力；画质优先昂贵按调用次数计费
flux-pro-1.1
兼容FLUX 1.1行为；适配兼容工作流适中按调用次数计费
flux-pro-1.1-ultra
超高清模式；基于宽高比的生成；可选原生风格昂贵按调用次数计费
flux-pro-1.0-fill
图像修复（蒙版/alpha通道）昂贵按调用次数计费（工具端点）
flux-pro-1.0-expand
图像扩展（画布延伸）中高价位工具端点；需查看返回的
cost
/余额消耗
flux-dev
当你熟悉API结构时，通过
--body
自定义请求		低廉按调用次数计费；需查看返回的
cost
flux-pro
当你熟悉API结构时，通过
--body
自定义请求		档位不一需查看返回的
cost
/余额消耗
注：
  • 基于MP计费：成本随输出图片的像素数（宽 × 高 / 1,000,000）递增，图片越大成本越高。

Safety / reliability notes

安全与可靠性说明

  • API key: avoid passing secrets via flags; use env/config/stdin.
  • Signed URL: 
    result.sample
    is typically short-lived; download immediately.
  • API密钥：避免通过参数传递敏感信息；使用环境变量/配置文件/标准输入方式。
  • 签名URL：
    result.sample
    通常有效期较短；请立即下载。

Common errors (exit codes)

常见错误（退出码）

  • 2
    : invalid args/validation
  • 3
    : missing key or 
    403
  • 4
    : 
    402
    (insufficient credits)
  • 5
    : 
    429
    (rate limit)
  • 6
    : moderation
  • 7
    : other API/task errors
  • 2
    : 参数无效/验证失败
  • 3
    : 密钥缺失或返回
    403
    错误
  • 4
    : 
    402
    错误（余额不足）
  • 5
    : 
    429
    错误（请求频率超限）
  • 6
    : 内容审核不通过
  • 7
    : 其他API/任务错误