教程
如何通过 HiAPI API 调用 flux-2/text-to-image:curl 与 Python 教程
可用的请求演练:模型标识符、提示词与宽高比参数、响应字段以及错误处理
本页内容
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 的全部意义。