博客

教程

如何通过 HiAPI API 调用 flux-2/text-to-image:curl 与 Python 教程

可用的请求演练:模型标识符、提示词与宽高比参数、响应字段以及错误处理

2026年11月12日
封面图:深靛蓝底色上层层嵌套的宽大箭头依次向右递进,前缘为杏橙色,扁平精确如信号流程图。
本页内容

flux-2/text-to-image 通过 API 暴露的内容

在写第一行代码之前,先弄清楚你究竟在接入什么会很有帮助。在 HiAPI 上,flux-2/text-to-image 并不是你要安装的单独 SDK,也不是需要单独鉴权的新服务。它是一个模型标识符,连同描述你想要画面的提示词一起,传给共享的图像生成端点。

这个心智模型很重要,因为它界定了集成的边界。你的代码需要三样东西:

  • 用于 HiAPI API 的鉴权凭证。
  • 接受图像生成请求的端点。
  • 包含 model(设为 flux-2/text-to-image)和 prompt 的 JSON 载荷。

其他一切——宽高比、输出偏好,以及模型暴露的任何其他旋钮——都作为附加字段存在于这个载荷中。这也是为什么从另一个文生图模型切换到 flux-2/text-to-image 通常只需修改一行配置,而非重写代码:请求信封保持不变,只有 model 的值变了。

端点接收你的请求,通过模型运行,然后返回包含生成图像(通常为 URL 或编码载荷)以及作业元数据的结构化响应。对于基本调用,你不需要轮询单独的作业队列——从客户端视角看,请求/响应周期是同步的,但底层生成仍然需要时间,因此你的 HTTP 客户端超时应该设置得较为宽松。

记住这个图景:一个端点、一个载荷、一个模型字符串。本教程的其余部分将填充载荷并加固调用。

用 curl 构建可用的请求

确认凭证和载荷结构正确的最快方式是一次 curl 调用。在碰 Python 之前先在终端获得一次成功响应——这能将认证和载荷问题与语言层面的 bug 隔离开来。

首先将密钥设为环境变量,这样它就不会以明文形式留在 shell 历史记录中:

export HIAPI_API_KEY="your_api_key_here"

然后发送请求:

curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "prompt": "a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
    "aspect_ratio": "16:9"
  }'

运行时需要检查的几点:

  • 端点和密钥来自你的 HiAPI 账户仪表盘。从仪表盘复制端点而非重新输入,可以避免最常见的静默失败——请求发到了意料之外的地方。
  • -sS 保持输出整洁,但仍会暴露 curl 层面的错误,如 DNS 或 TLS 失败。
  • Authorization 头使用标准 bearer 方案。变量展开周围没有尾随空格,也没有引号。
  • Content-Type: application/json 是必需的;没有它,请求体可能在模型看到之前就被拒绝。

如果调用成功,你会在终端看到 JSON 响应体。通过格式化器管道输出以提高可读性:

curl -sS -X POST "$HIAPI_IMAGE_ENDPOINT" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-2/text-to-image","prompt":"a red fox in fresh snow, eye level","aspect_ratio":"1:1"}' \
  | python3 -m json.tool

一旦这个能工作,你就有了一个已知良好的基线。之后 Python 中的任何失败都可以与这个你确认为有效的调用进行对比。

提示词与宽高比参数

有两个请求字段对输出的影响最大:prompt 和 aspect_ratio。一次只调整一个,否则你将无法判断是哪一个导致了你所看到的变化。

提示词

提示词是对图像的自然语言描述。把它写成紧凑的场景描述,而非关键词列表——大致按主体、场景、光照和构图的顺序。对比:

  • 模糊:a lighthouse
  • 具体:a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot

实验时保持措辞明确且稳定。如果你在同一轮迭代中重写提示词和宽高比,你就有了两个变量和一次观察。冻结提示词,一次调整一个词,并记录实际变化。

实用习惯:

  • 将最重要的主体放在字符串前部。
  • 用具体而非抽象的词语描述光照和氛围。
  • 在代码库中保留一小组参考提示词,并在更改其他任何内容时重新运行它们,这样你就能区分模型行为变化和提示词变化。

宽高比

aspect_ratio 控制输出的形状——宽幅用于风景和横幅,方形用于头像和缩略图,竖幅用于海报和移动端布局。模型接受诸如 16:9、1:1 或竖版等价物的比例字符串;使用模型文档中记录的比例,而非随意发明。

由于宽高比是单个离散字段,它是最容易扫描的参数。写一个循环,保持提示词不变,以三种比例请求同一图像,然后并排比较构图。你很快会了解哪些比例会裁切主体,哪些会给主体留出空间。

一个注意事项:宽高比改变的是有效构图,而不仅仅是画布。为宽幅镜头写的提示词在方形框架中可能显得单薄。确定比例后,重新审视一次提示词以作补偿。

将调用移植到 Python

curl 调用可以直接转换为 Python。目标是写一个小函数,接收提示词和宽高比,从环境读取密钥,返回解析后的 JSON——生产形态,而非一次性脚本。

import os
import requests

IMAGE_ENDPOINT = os.environ["HIAPI_IMAGE_ENDPOINT"]
MODEL = "flux-2/text-to-image"


def generate_image(prompt: str, aspect_ratio: str = "1:1", timeout: int = 120) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # fail fast if unset
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "aspect_ratio": aspect_ratio,
    }
    response = requests.post(
        IMAGE_ENDPOINT,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()

关于为何这样写的说明:

  • 使用环境变量,而非字面量。os.environ[...] 在变量缺失时立即抛出 KeyError,这远比发送空 bearer token 然后稍后解码令人困惑的认证错误要好。
  • json=payload 让 requests 为你序列化请求体并设置 Content-Type。不要手动构建 JSON 字符串。
  • 显式超时。图像生成不是即时的;默认客户端超时会在负载下给你带来麻烦。有意设置它。
  • raise_for_status() 将非 2xx 响应转换为可捕获和分类的异常,而非静默返回看起来像数据的错误体。

调用它:

result = generate_image(
    "a weathered lighthouse on a granite cliff at dawn, soft fog, wide shot",
    aspect_ratio="16:9",
)
print(result)

如果你更喜欢 httpx,形状完全相同——更换导入并保留相同的头、json= 载荷和超时参数。重要的是载荷,它与 curl 版本保持不变。

读取响应

成功调用返回一个 JSON 对象。与其猜测字段名,不如先检查一个真实响应,然后根据你实际看到的内容编写解析器。运行你的函数并打印顶层键:

result = generate_image("a red fox in fresh snow, eye level", "1:1")
print(result.keys())

你通常会使用的字段分为两组:

  • 图像本身。响应携带生成的图像——通常是你可下载或提供的 URL,有时是编码的图像数据。从你自己的响应中读取确切的字段名,存储该值,并根据其形式处理。如果是 URL,将其视为短期有效:及时下载或复制到你自己的存储,而不是将链接存入数据库并假设下个月仍然可解析。
  • 元数据。预期有描述生成过程的伴随字段——使用的模型、请求的宽高比或尺寸,以及请求的标识符。将它们与图像一起记录。当用户报告图像“看起来不对”时,元数据能告诉你哪个提示词和比例产生了它,而无需你从应用状态重新推导。

一个安全的提取模式:

image_ref = result.get("image") or result.get("data")
if not image_ref:
    raise ValueError(f"no image in response; keys={list(result.keys())}")

这是有意防御性的。字段名在模型内是稳定的,但将访问器写成以实际键列表大声失败的形式,可以避免静默的 None 传播到你的 UI。一旦从真实响应确认了字段名,就收紧代码直接读取它们。

最后,不要丢弃原始响应。在你的集成稳定之前存储它(或为部分请求记录日志)——当下游出现异常时,它是事实依据。

常见错误及修复方法

大多数首次运行的失败都属于少数几类。按 HTTP 状态类别处理它们,而非字符串匹配消息文本,后者会未经通知地变化。

认证失败(401 / 403)

密钥缺失、格式错误或缺少访问权限。按顺序检查:你的进程能看到的环境中是否确实设置了 HIAPI_API_KEY;头是否恰好是 Authorization: Bearer <key>,没有多余空白或包裹引号;你是否意外发送了来自不同环境的密钥。如果 curl 能工作而 Python 不能,打印你发送的头并逐字符比较。

载荷格式错误(400)

请求体在生成前被拒绝。常见原因:无效 JSON(手动构建的字符串带有尾随逗号)、缺少 prompt,或 Content-Type 错误。修复方法是在 Python 中使用 json=payload,在 curl 中使用带有效 JSON 的 -d。在日志中回显你即将发送的载荷,并像人一样阅读它。

不支持或无效的参数(400 / 422)

模型不接受的字段名或值——拼错的 aspect_ratio、模型未记录的比例,或从另一个模型示例复制的额外字段。将载荷缩减到最小(model、prompt),然后逐个添加字段以找出问题所在。

速率限制(429)

你发送请求的速度超过了账户限制允许的速度。这是暂时性的。不要在紧凑循环中重试——使用递增延迟和尝试上限进行退避。如果你在批处理,在调用之间添加小延迟,而非一次性全部发出。

服务器端错误(5xx)和超时

这些是暂时性的,超出你的控制。使用退避重试,并确保超时足够长,以免缓慢的生成被误分类为失败。在模型仍在工作时触发的读取超时会产生一次重试,浪费一个请求。

将分类放在一个地方可以保持可维护性:

def classify(status: int) -> str:
    if status in (401, 403):
        return "auth"        # fix config, do not retry
    if status in (400, 422):
        return "payload"     # fix request, do not retry
    if status == 429:
        return "rate_limit"  # retry with backoff
    if status >= 500:
        return "server"      # retry with backoff
    return "other"

为生产环境封装调用

上面的函数能工作,但真实集成需要三样它还没有的东西:区分暂时性和永久性失败的重试、反映现实的超时,以及让你能重建所发生情况的日志。一个小包装器覆盖这三者。

import logging
import time

log = logging.getLogger(__name__)

def generate_with_retry(prompt, aspect_ratio="1:1", attempts=3):
    delay = 1.0
    for attempt in range(1, attempts + 1):
        try:
            return generate_image(prompt, aspect_ratio)
        except requests.HTTPError as exc:
            status = exc.response.status_code
            kind = classify(status)
            log.warning("flux-2 call failed", extra={
                "attempt": attempt, "status": status,
                "kind": kind, "aspect_ratio": aspect_ratio,
            })
            if kind in ("auth", "payload"):
                raise  # retrying will not help
            if attempt == attempts:
                raise
            time.sleep(delay)
            delay *= 2

为何每一部分都有其价值:

  • 只重试可重试的。认证和载荷错误是确定性的——重试它们浪费时间并掩盖真正的 bug。速率限制、服务器错误和超时获得指数退避。
  • 记录结构化字段,而非散文。尝试次数、状态、错误类别和使用的参数让你之后能对失败进行分组。绝不要记录 API 密钥。
  • 限制尝试次数。无界重试循环会将一次故障变成挂起的工作进程。
  • 保持超时显式且宽松。从配置传入,这样你可以在已知的慢速时段提高它而无需修改代码。

另外两个有回报的习惯:为每个生成的图像持久化 (model, prompt, aspect_ratio) 的哈希,以便你能重现任何输出;在测试套件中保留一小组参考提示词,在对包装器做任何更改后运行它们。两者结合,将教程片段转变为可运维的东西。

请求形状确定、错误处理到位后,之后更换模型只需对 model 字段做一行更改——这正是通过统一接口调用 flux-2/text-to-image 的全部意义。

立即开始构建持久 AI 产物

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

阅读 API 文档