博客

教程

通过 HiAPI API 使用 flux-2/image-to-image:curl 与 Python 教程

2026年11月12日
封面图:深松绿色底上几块大棱镜被斜切成平整色块,青绿与雾绿几何切面简洁有序。
本页内容

flux-2/image-to-image 的作用与适用场景

flux-2/image-to-image 是一个编辑端点,而不是纯粹的文生图生成器。你需要交给它两样东西:一张参考图和一段用自然语言写成的编辑指令。模型会把参考图读作视觉上下文——主体、构图、风格、光照——并生成一张既遵循你的指令、又锚定在这张参考图上的新图像。

在设计流水线时,这一区别很重要。使用文生图时,你要从零描述一切,然后指望模型落在你意图附近。使用图生图时,你已经有一个视觉素材,想要的是受控的变换:重新设计产品图的风格、替换背景、调整场景氛围,或在保持底层构图稳定的同时迭代设计。

适合的场景

  • 素材变体。 基于一张已获认可的参考图生成多种风格化处理。
  • 引导式编辑。 应用针对性改动(“让光线更温暖”“把背景换成纯色影棚墙”),而不必重新生成整个场景。
  • 一组结果的一致性。 复用同一张参考图,让一批输出共享同一个视觉锚点。
  • 人机协同工具。 让用户上传图片、描述修改,并在你自己的界面里拿回结果。

不适合的场景

  • 像素级精确的修图或合成。这是生成式模型,不是栅格图像编辑器。
  • 完全没有参考图的情况——这种情况下文生图是更好的起点。
  • 任何要求仅凭指令承载全部细节的工作流;参考图在实际发挥作用,糟糕的参考图只会产生糟糕的结果。

把这个端点理解为 参考图 + 指令 -> 编辑后的图像。本教程的所有内容都建立在这个形态上:如何发送、如何读取返回的结果,以及当网络不配合时如何让它继续运行。

前置条件与认证设置

在第一次调用之前,准备好三件事。

1. 一个 HiAPI 账户

注册并打开控制台。本教程中的所有请求都通过 HiAPI 统一 API 发出,因此无需单独注册服务商,也无需为每个服务商安装 SDK。

2. 一个 API 密钥

在控制台创建一个 API 密钥。像对待密码一样对待它:不要提交到代码仓库,不要粘贴到客户端代码里,也不要记录到日志中。标准做法是在运行时从环境变量加载:

export HIAPI_API_KEY="your-api-key-here"

然后在需要密钥的地方引用 HIAPI_API_KEY。如果你部署到容器或无服务器平台,请在该环境中将其设置为机密,而不是烘焙进镜像里。

3. 一张可访问的参考图

该端点需要一张参考图,所以要事先决定如何提供它。两种常见方式:

  • 一个 URL,API 可以抓取,例如指向你自己对象存储的签名链接。
  • Base64 编码的字节,在请求体中内联发送,这样可以避免暴露内部 URL,但会增加载荷大小。

先挑一张小的测试图——几百 KB 就足以验证集成。大文件上传会拖慢每次重试,也让调试更困难。

检查点

现在你应当已经有一个存放在环境变量中的密钥,以及一张可以从本机访问的测试图。尽量让密钥不出现在 shell 历史中(由工具加载的 .env 文件通常比在命令行内联导出更干净)。

还有一个值得从现在开始养成的习惯:从第一天起就记录请求 ID 和耗时。当生产环境出问题时,可追踪的请求与不可追踪的请求之间的差别是巨大的。

构建请求:参考图与编辑指令

每次图生图调用都围绕两个输入构建。把这两项做对,其余都是管道工作。

输入一:参考图

参考图是锚点。它告诉模型在任何编辑之前场景包含什么、看起来如何。实用建议:

  • 匹配你想要的输出宽高比。 如果参考图是宽幅横图而你需要方形输出,根据调用配置的不同,预期会出现裁剪或变形。
  • 从一张干净、光照良好的图像开始。 浑浊的参考图会产生浑浊的编辑结果。
  • 最好只有一个清晰的主体。 杂乱的拼贴图会给模型太多相互竞争的锚点。

输入二:编辑指令

指令是对你想要的改动的自然语言描述。大多数质量差异就来自这里。把它当作附带了参考图的提示词。

  • 陈述改动,而不是整个场景。 “把背景换成纯白色影棚墙”要好于“白色背景上的产品”——后者会诱导模型重画一切。
  • 说明哪些必须保留。 诸如“保持主体的姿势和构图不变”这样的表述能显著减少漂移。
  • 具体说明风格和光线。 “柔和的阴天光线,低饱和色彩”比“让它更好看”给模型更多可用信息。
  • 避免矛盾。 如果参考图是白天的户外场景,而你要求夜晚的室内,就要预期模型会做出一个你可能不喜欢的判断。

请求体

你发给 flux-2/image-to-image 的请求包含模型标识符、参考图和指令。一个有用的心智模型:

{
  "model": "flux-2/image-to-image",
  "input": {
    "image": "<URL 或 base64 参考图>",
    "prompt": "<编辑指令>"
  }
}

如果你的参考图是 base64,按照请求 schema 构建为 data URI,或把原始编码与 MIME 类型一起传递。如果是 URL,请确保该链接在调用期间可公开访问——在请求中途过期的签名链接会产生难以理解的失败。

先迭代,再集成

在把任何东西接入代码之前,为同一张参考图写两三条指令并比较输出。当指令具体时,模型表现可预测;当指令含糊时,表现就不稳定;现在学到这一点比在生产中便宜得多。

一个可用的 curl 请求

验证密钥、参考图和指令最快的方式是一次 curl 调用。下面的示例假设你的密钥在 HIAPI_API_KEY 中,且参考图可通过 URL 访问。

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "image": "https://your-bucket.example.com/reference.jpg",
      "prompt": "把背景换成纯白色影棚墙。保持主体的姿势、构图以及主体上的光照不变。"
    }
  }'

有几点需要注意:

  • 密钥通过 Authorization 头作为 bearer 令牌传输。绝不要把它放进 URL。
  • Content-Type 是 JSON。 忘记设置它是导致令人困惑的 4xx 的常见原因。
  • 模型 id 放在请求体中,因此同一个端点可以通过改一个字段路由到其他模型。
  • 指令是完整句子,不是关键词列表。 这是有意为之——见上一节。

读取原始输出

先运行一次,在写任何解析代码之前查看整个响应。如果有帮助,可以用格式化工具处理:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

把请求体保存在文件(request.json)中比编辑 shell 引号字符串更容易迭代,而且它给你一个持久产物,日后可以用来复现 bug。

如果需要 base64 而非 URL

把 image 的值换成由你的文件构建的 data URI:

python - <<'PY'
import base64, json, pathlib
data = base64.b64encode(pathlib.Path("reference.jpg").read_bytes()).decode()
body = {
    "model": "flux-2/image-to-image",
    "input": {
        "image": f"data:image/jpeg;base64,{data}",
        "prompt": "让光线更温暖,并稍微降低对比度。",
    },
}
pathlib.Path("request.json").write_text(json.dumps(body))
PY

现在相同的 curl 调用就可以工作,因为载荷保存在 request.json 中。如果调用成功,你就拥有了转向 Python 所需的一切。

同样的调用在 Python 中

Python 版本刻意保持平淡:构建相同的字典,用相同的头发送,并把端点和模型放在常量中,这样就不会与 curl 版本产生漂移。

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "flux-2/image-to-image"


def edit_image(reference_url: str, instruction: str, timeout: float = 60.0) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # 未设置时立即失败
    payload = {
        "model": MODEL,
        "input": {
            "image": reference_url,
            "prompt": instruction,
        },
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = edit_image(
        "https://your-bucket.example.com/reference.jpg",
        "把背景换成纯白色影棚墙。"
        "保持主体的姿势、构图以及主体上的光照不变。",
    )
    print(result)

为什么这样组织

  • 用 os.environ["HIAPI_API_KEY"] 而非 .get(),这样缺失密钥会立即报错,而不是发送未认证的请求。
  • timeout 是显式的。 图像生成不是瞬时的;没有超时的请求最终会挂住工作进程。
  • 在解析之前调用 raise_for_status()。 你希望在 4xx 或 5xx 时得到异常,而不是在后续某处出现令人困惑的 KeyError。
  • 端点和模型是模块级常量,这让测试套件指向桩服务器变得轻松。

使用 base64 输入

如果你传递的是字节而非 URL,请在构建载荷的同一位置编码文件并构建 data URI:

import base64, pathlib

def as_data_uri(path: str, mime: str = "image/jpeg") -> str:
    raw = pathlib.Path(path).read_bytes()
    return f"data:{mime};base64," + base64.b64encode(raw).decode()

然后调用 edit_image(as_data_uri("reference.jpg"), instruction)。把编码步骤与请求函数分开,这样你就可以在不接触网络的情况下对校验和提示词组装进行单元测试。

解析响应

调用返回了一个 JSON 对象。现在以这样一种方式提取编辑后的图像:即便响应将来增加字段也不会出错。

先检查,而非假设

在开发期间导出一份原始响应,注意图像引用在哪里——通常嵌在结果结构中的 URL 或 base64 载荷。然后编写访问器,检查它是否存在,而不是直接深入嵌套键。

def extract_image_url(response: dict) -> str:
    data = response.get("data") or []
    if not data:
        raise ValueError(f"响应中没有图像数据:{response}")
    first = data[0]
    url = first.get("url") or first.get("b64_json")
    if not url:
        raise ValueError(f"无法识别的图像载荷:{first}")
    return url

这段代码中有两个值得保留的习惯:在错误消息中携带实际载荷大声失败,以及接受任一形态(URL 或 base64),而不是硬编码其中一种。响应格式会演进;宽容的读取器才能存活。

立即持久化

返回的 URL 可能是临时的。如果图像重要,请在同一个任务中下载它并存入你自己的存储桶:

def persist(url: str, dest: str) -> None:
    if url.startswith("data:"):
        header, b64 = url.split(",", 1)
        import base64, pathlib
        pathlib.Path(dest).write_bytes(base64.b64decode(b64))
        return
    with requests.get(url, stream=True, timeout=60) as r:
        r.raise_for_status()
        with open(dest, "wb") as f:
            for chunk in r.iter_content(1 << 16):
                f.write(chunk)

持久化还给你一个稳定的键可以记录到数据库中,这比存一个可能腐烂的链接有用得多。

校验你得到的东西

廉价的检查能发现昂贵的错误。确认文件非空、其魔数匹配某种图像格式,并可选地确认其尺寸符合预期。在边界处拒绝损坏或截断的图像,比把它提供给用户要好得多。

记录来源信息

把模型 id、指令文本、参考图键和时间戳与输出一起存储。当三周后有人问为什么某张图看起来是这样,那一行记录就是答案——而且它让重跑某个特定编辑变得轻而易举。

生产环境的重试与错误处理

图像生成调用失败的原因非常不同,把它们混为一谈是经典的生产 bug。

区分瞬时错误与最终错误

  • 瞬时——超时、连接重置、429 限流、5xx 响应。同样的请求在暂停后重试很可能成功。
  • 最终——400 无效请求、401 密钥错误或缺失、404 未知模型、载荷校验错误。重试这些浪费时间和金钱,并拖延真正的修复。

只重试第一类。对于第二类,立即让任务失败并暴露错误消息——它几乎总是准确告诉你哪个字段有问题。

带退避和抖动地重试

import random, time, requests

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_retries(fn, attempts: int = 5, base: float = 1.0):
    last = None
    for i in range(attempts):
        try:
            return fn()
        except requests.HTTPError as e:
            status = e.response.status_code if e.response is not None else None
            if status not in RETRYABLE:
                raise
            last = e
        except (requests.Timeout, requests.ConnectionError) as e:
            last = e
        delay = base * (2 ** i) + random.uniform(0, 0.5)
        time.sleep(delay)
    raise RuntimeError("重试次数已耗尽") from last

指数退避能防止你猛击一个已经吃力的服务;抖动能防止一批工作进程同步重试。始终限制尝试次数和总耗时——无界循环比干净失败更糟。

遵守限流

遇到 429 时,在退避之前遵守响应头中的任何重试提示。如果你在运行大批量任务,请在自己这一侧添加并发限制,而不是依赖服务器来给你节流。

让失败可见

  • 用唯一任务 id 标记重试,并记录每次尝试及其结果和耗时。
  • 为重试率发出指标;缓慢攀升是上游某处正在退化的早期预警。
  • 最后一次尝试失败后,把任务移到死信队列,并附上完整响应体,绝不只是“failed”这样的消息。

幂等性与成本合理性

重试的请求可能在服务器上已成功,即便你的客户端从未看到响应。如果你的产品无法容忍重复输出,请用你自己的 id 对任务做键,并在重试前进行对账。而且由于调用按使用计费,要提防重试循环悄悄放大开销——一个卡住并永远重试的消费者是这方面最昂贵的 bug。

常见陷阱与后续步骤

围绕 flux-2/image-to-image 的大多数集成痛点都来自一小串错误。在发布之前,对照这些检查你的代码。

  • 指令含糊。 “改进它”产生随机结果;“去掉招牌上的文字并保持招牌形状”产生可用的结果。具体性是质量上最大的杠杆。
  • 参考图不匹配。 错误的宽高比、模糊的源图或杂乱的拼贴图,不会因为提示词更好而得到挽救。
  • 过期的 URL。 在请求途中断掉的签名链接会导致看起来像服务器错误的失败。使用足够长的有效期,或改用 base64。
  • 硬编码响应结构。 直接深入嵌套键会把一个小的 schema 变更变成一次故障。使用带清晰错误的防御性提取器。
  • 没有超时。 缺失的超时会无限期占用一个工作进程,并掩盖真正的问题。
  • 重试最终错误。 400 不会自己修好。读一下消息。
  • 丢失输出。 如果返回的 URL 是临时的而你未持久化图像,你就什么都没有。
  • 粗心地记录机密和提示词。 密钥绝不能出现在日志中;用户提供的指令可能需要根据你的领域进行脱敏。

后续步骤

当单次调用流程稳固后,自然的扩展是:把调用包装成后台任务,让你的 UI 保持响应;存储指令/响应对,以便对提示词措辞做 A/B 测试;如果用户提供自己的图像,则在输入上添加审核或校验层。浏览 flux-2/image-to-image 的模型页面和 HiAPI 文档,看看你的用例接下来可能需要的参数。构建能起作用的最小东西,度量它,并让指令质量承担重任。

立即开始构建持久 AI 产物

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

阅读 API 文档