博客

教程

如何通过 HiAPI API 使用 flux-3:curl、Python 与可运行的请求示例

2026年11月10日
封面图:半透明玻璃板交错叠压,将浅色底场折射成冷静的蓝色条带,留白均衡的抽象几何构图。
本页内容

通过 HiAPI 使用 flux-3 能获得什么

flux-3 是一个图像生成模型,既能处理文生图,也能处理图生图。如果你正在构建产品功能、设计工具或内部流水线,真正有意思的部分往往不是模型本身——而是你能多干净地将它置于一个稳定、可预测的接口之后,并在需求变化时保持这种状态。

这正是聚合型 API 平台的价值所在。通过 HiAPI 调用 flux-3 意味着你:

  • 只需集成一次。 单一基础 URL、单一鉴权方式,以及在你所用模型之间保持一致的请求与响应结构。之后更换或对比模型只是改配置,而不是重写代码。
  • 省去基础设施工作。 无需托管模型、无需规划 GPU 容量、无需在你这一侧管理冷启动。你发送 HTTP 请求,处理响应即可。
  • 集中管理凭据。 只需一个 API key 来发放、轮换和限定权限,而不必与每个上游提供商分别建立关系。
  • 获得统一的错误语义。 无论调用背后是哪个模型,状态码和错误封装都相同,这使得重试与告警逻辑可以复用。

具体到 flux-3,这意味着你可以从 notebook 里的原型直接迁移到生产端点,而无需改变客户端代码的结构。两种生成模式——文生图与图生图——共享同一套请求结构,因此支持两者只取决于你填充哪些字段,而不取决于你导入哪个 SDK。

本文通篇采用以下约定:

  • 基础 URL: 你账户控制台中记录的 HiAPI API 端点。
  • 鉴权: 在 Authorization 头中携带 bearer token。
  • 内容类型: 请求体使用 application/json,图像输入根据你的载荷大小限制,以 URL 或 base64 编码数据形式提供。

请将密钥放在环境变量中——绝不要提交到源码管理。下面的示例从 HIAPI_API_KEY 读取密钥,从 FLUX_MODEL 读取模型标识符,这样你无需修改代码即可调整。

铺垫完毕,下一节将拆解请求体本身。

请求结构剖析:文生图与图生图

一次 flux-3 调用在逻辑上分为三部分:端点路径、鉴权头和一个 JSON 请求体。请求体是两种模式产生差异的地方,理解这一差异,你就能让一个客户端同时复用于两者。

共享骨架

每个请求都包含以下某种形式的字段:

  • model — 要调用的模型;此处为你的 flux-3 标识符。
  • input — 承载生成指令的对象。
  • input.prompt — 用自然语言描述你想要的内容。两种模式下均为必填。
  • 可选的生成设置 — 如输出尺寸、宽高比或步数等,取决于模型暴露的能力。只设置你需要的,默认值通常已足够合理。
  • 可选的异步控制 — 改变任务执行与交付方式的标志或回调(下一节详述)。

文生图

在文生图模式下,prompt 是唯一实质性的字段。你描述图像,可选地约束输出几何尺寸,然后提交。没有源图像,因此模型拥有最大自由度——这也意味着提示词质量主导输出质量。

一个有用的习惯:像向人类插画师交代需求那样写提示词。按主体、构图、光照、风格以及任何硬性约束(如「图像中不要出现文字」「主体居中」)的顺序书写。含糊的提示词无论花多少步数,产出都平平无奇。

图生图

在图生图模式下,你在提示词之外再添加一个源图像字段,此时提示词描述的是相对于该输入的变换,而非从零构建的场景。视模型接口而定,这可能意味着提供图像 URL 或编码后的图像载荷,外加任何控制输出偏离源图程度的强度或引导参数。

对你的 API 客户端而言,实际影响很小:相同的端点、相同的鉴权、相同的 input 对象——只多一个字段。这正是设计目标。你的 generate() 函数应接受可选的源图像并在内部处理分支,这样调用方永远不需要知道自己触发了哪种模式。

响应结构

响应应包含任务标识,并在完成时携带生成图像的位置。请将该位置视为不透明值:可以获取或存储,但不要对其内容做解析假设。有些响应是即时返回的,有些则是任务句柄——这正是异步处理必须从第一天起就纳入设计的原因。

参数与异步模式

选择生成设置

生成设置是在质量、延迟与成本之间做权衡。以下几条原则适用于大多数图像模型,也包括 flux-3:

  • 分辨率与宽高比 同时影响输出的实用性和算力消耗。按你实际交付的尺寸生成;把大图缩小浪费预算,把小图放大浪费渲染。
  • 步数或质量控制 提升保真度到一个点后便趋于平缓。用固定提示词实测找到这个拐点并停在那里。
  • 确定性控制(若可用)对可复现性很重要。如果你需要为 QA 或用户支持重新渲染同一结果,请将设置与输出一并记录。

不要猜测参数名称或可接受范围——从控制台中的模型文档读取,并以之为准。若某个字段被拒绝,错误响应会告诉你具体是哪一个。

同步 vs. 异步

图像生成不是瞬时操作。有两种执行模式:

同步(阻塞)。 你发送请求并保持连接直到图像就绪。这种方式简单,适合短任务、脚本以及用户盯着加载动画的交互式工具。但它也很脆弱:无服务器函数、负载均衡器和移动客户端都有超时限制,长时间渲染必然会撞上其中之一。

异步(基于任务)。 你提交请求,立即收到一个标识符,然后轮询状态端点或接收回调,直到任务报告完成。以下场景应选择此模式:

  • 有硬性执行时长上限的无服务器与边缘运行时。
  • 需要并行提交大量渲染的批处理任务。
  • 任何希望立即返回控制权并流式推送进度的用户交互流程。

将客户端设计为围绕异步构建,再用一个同步便捷方法包裹简单场景。反过来做——把异步硬塞进阻塞式客户端——很少有好结果。

轮询时,使用有上限的指数退避而非固定紧密循环,设定总等待时间上限,并将永远无法到达终态的任务视为值得告警的错误。

一个可运行的 curl 请求

从终端开始;一旦原始 HTTP 交换清晰了,代码版本就很简单。

1. 设置环境

export HIAPI_API_KEY="your-key-here"
export FLUX_MODEL="your-flux-3-model-id"
export HIAPI_BASE="https://your-hiapi-endpoint"

将模型标识符放在变量中——以后换模型只改一行。

2. 发送文生图请求

curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLUX_MODEL"'",
    "input": {
      "prompt": "A minimal studio photograph of a ceramic mug on a concrete surface, soft side light, shallow depth of field"
    }
  }'

-sS 标志让输出保持干净,同时仍能显示错误。运行前请对照控制台中记录的端点确认确切路径——路径有版本号,以文档为准。

3. 读取返回内容

将响应通过格式化工具输出,使其可读:

... | python -m json.tool

关注两点:任务标识符,以及图像位置或告诉你任务仍在运行的状态字段。如果你看到的是状态而非图像,说明你在异步路径上——记下标识符,转入轮询。

4. 尝试图生图

将源图像加入 input 对象,其余保持不变:

curl -sS -X POST "$HIAPI_BASE/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLUX_MODEL"'",
    "input": {
      "prompt": "Reinterpret as a watercolor painting, keep the composition and shadows intact",
      "image": "https://example.com/source.jpg"
    }
  }'

由于请求只差一个字段,你第一次成功调用就已经验证了集成的大部分内容。剩下的——重试、存储、UI——都是普通的应用工作。

Python 中的同一请求

curl 调用可以直接翻译过来。下面是一个小巧可复用的客户端,而非一次性脚本。

import os
import time
import requests

BASE = os.environ["HIAPI_BASE"]
MODEL = os.environ["FLUX_MODEL"]
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}


def generate(prompt, image=None, timeout=60):
    """Submit a flux-3 generation job. Pass image= for image-to-image."""
    payload = {"model": MODEL, "input": {"prompt": prompt}}
    if image:
        payload["input"]["image"] = image

    resp = requests.post(
        f"{BASE}/v1/images/generations",
        headers=HEADERS,
        json=payload,
        timeout=timeout,
    )
    resp.raise_for_status()
    return resp.json()

几个有意的选择:

  • 一个函数,两种模式。 image 参数切换行为,调用方无需分支。
  • 显式超时。 requests 的默认行为——无限等待——正是拖垮工作线程池的方式。
  • raise_for_status()。 让 HTTP 层失败以异常形式浮现,你可以在一个地方捕获。

添加轮询辅助函数

当响应携带任务标识符而非完成的图像时,等待它:

def wait_for(job_id, timeout=300, initial=1.0, factor=1.6, cap=15.0):
    deadline = time.monotonic() + timeout
    delay = initial
    while time.monotonic() < deadline:
        r = requests.get(
            f"{BASE}/v1/jobs/{job_id}", headers=HEADERS, timeout=30
        )
        r.raise_for_status()
        data = r.json()
        if data.get("status") in ("succeeded", "failed"):
            return data
        time.sleep(delay)
        delay = min(delay * factor, cap)
    raise TimeoutError(f"job {job_id} did not finish in {timeout}s")

请根据文档记录的响应结构,调整状态字段名。结构本身——有上限的退避、硬性截止时间、终态检查——才是关键,且在你更换模型时原样适用。

组合起来

if __name__ == "__main__":
    result = generate(
        "A minimal studio photograph of a ceramic mug, soft side light"
    )
    if "id" in result and not result.get("output"):
        result = wait_for(result["id"])
    print(result)

接下来,用你自己的重试与日志层包裹 generate,集成便已具备生产形态。

成本控制与常见错误

保持支出可预测

图像生成按请求计费,具体金额取决于模型和设置——请查看控制台中的实时价格面板,而不要硬编码假设。工程纪律才是保护预算的关键:

  • 在你自己的代码中设置每用户和每任务上限。 平台执行账户级限制;你的应用应执行产品级限制,以免单个失控客户端耗尽账户。
  • 积极缓存。 对归一化后的提示词加设置做哈希,复用已存储的输出。编辑器与预览场景中相同请求很常见。
  • 按交付分辨率生成。 渲染你将要展示的尺寸;避免「大图渲染再缩小」这种昂贵模式。
  • 将重新生成置于显式用户操作之后。 在提示词输入框中每敲一次键就自动重新生成,是最常见的意外成本倍增器。
  • 记录每次调用的模型、设置和延迟。 没有这些,你无法判断哪个功能成本高。
  • 提交前校验输入。 在客户端拒绝空或异常长的提示词,这样你永远不会为必然失败的请求付费。

调试你实际会遇到的故障

按顺序逐条排查以下清单,它能解决大多数事故。

  1. 401 / 403 — 鉴权。 密钥是否加载到了请求实际运行的环境中?在你的 shell 中可用的密钥,在容器中可能不存在。确认 Bearer 前缀和头名称完全正确。
  2. 404 — 路径或模型错误。 版本化路径和模型标识符都会变化。逐字符对照文档记录的端点。
  3. 422 / 400 — 载荷被拒绝。 错误体会指明出问题的字段。常见嫌疑:类型错误、缺少 prompt 或参数不受支持。移除可选设置后重新发送以隔离问题。
  4. 429 — 触发限流。 带抖动地退避并重试;不要立即在循环中重试。要与账户级配额耗尽区分开,后者重试无济于事。
  5. 超时。 如果请求耗时过长,说明你在应该轮询的地方做了阻塞。切换到异步流程,并有意识地设置客户端超时。
  6. 任务卡在 pending。 带截止时间轮询,并将超时视为可告警的失败,而非无限等待。

一个习惯能把整份清单串起来:记录完整的错误体,而不只是状态码。错误体通常会精确告诉你哪个字段或限制出了问题,这将半小时的排查变成一行修复。

先让 curl 调用跑通,移植到上面的客户端,把轮询和错误处理集中在一个地方——剩下的集成就是普通的应用代码。关于当前的模型能力与价格,请参阅 HiAPI 控制台中的 flux-3 文档和价格面板。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档