教程
如何通过 HiAPI API 使用 minimax-h3-image 文生图:curl 与 Python
本页内容
本教程涵盖什么,以及你需要先准备什么
本教程只讲一件具体的事:通过 HiAPI API 向 minimax-h3-image 文生图模型发送一条图像生成提示词,先做一次 curl 请求,再用一个可以放进应用里的小型 Python 函数实现。内容涵盖请求的结构、如何解读响应、错误如何显现,以及在生产环境上线前需要收紧哪些地方。
它刻意不涉及提示词工程理论、图像后处理或构建 UI。目标更聚焦:读完之后,你应当拥有一个可信的请求,并且清楚上一次它失败的确切原因。
前提条件
- 一个 HiAPI 账户。 在一切之前,你需要一个项目和一把 API 密钥——下面每个请求都需要鉴权。
- 把密钥存放在安全的地方。 把它放在环境变量(
HIAPI_API_KEY)里,而不是源码文件中,这样同一份代码在本地和 CI 中都能工作。 - 模型标识符。 本教程使用
minimax-h3-image及其text-to-image能力。请把模型名和任务路径都当作代码中的配置值,而不是散落各处的魔法字符串。 - 工具。 第一个请求用
curl,第二个用 Python 3.9+ 和requests。不需要其他库。 - 一种查看图像的方式。 你会读到一份响应负载,其中包含图像数据或对图像的引用——在假定任何 schema 之前,先手动检查一次响应字段。
现在就该养成的习惯
在你应用代码之外先生成第一个成功的请求。一条可用的 curl 命令就是基准真相:每当 Python 版本行为异常时,就拿它来对照。如果 curl 调用成功而 Python 不成功,问题就在你的客户端,而不是模型或网络。
用 curl 构建一个可用的文生图请求
从尽可能最小的请求开始,然后一次加回一个设置。生成请求由三部分组成:端点、鉴权头和 JSON 请求体。
请求
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": "亚麻桌布上的一只陶瓷碗,柔和的北窗光,50mm 镜头,浅景深",
"size": "1024x1024",
"n": 1
}'
那条命令里有三点需要注意:
- 密钥以 bearer token 的形式放在
Authorization头中传递。绝不要把它放在 URL 或请求体中,否则它会进入日志和 shell 历史记录。 model和task描述你想要什么——模型系列和能力。即使存在默认值,也要显式写出两者;显式请求更经得起时间考验。prompt是普通字符串。其他所有内容(size、n)都是图像设置,而不是对主体的描述。
解读响应
把输出通过格式化工具处理一下,这样你才能真正读懂它:
curl -s -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)——这样提示词保持可读,修改提示词也变成一行 diff,而不是一场引号猜谜。
在编写解析器之前先检查负载。注意图像是内联返回还是以 URL 返回,哪些字段携带图像标识符和任何修改后的提示词,以及响应是否包含用量元数据。把这些字段名记下来;你的 Python 客户端将依赖它们。
端到端确认整个流程
保存返回的图像,打开它,检查你要求的是否就是收到的。200 响应配上看似合理的 JSON 体,并不等于正确的图像——正是在这个节点,提示词和参数问题最容易被廉价地发现。
把请求翻译成 Python
现在移植完全相同的请求。保持平淡无奇:一个函数、显式超时、暂时不加隐藏的重试。
import os
import requests
HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
"""通过 HiAPI 使用 minimax-h3-image 生成图像。"""
payload = {
"model": "minimax-h3-image",
"task": "text-to-image",
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
ENDPOINT,
headers={
"Authorization": f"Bearer {HIAPI_API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=(5, 120), # 连接超时、读取超时
)
response.raise_for_status()
return response.json()
那个函数里有四个刻意的选择:
- 元组超时。 连接超时较短,因为连接建立缓慢意味着有问题;读取超时较宽松,因为图像生成本来就需要时间。单一超时值会迫使你只能在一个失败模式上做得不好。
json=payload。 让库来序列化请求体。手工拼接的 JSON 字符串正是引号 bug 的温床。- 解析前先
raise_for_status()。 状态检查不是可选项——把错误响应体当作成功来解析,是这类集成中最令人困惑的 bug 类型。 - 返回普通
dict。 你以后可以用类型化模型来装饰它;先确保你知道响应实际包含哪些字段。
把密钥查找隔离出来
如果变量缺失,os.environ["HIAPI_API_KEY"] 会立即抛出异常。这是有意为之:在启动时失败,而不是在第一个用户请求时失败。在更大的代码库中,在配置加载期间解析一次密钥,然后传递一个已配置的客户端,而不是在调用点读取环境变量。
接入运行
if __name__ == "__main__":
result = generate_image("退潮时潮湿海滩上空的一只红色风筝,阴天光线")
print(result)
运行它,并与 curl 的输出进行比较。负载结构应当一致。如果不一致,你就发现了一个值得在继续构建之前弄清楚的差异。
处理错误,而不是猜测
最常见的集成 bug 是重试一个永远不会成功的错误。把失败分成三类,并区别对待。
鉴权与授权失败
这类通常表现为 401 或 403。原因包括:缺少头、Bearer 前缀格式错误、密钥被撤销或配置错误,或者项目没有该模型的访问权限。它们不可重试。重试只会浪费时间,并用相同的失败污染日志。修好凭据然后继续。
请求校验失败
这类通常是 400 级别的响应:未知的 model 或 task 值、模型不支持的 size、n 超出范围、空提示词、格式错误的 JSON。它们同样不可重试——相同的请求会以相同方式失败。有用的工作是把错误信息原样呈现给编写该请求的开发者,而不是把它吞进一个通用异常里。
瞬态服务器与网络失败
429 和 5xx 响应,加上连接重置和读取超时,才是真正可重试的一类。用有上限的指数退避和抖动来处理它们:
import time, random, requests
def post_with_retry(session, url, payload, max_attempts=4):
for attempt in range(max_attempts):
try:
r = session.post(url, json=payload, timeout=(5, 120))
if r.status_code in (429, 500, 502, 503, 504):
raise requests.HTTPError(f"瞬态错误 {r.status_code}", response=r)
r.raise_for_status()
return r.json()
except (requests.ConnectionError, requests.Timeout, requests.HTTPError) as exc:
if attempt == max_attempts - 1:
raise
time.sleep(min(2 ** attempt + random.random(), 30))
两点提醒。第一,由非 429 的 4xx 引发的 HTTPError 必须立即向外抛出——不要让 except 子句吸收校验失败。第二,遵循响应中携带的任何重试指引,而不是自己发明延迟。
这里的重试不是幂等的
每一次重试的生成都是一次新的计费生成。如果请求超时,图像可能仍已被生成并计费。保持重试次数小,在日志中把尝试次数与请求元数据一起记录,并优先呈现明确的失败,而不是静默地把同一张图像生成四次。
提示词与参数的实用卫生习惯
这些习惯的意义在于可比较性:当你改变一件事时,你应当能判断输出变化是否是由它引起的。
编写点明画面内容的提示词
按主体、场景、光照、构图的顺序描述。具体的名词和摄影术语(如“柔和的北窗光”、“浅景深”)比堆叠美学形容词携带更多信号。避免大量使用否定的提示词;描述应当出现的内容。
一次只改一个变量
每个项目保留一个小型提示词文件,在运行之间编辑它,而不是从头重写。如果某次运行令人失望,要么改提示词,要么改设置——不要两个都改。否则你无法得知是哪个改动起了作用。
把设置当作显式契约
size 和 n 同时影响输出和成本。把它们固定在一个配置对象中,而不是把字面量穿到各个调用点,这样为整个功能更改宽高比就只是一次编辑。如果你需要多张图像做比较,在一次调用中请求它们,而不是分多次——往返更少,日志更易读。
把提示词与输出一起存储
在每张生成的图像旁边持久保存确切的提示词字符串、设置和模型标识符。无法复现的提示词,就是无法重新生成、调试或改进的图像。这一个习惯比任何提示词技巧都更省时间。
为比较设定种子
同一个提示词在不同运行之间可能产生不同的图像。当你在评估某个改动时,比较聚合结果——每种配置多张图像——而不是相信单个幸运或不幸的样本。
为提示词做版本管理
把提示词文本当作代码:保存在文件中,审查改动,并记录哪个提示词版本产生了哪个资产。这使“为什么上周二图像变差了?”成为一个可回答的问题。
上线前的生产检查清单
可用的请求只是容易的部分。下面这些检查区分了演示和集成。
- 每次调用都设置超时。 显式设置连接超时和读取超时,绝不用默认值。没有读取超时的生成端点最终会挂起一个 worker。
- 有上限的重试,只重试可重试错误。 限制尝试次数,加入抖动,并确保校验和鉴权失败完全绕过重试路径。
- 密钥管理。 从环境或密钥存储中读取密钥,绝不从源码读取。无需改代码即可轮换。
- 结构化日志。 记录模型标识符、提示词(或其哈希加引用)、设置、HTTP 状态、尝试次数,以及响应中的任何请求标识符。没有这些,图像问题将无法复现。
- 成本可见性。 生成按输出计费,所以用量取决于你要求多少张图像以及重试多频繁。提前确定请求是按用户、按任务还是后台执行,并相应地跟踪量——查看网站上实时的定价面板以获取当前费率,而不是硬编码假设。
- 定义失败行为。 决定在最终尝试后生成失败时用户会遇到什么:错误状态、占位符,还是排队重试。未定义的兜底会变成未定义的用户体验。
- 固定负载 schema。 存储并校验你依赖的响应字段,这样负载变化会以显式错误显现,而不是静默的
None。
最终验证环节
运行 curl 命令、Python 函数,以及一个故意损坏的请求(先坏密钥,再坏参数),确认每个都产生你预期的失败。最后这一步才能告诉你错误处理是真实的,而不是装饰性的。
请求已鉴权、已移植、已合理重试并已记录日志之后,这个集成就可以放在应用其余部分之后了。