教程
如何通过 HiAPI API 调用 qwen-image-3.0-pro/image-to-image:curl、Python 与一次可用的请求
一份集成演练,涵盖异步任务模式、curl 与 Python 客户端,以及错误处理
本页内容
为什么图像生图(image-to-image)是异步任务
当你调用一个图像生图模型时,你并不是在请求一个能在几百毫秒内流式返回的字符串补全结果。模型需要加载你的源图像,以它为条件运行完整的扩散式生成流程,并对输出进行编码。这可能需要几秒到几十秒不等,且时长会随分辨率和设置而变化。在整个窗口期内保持 HTTP 连接打开对各方都不划算:代理会超时,负载均衡器会丢弃空闲套接字,你自己的工作线程也会被钉在一个可能稍后仍会失败的请求上。
因此该端点采用“先提交、再轮询”模型。你的第一个请求提交一个任务,并立即返回一个任务句柄。图像生成在该句柄背后进行。随后你发起独立的、开销很低的请求来检查任务状态,直到它报告完成,此时响应会携带你所请求的结果。
这有一些实际的后果,你应该从一开始就将其纳入设计:
- 提交不等于完成。 提交调用成功仅意味着平台接受了你的任务,仅此而已。在代码中要将这两种状态区分开来。
- 任务 ID 是你唯一的句柄。 要持久化保存它。如果你的进程在提交与轮询之间崩溃,任务 ID 就是你无需重新提交(并再次付费)同样的工作即可恢复的依据。
- 轮询开销低但并非免费。 状态检查很轻量,但紧凑的循环仍会产生流量,并可能触发速率限制。要拉开间隔。
- 失败是异步到达的。 损坏的图像或被拒绝的参数可能会以任务级错误的形式出现,而不是提交时的 HTTP 错误。你的轮询代码必须读取任务状态,而不仅仅是状态码。
记住这个模型,后面的集成就会很直接:一次调用创建工作,一个循环等待它,以及对可能出错的三种情况做有意的处理。
写代码之前:需要准备什么
在接触终端之前,先收集本指南中每次调用都依赖的几样东西。
HiAPI 凭据
你需要一个 HiAPI 的 API 密钥。把它当作机密:从环境变量加载,而不是粘贴进你可能提交的脚本里。下面的示例将其读取为 HIAPI_API_KEY。API 的基础 URL 和确切的模型标识符 qwen-image-3.0-pro/image-to-image 是你全程要引用的两个常量。
一张源图像
图像生图需要输入。准备好一张,并决定如何提供它:
- 作为可公开访问的 URL,或者
- 作为已上传的资产或编码后的载荷,取决于端点接受哪种形式。
在编写调用之前,查阅模型的请求 schema,确认确切的字段名和可接受的源图像格式。提供端点不接受的源图像是任务被拒绝的最常见原因,而且提前排除它比从错误信息中去调试要容易得多。
一个能轮询的客户端
由于调用是异步的,你用来发送请求的工具也需要能够反复发出后续请求。curl 适合做首次冒烟测试;任何更长期的用途都应该是脚本。没有需要配置的回调 URL,也没有需要托管的 webhook——轮询就是机制,所以要规划一个循环。
一个查看结果的地方
提前决定对你来说“完成”是什么样子:一个你可以在浏览器中打开的 URL,或者你写入磁盘的字节。在开始前知道这一点,就能在集成真正可用时一目了然。
手头有了这四样东西,第一个请求就很简短了。
用 curl 发送一次可用的请求
确认你的密钥、端点和任务生命周期都能工作的最快方式,是一次两步的 curl 会话。首先提交;然后轮询。
第 1 步:提交任务
curl -sS -X POST "$HIAPI_BASE_URL/qwen-image-3.0-pro/image-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/source.jpg",
"prompt": "restyle as a soft watercolor illustration"
}'
逐项说明:
-X POST—— 提交是一个创建操作。Authorization头携带你的密钥。通过导出环境变量而不是内联输入,可以避免它留在 shell 历史中。Content-Type: application/json—— 请求体是 JSON。-d—— JSON 载荷。image字段指向你的源图像,prompt描述要执行的变换。参数名和可接受的选项来自模型的请求 schema;请在那里核对,而不要猜测。
提交成功的响应是一个任务对象。它会包含一个标识符——称之为任务 ID——以及一个状态字段,应表明任务已排队或正在运行。记下任务 ID;后续一切都依赖它。
第 2 步:轮询任务
export TASK_ID="<the id from the submit response>"
curl -sS "$HIAPI_BASE_URL/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
每次调用时,读取状态字段。当它报告待处理或运行状态时,等待几秒再检查。当它报告成功时,响应包含生成的图像——通常是可获取的 URL,或编码后的数据。当它报告失败时,响应携带解释原因的错误描述。
整个生命周期就是如此:一次提交,然后状态检查直到终态。之后你构建的任何东西,都只是这两条命令的更方便版本,加上等待和错误处理。
用 Python 实现同样的调用
手工重复这两个 curl 步骤很快就会让人厌烦,而把轮询循环复制粘贴到每个脚本里,正是微妙 bug 扩散的方式。将提交和轮询的模式包装成一个可复用的函数。
import os
import time
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL_PATH = "/qwen-image-3.0-pro/image-to-image"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def submit_task(source_image: str, prompt: str) -> str:
resp = requests.post(
BASE_URL + MODEL_PATH,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image": source_image, "prompt": prompt},
timeout=30,
)
resp.raise_for_status()
return resp.json()["id"]
def wait_for_task(task_id: str, poll_interval: float = 3.0,
max_wait: float = 300.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
resp = requests.get(
f"{BASE_URL}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
resp.raise_for_status()
task = resp.json()
status = task["status"]
if status == "succeeded":
return task
if status == "failed":
raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
time.sleep(poll_interval)
raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")
def generate(source_image: str, prompt: str) -> dict:
task_id = submit_task(source_image, prompt)
return wait_for_task(task_id)
有几处刻意的选择值得指出:
- 将提交与等待分离。 如果提交失败,你在任何轮询发生之前就能知道。如果你以后想在一个进程中提交、在另一个进程中收集,接缝已经存在。
- 每个请求都有
timeout。 没有超时的请求可能会无限期挂起,这正是异步 API 本应帮你避免的失败模式。 - 轮询循环既有间隔也有整体截止时间。 没有截止时间,一个卡在运行状态的任务会永远循环。没有间隔,你会猛打端点。
- 状态字符串是显式匹配的。 任何既不是成功也不是失败的状态都会落入下一次迭代,这对中间状态是正确的默认行为。
像调用任何函数一样调用它:generate(source_url, "make the background a dusk cityscape")。返回的对象是终态任务载荷,从中提取图像引用。
处理错误与失败的任务
异步工作流中的错误分为三类,每一类都需要不同的应对。
请求级拒绝
这些是提交调用的普通 HTTP 错误响应——凭据错误或缺失、JSON 格式错误、不支持的参数、无法访问的源图像。它们在任何任务存在之前到达。
正确的应对几乎总是停下来并呈现消息。重试格式错误的载荷只会浪费配额和时间。逐字记录状态码和响应体;验证消息通常会指出有问题的字段。有两种情况值得特别处理:认证失败应快速且响亮地失败,因为它们意味着配置问题;速率限制响应可以在退避后重试。
任务级失败
这里提交成功了,任务 ID 存在,但工作失败了。轮询响应报告失败状态并附带错误。
这一类涵盖模型自身的问题:源图像能解码但不可用、提示词被拒绝、生成触达内部限制。由于这些与输入特定相关,盲目重试通常会复现同样的失败。逐个情况决定:暂时的内部错误可能值得重试一次;被拒绝的源图像永远不值得。将任务 ID 与错误一起记录,以便与支持请求关联。
永不结束的轮询
提交成功,任务存在,轮询在运行——但终态始终不到达。这不是平台返回的错误;这是你代码中的一个假设,必须过期。
用截止时间来防护它,如 Python 示例所示。当截止时间触发时,停止轮询。不要静默返回半完成的结果;抛出或返回一个明确的超时结果,让调用方决定。保留任务 ID——任务可能仍在你的截止时间之后完成,你可能想稍后收集它而无需重新提交。
对这三类情况的实用经验法则:将任务状态视为唯一真相源。HTTP 状态码告诉你请求是否被接受;任务的状态和错误字段告诉你工作是否成功。同时读取两者,失败就变得可诊断,而不是神秘莫测。
将其包装进生产代码
上面的函数是一个可用的集成,而不是一个完成的服务。在它承载真实流量之前,要收紧四件事。
处处有超时
为每次调用设置明确的连接和读取超时——提交、轮询,以及任何对结果图像的后续获取。然后为整个任务生命周期设置整体截止时间。HTTP 层的超时保护单个请求;任务截止时间保护整个操作。
有判断力的重试
只重试可以安全重试的内容。轮询时的速率限制和暂时性网络错误符合条件。被拒绝的载荷不符合。对于任务级失败,重试意味着提交新任务,这与重试状态检查是不同且更昂贵的操作——要将其作为有意的决定,最好有上限。
包含任务 ID 的日志
在提交时以及随后的每次状态转换时记录任务 ID,连同时间信息。提交与首次终态之间的间隔是当事情感觉慢时你实际会想要的指标。当用户报告糟糕的结果时,任务 ID 是将轶事转化为可追溯记录的关键。
让轮询远离请求路径
如果你的函数运行在 Web 处理程序内,同步轮询循环会在整个生成时间内保持请求打开——这正是异步设计要避免的问题。相反,在处理程序中提交,将任务 ID 返回给调用方,并在后台工作进程、队列或计划任务中执行等待。然后客户端轮询你的服务,而不是模型。
按这个顺序构建,集成就会从“在我的机器上能用”变成你可以依赖的东西:提交,持久化句柄,带限制地等待,让任务状态——而不是希望——告诉你何时停止。