教程
如何通过 HiAPI API 调用 flux-2-klein-4b/text-to-image：curl、Python 与一个可用的请求
一份将经济型图像层级接入你的流水线的实操教程
为什么 flux-2-klein-4b/text-to-image 适合成本敏感型工作负载
并非每条图像流水线都需要目录中最重的模型。生产中很大一部分流量是重复性的：商品图、变体预览、商品列表缩略图、由同一模板生成的社交卡片。对于这些场景，flux-2-klein-4b/text-to-image 被设计为一个刻意更轻的层级——你用少许最高保真度换取吞吐量和可预测性，而在按计划批量生成数千个素材时，这通常是正确的取舍。
两类工作负载受益最大：
- 电商产品图像。 你通常有一份干净的基础描述（“哑光陶瓷马克杯，350ml，暖灰色，置于白色无缝背景上”），并需要生成覆盖颜色、角度和构图的大量渲染变体。一致性比艺术表现力更重要。
- 面向内部或长尾界面的批量生成。 类目横幅、A/B 测试创意、草稿列表的占位图——在这些素材上，边际的质量提升并不值得更重的运行成本。
当你制作的是主视觉图、精细纹理和构图本身就是产品时，选择更重的层级。当生成量、延迟和单图成本主导决策时，选择 flux-2-klein-4b/text-to-image。本教程余下部分将端到端地使用这一层级：请求结构、curl 调用、Python 辅助函数、宽高比策略以及异步生命周期。
发送请求之前的准备
首次调用之前，需要确定三件事。
1. 来自 HiAPI 的 API 密钥
在 HiAPI 控制台中创建密钥。这里描述的每个请求都用该密钥进行认证，而密钥是你唯一需要的凭据——没有单独的按模型注册流程。
2. 让密钥远离源代码管理
像对待任何其他机密一样对待密钥。一种行之有效的做法：
export HIAPI_API_KEY="your-key-here"
然后在 shell 和 Python 中从环境读取它。绝不要提交它，如果你使用 dotfile 加载器，请将 .env 添加到 .gitignore。如果密钥泄露，请在控制台中轮换它，而不是试图清理历史记录。
3. 确认模型标识符
标识符字符串会在请求体中原样使用，在某些配置中也会出现在 URL 中：
flux-2-klein-4b/text-to-image
请精确复制——4b 和 /text-to-image 后缀都是名称的一部分。这里的拼写错误是 404 或“unknown model”错误最常见的原因。一旦环境中有了密钥并确认了标识符，你就可以构建载荷了。
flux-2-klein-4b/text-to-image 请求的构成
HiAPI 上的文本生成图像请求刻意保持精简。你提供模型标识符和一组生成参数载荷；返回的要么是结果，要么是作业句柄，取决于该模型端点的配置方式。
最关键的字段
model— 精确的标识符，flux-2-klein-4b/text-to-image。prompt— 一个描述图像的字符串。这是对输出质量影响最大的字段；在改动其他任何内容之前，请把精力花在这里。- 尺寸或宽高比 — 你如何指定输出的取景。优先使用宽高比形式的规格，而不是硬编码的像素对，因为即使底层分辨率行为发生变化，它也能保持稳定。
响应长什么样
响应分为两种形态，你的客户端应同时处理两者：
- 同步式载荷 — 响应直接包含生成图像的位置（一个 URL）。
- 异步作业载荷 — 响应包含作业标识符和状态（
pending、processing、succeeded、failed是典型状态）。然后你用该标识符轮询状态端点，直到它达到终止状态且载荷携带输出位置。
不要发明你无法验证的参数。如果某个字段不属于该模型文档化的请求内容，就不要包含它——未知字段是令人困惑的 400 错误的第二常见来源。从 model、prompt 和宽高比开始，先获得一张可用的图像，然后逐一添加可选参数，并在每次改动后检查输出。
你的首次可用 curl 调用
下面是一个可以粘贴到终端中的完整请求。它假定 HIAPI_API_KEY 已按上述方式导出。
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-klein-4b/text-to-image",
"prompt": "Studio product photo of a matte ceramic mug, warm grey, soft diffused light, seamless white background, centered composition",
"aspect_ratio": "1:1"
}'
将其通过 JSON 格式化工具（| jq .）处理，以便读取响应。你会直接看到图像 URL，或者一个带有 id 和 status 的作业对象。
解读结果
- 如果得到图像 URL，在浏览器中打开它。这确认了密钥、模型标识符和提示词都正常工作。
- 如果得到作业对象，记下
id——你将在后面的章节中轮询它。
诊断常见故障
- 401 / 403 — 密钥缺失、格式错误，或未通过
Authorization: Bearer头传递。检查运行 curl 的 shell 中是否确实导出了环境变量。 - 404 或“unknown model” — 标识符错误。它必须正好是
flux-2-klein-4b/text-to-image。 - 带有验证消息的 400 — 通常是缺少
prompt、不支持的参数名，或不在接受集合中的宽高比。将载荷精简回三个核心字段并重试。 - 429 — 你的请求发送速度快于你的层级允许。添加退避，而不是在紧密循环中重试。
一旦 curl 正常工作，你就有了一个已知可用的请求，可以在 Python 版本出现问题时进行对照。
将同一请求移植到 Python
Python 版本是围绕同一载荷的薄封装。将其组织为函数，这样流水线的其余部分可以调用它，而无需重复 HTTP 逻辑。
import os
import time
import requests
API_BASE = "https://api.hiapi.ai/v1"
MODEL = "flux-2-klein-4b/text-to-image"
def generate_image(prompt: str, aspect_ratio: str = "1:1") -> dict:
"""Submit a text-to-image job and return the parsed response."""
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"model": MODEL,
"prompt": prompt,
"aspect_ratio": aspect_ratio,
}
response = requests.post(
f"{API_BASE}/images/generations",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
if response.status_code >= 400:
# Surface the server's message rather than a bare status code.
raise RuntimeError(f"HiAPI error {response.status_code}: {response.text}")
return response.json()
几个立即见效的习惯：
- 在函数内部从环境读取密钥，而不是在导入时，这样同一模块可以在 notebook、脚本和计划任务中通用。
- 显式检查状态码，并将响应体包含在异常中。HiAPI 的验证消息会告诉你哪个字段错误；裸的
raise_for_status()会隐藏这一点。 - 设置超时。 没有超时，停滞的连接可能无限期地挂起工作进程。
- 将载荷保持为 dict，这样你可以记录它、对比差异，并扩展可选参数，而无需重写字符串格式化。
现在是一个最小驱动程序：
result = generate_image(
"Studio product photo of a matte ceramic mug, warm grey, "
"soft diffused light, seamless white background, centered composition"
)
print(result)
选择经得起生产考验的宽高比
宽高比是最有可能在后期造成返工的参数，因为下游系统会假定取景。按界面逐一决定，而不是按请求决定。
实用的映射
- 正方形 (1:1) — 市场列表、商品网格、头像和缩略图位置。这是电商的安全默认值，因为大多数产品瓷砖是正方形的，裁剪效果很差。
- 竖版 (3:4 或 4:5) — 社交信息流位置和 lookbook 风格的产品图。为瓶子和服装等垂直产品提供空间而无需加黑边。
- 横版 (16:9) — 横幅、主视觉条、电子邮件页眉、视频缩略图。
为什么要在上游锁定比例
如果比例在渲染时由恰好调用 API 的代码选择，你会得到一个一半瓷砖是正方形、一半是竖版的商品目录，并且你需要支付一次重新生成来修复它。相反，将比例编码到你的内容模型中——一个确定性地映射到比例的 surface 或 placement 字段——并从该字段生成。可容忍裁剪的位置使用 1:1；具有固定布局的位置使用布局所要求的比例。
同样的纪律也适用于提示词：将取景提示（“居中构图”、“完整产品在画面内”、“左侧留白用于文案”）包含在提示词模板中，而不是临时的逐次调用字符串中。模板让一千张生成图像看起来像来自同一条流水线，而这正是产品目录所需要的。
一个注意事项：并非每个模型都接受每种比例。发送你选择的比例一次，确认成功，然后才在整个批次中推广。
轮询异步作业直至完成
当 flux-2-klein-4b/text-to-image 返回作业句柄而非图像时，将其视为状态机。流程是：提交 → 接收作业 ID → 轮询状态 → 终止状态 → 读取输出。
def wait_for_job(job_id: str, timeout_s: int = 300, interval_s: int = 2) -> dict:
api_key = os.environ["HIAPI_API_KEY"]
deadline = time.time() + timeout_s
while time.time() < deadline:
response = requests.get(
f"{API_BASE}/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
response.raise_for_status()
job = response.json()
status = job.get("status")
if status == "succeeded":
return job
if status == "failed":
raise RuntimeError(f"Job {job_id} failed: {job.get('error')}")
time.sleep(interval_s)
raise TimeoutError(f"Job {job_id} did not finish in {timeout_s}s")
处理每种状态
pending/processing— 继续等待。以较短的间隔开始，并考虑温和的退避（例如，将睡眠时间增长到上限），以免在长队列期间频繁冲击状态端点。succeeded— 载荷现在包含输出位置。立即停止轮询。failed— 不要盲目重试。记录错误消息；如果是提示词或参数问题，重新提交相同的请求会以相同方式失败。
知道何时停止
始终用挂钟截止时间约束循环。永远轮询的工作进程是泄漏的工作进程。超时时，暴露作业 ID 以便手动检查——如果作业后来成功，你仍然可以检索输出。对于批次，并发运行多个作业并一起轮询它们，而不是为每张图像串行化提交和等待。
下载并存储输出
生成的图像以可检索的位置出现在作业或生成响应中。在服务器端获取它，然后自行持久化——不要将返回的 URL 热链接到产品页面中，因为它是交付产物，而不是你的存储层。
def download_image(url: str, path: str) -> str:
response = requests.get(url, timeout=120)
response.raise_for_status()
with open(path, "wb") as f:
f.write(response.content)
return path
使用可预测的命名方案
像 images/{surface}/{sku}/{variant}-{ratio}.png 这样的路径给你三样东西：素材按产品自然分组，界面告诉你请求的是哪种取景，文件名中的比例使意外的重复项显而易见。如果你重新生成同一 SKU 的变体，请在文件名中包含提示词的短哈希——这样重新运行就不会悄悄覆盖你可能想对比的先前尝试。
闭环
将作业 ID 与存储的文件一起记录，记录在清单、数据库行或附属文件中。当下游系统报告图像不佳时，作业 ID 是让你能取回原始提示词和参数的东西。结合内容寻址的文件名，这为你提供了从存储的素材回溯到产生它的确切请求的可复现审计轨迹。
将提交、轮询和下载连接在一起后，flux-2-klein-4b/text-to-image 就成为你流水线中的普通一步：排队工作、带截止时间轮询、用稳定名称存储。从那里开始，扩展只是并发和模板的问题，而不是新代码。
