FLUX.3 Image API 接入教程：5 分钟出图

TL;DR

FLUX.3 Image 是 Black Forest Labs 2026 年 10 月发布的图片模型，模型名 flux-3-image。一个模型名同时管文生图和改图，改图最多传 10 张参考图。打开模型页就能在线试。
按张计费：1K（默认）$0.048，2K $0.10，4K $0.607。每次任务出 1 张。
最快的调法：POST /v1/tasks 传 prompt，轮询到 success，下载 output[0].url。记得显式写 resolution，失败状态 fail 和 failed 都要判断。

FLUX.3 Image 是什么，新在哪？

生图、改图一个模型名。 不传 image_urls 就是文生图；传 1–10 张参考图就围绕参考图改，提示词里写清每张图负责什么。
五档分辨率：768（$0.041）到 4K（$0.607）；15 种画幅从 21:9 到 9:21，另有 auto。
联网搜索补细节。 grounding 默认开启，生成前可以先搜网页和图片，补充画面信息。
Artificial Analysis 文生图榜第 9。

1.5K、3:2 的室内图：

Architectural interior photograph of a cedar alpine reading cabin,
floor-to-ceiling window opening onto a misty mountain lake, linen armchair and a
small brass lamp, warm wood grain, quiet morning atmosphere, restrained
Scandinavian design, no text.

用这个提示词生成 →（1.5K、3:2）

flux-3-image，1.5K，3:2，$0.07。

两条上手路线

在线试用（不写代码）：

打开 FLUX.3 Image 模型页，登录（新用户注册送 200 积分）。
粘贴提示词，选分辨率和画幅，需要的话上传参考图。
点生成，下载结果。

API 调用：

在控制台创建 API Key。
POST /v1/tasks，"model": "flux-3-image"。
轮询 GET /v1/tasks/{taskId} 或接收回调，保存 output[0].url。

curl：跑通第一张

1K、4:3，$0.048：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-image",
    "input": {
      "prompt": "A refined still life of a terracotta architectural model on ivory paper, brass desk lamp, olive leaves, soft late-afternoon sunlight, no text",
      "resolution": "1K",
      "aspect_ratio": "4:3"
    }
  }'

返回里有 data.taskId。轮询 GET /v1/tasks/{taskId}，status 变成 success 后下载 output[0].url。

Python：提交、轮询、下载

# pip install requests; export HIAPI_KEY=你的 Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(timeout_s=300, **inp):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    r = requests.post(API, json={"model": "flux-3-image", "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(5)
    raise TimeoutError(task_id)

url = generate(
    prompt="A cinematic rainy Tokyo side street at blue hour, a small bookstore with warm amber windows, a red bicycle outside, no readable signs",
    resolution="2K", aspect_ratio="16:9",
)
ext = url.split("?")[0].rsplit(".", 1)[-1]  # 按返回的文件类型保存
with open(f"street.{ext}", "wb") as f:
    f.write(requests.get(url).content)

用参考图改图

传 image_urls（1–10 张公开链接），提示词里说清每张图提供什么、不要带入什么。下面这张三图合成：图 1 出主体，图 2 出场景，图 3 只借配色。

Create a refined product photograph. Use the cobalt blue ceramic teapot and
walnut handle from Image 1 as the main subject, place it on a pale stone side
table inside the cedar reading cabin from Image 2. Borrow only the subtle teal
and amber lighting palette from Image 3. Preserve the teapot shape and glaze,
keep the lake window visible in the background, realistic scale, no lettering.

url = generate(
    prompt=open("teapot_prompt.txt").read(),
    image_urls=[
        "https://your-cdn.example.com/teapot.jpg",   # 图 1：主体
        "https://your-cdn.example.com/cabin.jpg",    # 图 2：场景
        "https://your-cdn.example.com/street.jpg",   # 图 3：只借配色
    ],
    resolution="1K", aspect_ratio="3:2",
)

flux-3-image，三张参考图，3:2，$0.048。参考图不加价。

参数速查

字段	取值	说明
`prompt`	字符串，必填，最多 5000 字符	描述画面，或写清要改什么、保留什么
`image_urls`	1–10 张公开链接，可选	不传就是文生图
`resolution`	`768` / `1K` / `1.5K` / `2K` / `4K`，默认 `1K`	决定价格；实际宽高随画幅变
`aspect_ratio`	`21:9` `2:1` `16:9` `3:2` `7:5` `4:3` `5:4` `1:1` `4:5` `3:4` `5:7` `2:3` `9:16` `1:2` `9:21` `auto`，默认 `auto`	固定版位请明确选比例
`safety_tolerance`	0–4，默认 2	0 最严格
`grounding`	布尔，默认 `true`	生成前搜索网页和图片

上线前注意

每次都写 resolution。 手滑写成 4K，一张就从 $0.048 变成 $0.607。
fail 和 failed 都要判断。 文档写的是 failed，两个都判断更稳。
用回调代替轮询：在 input 同级加 "callback": {"url": "https://your-app.example.com/hiapi/callback"}，按 taskId 去重。
结果马上保存。 output[0].url 有有效期，及时下载或在创建任务时选永久存储。
带上 Idempotency-Key 请求头，重试时同一个 Key 只建一次任务。