教程
如何在 hiapi 上用 curl 和 Python 调用 minimax-h3-image 图生图
本页内容
图生图端点期待什么
在写任何代码之前,先了解图生图调用的结构会很有帮助。minimax-h3-image 图生图端点接收你的参考图(一张或多张)以及一段文本提示词,返回一张遵循提示词、同时锚定于参考图的全新生成结果。
从概念上讲,每个请求包含三部分:
- 模型路由——你用
image-to-image任务来寻址minimax-h3-image,全部通过单一的 hiapi 端点完成。你不需要为每种能力准备单独的凭证或主机。 - 输入——一个提示词字符串、一张或多张参考图(URL 或 base64 载荷),以及分辨率档位等生成控制项。
- 输出契约——调用是异步的。你会拿回一个任务标识符,然后轮询状态,并在任务完成时获取生成的图片 URL。
最后一点很重要。图生图并不是一个在同一次响应里就给你像素的阻塞式调用。把提交调用视为“将作业入队”,并且从一开始就围绕任务生命周期来设计客户端。如果你先按同步行为设计,后面就不得不重写集成代码。
由于一切都经由同一个 hiapi 接口流转,请求头、鉴权和响应封装在各模型与任务之间保持一致。为 minimax-h3-image 学一次,同样的模式就适用于平台上的其他地方。
一个最小可运行请求
从能证明你的凭证、端点和载荷结构都正确的最小请求开始。不要急于一开始就加上所有可选字段。
最小请求体包含:
- 模型名
minimax-h3-image - 任务类型
image-to-image - 一段描述你想要何种转换的
prompt - 单个参考图字段
- 一个分辨率档位
从概念上看,载荷大致如下:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "把这张草图变成白底上干净的产渲染图",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
发送它,确认返回了任务 id,然后手动轮询一两次,观察状态转换。如果拿到了任务 id,说明连通性和鉴权都没问题,你可以继续构建真正的客户端了。如果没有,就停下来读错误响应体——它通常会直接指出出问题的字段。
把这个请求保存为冒烟测试。当后续的改动弄坏你的流水线时,重跑这个最小请求就能立刻告诉你,问题出在你的载荷还是周边的代码。
用 curl 调用
curl 是查看原始请求和响应的最快方式。把 JSON 请求体写到文件里,这样编辑时就不必和 shell 引号较劲。
cat > payload.json <<'JSON'
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "把这张照片改成水彩插画风格",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
JSON
curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
--data @payload.json
两个请求头承担了主要职责:带 bearer token 的 Authorization 和 Content-Type: application/json。两者都要远离版本控制——从环境变量读取密钥,而不是把它粘贴到命令里。
提交成功时,捕获返回的任务 id 并轮询它:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
响应中有一个状态字段,完成后还有结果。用 jq 只提取你关心的字段:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .result'
这也是调试载荷最简单的方式:curl 会准确显示你发送了什么、又返回了什么,没有任何内容被客户端库隐藏。
用 Python 调用
Python 版本应当镜像 curl 流程:提交、捕获 id、轮询直到终态、获取结果。使用 requests 和 Session,这样连接复用和默认请求头只需处理一次。
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
def submit(prompt: str, image: str, resolution: str = "1024") -> str:
body = {
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": prompt,
"image": image,
"resolution": resolution,
},
}
resp = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()["id"]
def poll(task_id: str, timeout: float = 300, interval: float = 2.0) -> dict:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
resp = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"任务 {task_id} 未在 {timeout} 秒内完成")
if __name__ == "__main__":
task_id = submit(
"把这张图片变成扁平矢量海报",
"https://example.com/reference.png",
)
print("已提交:", task_id)
result = poll(task_id)
print(result)
关键细节:raise_for_status() 把 HTTP 错误变成异常,而不是静默失败;轮询循环同时有截止时间与间隔;终态是显式判断的。只有在状态到达终态之后才从结果对象中解析图片 URL,绝不能提前。
使用多张参考图
单张参考图往往不够。你可能想保留一张照片中的人脸,同时借用另一张的构图,或者融合一种质感和一个轮廓。Minimax-h3-image 图生图通过复数形式的 image 字段支持多参考输入。
结构上,input 对象可以用 image 字段承载单张参考图,当你有多张时用 images 数组:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "保留第一张图中的人物,使用第二张图的背景风格",
"images": [
"https://example.com/person.png",
"https://example.com/background.png"
],
"resolution": "1024"
}
}
顺序是有含义的。参考索引 0 是你的主要对象,后面的条目是辅助上下文,因此提示词的表述要与你发送的顺序一致。如果得到的结果忽略了某张参考图,通常的原因是提示词有歧义,而不是字段坏了——让提示词明确说出哪张图决定哪个属性。
多参考工作的实用规则:
- 数量保持精简。 只用特定提示词真正需要的参考图;额外添加会稀释控制力。
- 尽量匹配宽高比,这样模型不必去调和相互冲突的构图。
- 在同一个请求中一致地使用公共 URL 或 base64,不要混用传输方式。
在集成期间发送一次双图请求,验证两张参考图都明显影响了输出,然后再在其上构建更复杂的逻辑。
选择分辨率档位
resolution 字段为 minimax-h3-image 图生图选择输出档位。它不只是一个外观上的旋钮——它改变计算量、响应延迟,以及你最终要处理的载荷大小。
如何权衡:
- 选满足目标场景的最小档位。 列表视图的缩略图不需要和主视觉横幅相同的档位。事后再对高分辨率输出做降采样,既浪费时间又浪费钱。
- 预期延迟随分辨率增长。 更高档位每次请求做更多工作,所以你的轮询超时和间隔预算应反映所选档位。
- 关注载荷大小。 base64 参考输入和高分辨率输出都会增大传输体积;如果你要搬运大量图片,要留意请求与响应体。
计费跟随你请求的分辨率档位——请求按其运行档位计价,因此在小用例上使用过大的档位会悄悄多花钱。请查看定价面板上的实时费率,而不是硬编码假设。
合理的集成策略是:开发阶段使用中等档位以换取速度,等提示词和参考图集确定后,再把关键资产提升到更高档位。较晚更改分辨率会让你的延迟测量失效,所以要在你实际打算上线的档位上做基准测试。
处理异步生命周期
hiapi 上的每次图生图调用都遵循同一个循环:提交、捕获任务 id、轮询直到终态、然后获取结果。让这个循环健壮,就是生产级客户端的大部分工作。
提交并记录
把任务 id 当作你的持久句柄。提交响应一到就立刻记录它,再做其他任何事——如果进程在轮询途中崩溃,这个 id 能让你恢复而不是重新生成。
带退避地轮询
固定两秒轮询对交互式使用没问题,但对长批次很浪费。从较短间隔开始并逐渐增大,同时给最大间隔设上限,这样你仍能及时检测到完成。
def next_interval(current: float, cap: float = 15.0, factor: float = 1.5) -> float:
return min(current * factor, cap)
尊重终态
只在成功或失败时退出循环。把任何非空响应都当作“完成”是最常见的异步 bug——你会去读取尚不存在的结果。
给一切设边界
为每次 HTTP 调用设置超时,并为任务设置总体截止时间。如果截止时间过去,抛出清晰的错误,而不是一直空转。对于瞬时网络错误,用退避重试轮询;不要盲目重新提交,那会造成重复工作。
清理
一旦获取到结果,及时把图片 URL 或字节持久化到你自己的存储。任务结果是临时句柄,不是你应用的长期 CDN。
故障排查与生产检查清单
这些是开发者使用 minimax-h3-image 图生图时最先遇到的失败,以及防止它们的检查项。
首次运行失败
- 401 / 403——bearer token 缺失、过期,或带有前后空白字符。确认运行请求的 shell 中已导出该环境变量。
- 422 或校验错误——检查错误响应体;它通常会指出字段。常见原因是把
prompt放在顶层而不是input内部。 - JSON 格式错误——发送前用
jq .校验你的载荷文件。
运行时失败
- 任务永不完成——确认你轮询时用的是实际收到的 id,而不是占位符。检查你的截止时间对所选分辨率档位是否足够长。
- “完成”任务的结果为空——精确读取状态字段;失败状态也会返回响应体。
- 参考图被忽略——在归咎于模型之前,先复查提示词措辞和参考图顺序。
上线前检查清单
- API 密钥和基础 URL 从环境变量读取,绝不提交到仓库。
- 每次 HTTP 调用都有显式超时。
- 轮询使用有界退避,并带硬性的总体截止时间。
- 终态被显式处理;不会落入结果解析分支。
- 结果由你的应用下载并存储,而不是从任务响应热链接。
- 多参考提示词写明哪张图控制哪个属性。
- 分辨率档位在你打算上线的取值上做过基准测试。
- 日志记录任务 id,以便失败作业可追踪、可恢复。
每当出问题时,就重跑前面那个最小请求——它能隔离出问题出在你的载荷还是周边代码。有了请求结构、curl 与 Python 客户端、多参考处理以及有纪律的轮询循环,你就具备了在 hiapi 上可靠上线 minimax-h3-image 图生图所需的一切。