Black Forest Labs

FLUX 3 Image

flux-3-image

Black Forest Labs 多模态家族中的图像方向模型，与视频、音频共享联合训练架构和 Self-Flow 框架，适合基于 FLUX 体系的图像生成管线升级

flux-3-image

试用 flux-3-image

输入

作品灵感

查看全部作品

输出

image

填写参数并生成，结果会显示在这里。

价格

flux-3-image 每张

规格	单价
768S	$0.041
1K	$0.048
1.5K	$0.070
2K	$0.100
4K	$0.607

定位简介

flux-3-image 是 Black Forest Labs 的 FLUX 3 多模态家族中的图像方向模型，通过 HiAPI.ai 统一接口调用。它既接受纯文本提示词直接生成图像，也支持最多 10 张参考图参与生成与局部修改，输出画幅、分辨率档位与内容安全宽容度均可调。适合正在搭建视觉内容生成管线的开发者，以及需要在既有 FLUX 图像工作流上接入新一代模型的团队。

核心亮点

参考图与提示词协同控制——最多可传入 10 张参考图，并在提示词中逐张指明其承担的主体、风格或构图角色。
可选联网检索补充视觉信息——grounding 默认开启，生成前检索网页与图片，为提示词补足实体与场景细节。
分辨率与画幅精细可选——输出覆盖 768 至 4K 五档像素与 16 种画幅比例，auto 模式可按提示词与参考图自动定画幅。

能力说明

文生图与参考图引导生成：一次请求即可由提示词生成图像；提供参考图时，在提示词中说明需修改与保留的内容即可完成定向调整，无需分步流程。

多图参考组合：单次最多可用 10 张参考图，分别承担主体、风格或构图角色，适合把多个视觉素材收敛到同一画面。

画幅与分辨率控制：aspect_ratio 提供从 21:9 横图到 9:21 竖图的 16 种比例并可自动选择，resolution 覆盖 768 到 4K，便于按投放渠道与清晰度要求批量出图。

内容安全宽容度调节：safety_tolerance 从 0 到 4 可调，默认 2，团队可按自身合规要求收紧或放宽过滤强度。

适用场景

创意设计团队的风格化出图——输入设计说明与风格参考图，产出符合指定构图与画幅的视觉稿，用于广告素材与概念提案。
既有 FLUX 管线的模型升级——以文本提示词替换现有图像生成调用，产出沿用原有接口形态，便于在不改动上层流程的前提下更新模型。
需要事实细节的场景图生产——开启 grounding 后以简短提示词描述主体，产出补充了检索信息的画面，用于内容配图与场景示意。
多素材合成与图片改稿——上传多张参考图并标注各自角色，产出统一风格的合成或修改结果，用于电商图与素材复用。

限制与选型建议

公开信息以 FLUX 3 家族整体及视频方向为主，针对本图像版本的具体规格披露有限；家族层面的联合训练与视频能力描述不能直接等同于本模型的全部能力。grounding 会先检索再生成，可能增加单次请求耗时。对生成速度、稳定性与极端困难提示词的表现，建议先用自有样例验证再纳入生产。若需求是视频或音频生成，应选择同家族对应方向的模型。

常见问题

查看全部常见问题 →

一个入口可以生成和编辑吗？

可以。没有参考图时从文字生成，提供 1–10 张参考图时围绕已有素材编辑。先根据创作目标准备文字或图片即可。
五档分辨率应该怎么选？

先用 768 或 1K 讨论方向；需要更多细节时考虑 1.5K 或 2K，需要较大图片与裁切空间时考虑 4K。档位不是固定边长，请核对返回图片的宽高。
参考图怎样分配作用？

按顺序说明哪张提供主体、哪张提供环境、哪张只提供配色或风格，同时指出不要带入的元素。
每次会生成多少张图片？

每次任务返回一张图片。需要另一个方向时调整描述并提交独立任务。

提交生成任务

POST https://api.hiapi.ai/v1/tasks

请求头

Authorizationstring必填

账号 API Key，所有请求必填。示例：Bearer YOUR_HIAPI_API_KEY。获取 API Key

Content-Typestring可选

请求体固定按 JSON 解析；如携带，仅接受 application/json（可带 charset），其他取值返回 415。示例：application/json。

Idempotency-Keystring可选

幂等键，最长 255 字节。同账户同键的重试只创建一次任务，重放返回首次 taskId。

幂等键

网络超时或客户端自动重试时，同键只创建一次任务、不会重复扣费（幂等范围 = API Key 所属账户）。建议用业务侧唯一标识做键（如 "order-42"）；同键重放返回首次 taskId，键在首次提交 24 小时后过期。详细的场景矩阵见统一异步接口介绍页。

请求体

modelstring必填

当前固定值：flux-3-image

routestring可选

当前固定值：default

inputobject必填

flux-3-image 和线路 default 的业务参数对象，见下方参数表。

promptstring必填minLength 1maxLength 5000

描述希望生成的画面内容；当提供参考图时，也可在此说明图中需要修改与保留的部分。

groundingboolean可选默认值: true

布尔值，控制是否在生成前联网搜索网页与图片，以补充提示词中的视觉信息；默认为 true。

image_urlsarray可选minItems 1maxItems 10

参考图片 URL 数组，用于为生成提供视觉参考；每张图片的主体、风格或构图角色需在提示词中说明。

Array [ string ]

resolutionstring可选默认值: "1K"

输出分辨率档位，具体宽高随画幅比例变化；默认为 1K。

可选项：7681K1.5K2K4K

aspect_ratiostring可选默认值: "auto"

输出画幅比例，可选横图、竖图或方图；auto 表示根据提示词与参考图自动确定画幅，默认为 auto。

可选项：21:92:116:93:27:54:35:41:1

显示全部（8 项）

4:53:45:72:39:161:29:21auto

safety_toleranceinteger可选默认值: 2min 0max 4

整数，内容安全宽容度，数值 0 为最严格；默认为 2。

callbackobject可选

终态通知配置；为空则不回调，由调用方自行查询。详见下方回调说明。

回调（Webhook）

创建任务时提供 callback.url，任务终态时 HiAPI 主动 POST 通知你的服务，可免去轮询。回调请求体与任务详情数据结构同构；签名校验、投递重试与幂等说明见统一异步接口介绍页的回调说明。

urlstring必填

callback 存在时必填；任务终态后向该 URL 发起 POST，须为合法 http(s) URL。

whenstring可选默认值: "final"

当前仅支持 final，即 success / fail 均回调。

可选项：final

storagestring可选默认值: "temp"

产物存储档位：temp（默认，保留约 7 天）或 persistent（长期保存，按大小计费）。余额不足或超出存储上限会静默降级为 temp；实际生效档位见任务详情响应。

可选项：temppersistent

请求示例

# 提交异步任务，成功立即返回 taskId（不等待生成完成）
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "flux-3-image",
  "input": {
    "prompt": "…",
    "grounding": true,
    "resolution": "1K",
    "aspect_ratio": "auto",
    "safety_tolerance": 2
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "flux-3-image",
    input: {
      "prompt": "…",
      "grounding": true,
      "resolution": "1K",
      "aspect_ratio": "auto",
      "safety_tolerance": 2
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "flux-3-image",
        "input": {
          "prompt": "…",
          "grounding": True,
          "resolution": "1K",
          "aspect_ratio": "auto",
          "safety_tolerance": 2
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

获取任务详情

GET https://api.hiapi.ai/v1/tasks/:id

响应字段

taskIdstring必填

任务 ID，前缀固定 tk-hiapi-。

modelstring必填

解析后的模型全名。用 route 参数提交的任务返回 base@线路（如 gpt-image-2/text-to-image@ext）；否则与创建时传入的模型名一致。

routestring可选

仅当任务用显式 route 参数提交时出现，回显提交时的原值。

statusstring必填

任务状态。

状态枚举

queued 已入队，尚未开始。 handling 处理中。 archiving 处理完成，产物准备中。 success 终态：完成，产物可用（返回 output）。 fail 终态：失败（返回 error）。提交后按 status 判断：success 或 fail 为终态，其余为非终态，建议按 1~3 秒间隔轮询直至终态。成功终态后从 output[].url 下载产物，并在 expireAt 前完成下载或转存；需要长期保留时在创建任务时使用 storage: "persistent"。

creatednumber必填

任务创建时间（Unix 秒）。

completednumber必填

进入终态的 Unix 秒；非终态固定为 0。

outputarray可选

仅 status == success 时出现。产物列表，始终为数组，同一任务可能同时返回多个 type（如 video + first_frame）。

Array [ object ]

数组元素

urlstring必填

资源 URL，可直接下载。

typestring必填

当前可能值：video、image、audio、first_frame、last_frame、thumbnail，后续可能会扩展。

expireAtnumber必填

资源可访问截止时间（Unix 秒）；过期前请完成下载或转存。

errorobject可选

仅 status == fail 时出现。

codestring必填

业务错误码。

messagestring必填

错误描述。

响应示例

成功

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

处理中（非终态）

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

失败

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}